slacktivate.macros package¶
Submodules¶
slacktivate.macros.manage module¶
This submodule contains a number of high-level macros that assist in complicated, multi-step tasks to be applied on Slack objects.
-
class
slacktivate.macros.manage.
UserMergeOptionsType
(value)¶ Bases:
enum.Enum
Enumeration class of the different possibilities for merging user attributes in the
user_merge()
method.-
KEEP_FROM
= 'keep-from'¶ Keep the attributes of the user specified as
user_from
.
-
KEEP_LEAST_FREQUENT_LOGIN
= 'least-freq-login'¶ Keep the attributes of the user that has least frequently logged into Slack.
-
KEEP_LEAST_RECENTLY_ACCESSED
= 'least-recent'¶ Keep the attributes of the least recently accessed user account.
-
KEEP_MOST_FREQUENT_LOGIN
= 'most-freq-login'¶ Keep the attributes of the user that has most frequently logged into Slack.
-
KEEP_MOST_RECENTLY_ACCESSED
= 'most-recent'¶ Keep the attributes of the most recently accessed user account.
-
KEEP_NEWEST
= 'newest'¶ Keep the attributes of the most recently created user account (in other words, the newest).
-
KEEP_OLDEST
= 'oldest'¶ Keep the attributes of the least recently created user account (in other words, the oldest).
-
KEEP_TO
= 'keep-to'¶ Keep the attributes of the user specified as
user_to
.
-
-
slacktivate.macros.manage.
UserMergeType
¶ This is a type to specify the different possibilities for merging user attributes in the
user_merge()
method. The values can either be taken from the enumeration classUserMergeOptionsType
, be a string, or be None (in which case a default decision will be made).alias of Optional[Union[str, slacktivate.macros.manage.UserMergeOptionsType]]
-
slacktivate.macros.manage.
user_access_count
(user, force_refresh=None)¶ Returns the number of times the user logged into Slack.
There is no way to access the logs randomly, therefore this method relies on a local cache of the full team access logs. This means that the first call to this method may take some time while the access logs are loaded using an internal call to
slacktivate.slack.methods.team_access_logs()
; and the data may be slightly out of date (a refresh of the data can be forced by settingforce_refresh
toTrue
).- Parameters
user (
slacktivate.slack.classes.SlackUserTypes
) – A valid Slack userforce_refresh (bool) – Flag determining whether to flush the cache
- Returns
The total number of accesses a user has made (or -1 if user is not found)
- Return type
int
-
slacktivate.macros.manage.
user_access_earliest
(user, force_refresh=None)¶ Returns the user’s earliest recorded login to the Slack workspace.
Like the other methods related to access logs, such as
user_access_logs()
, this method relies on an internal cache that can be controlled with the parameterforce_refresh
.- Parameters
user (
slacktivate.slack.classes.SlackUserTypes
) – A valid Slack userforce_refresh (bool) – Flag determining whether to flush the cache
- Returns
The Unix timestamp of the earliest recorded login for the user
- Return type
int
-
slacktivate.macros.manage.
user_access_latest
(user, force_refresh=None)¶ Returns the user’s most recently recorded login to the Slack workspace.
Like the other methods related to access logs, such as
user_access_logs()
, this method relies on an internal cache that can be controlled with the parameterforce_refresh
.- Parameters
user (
slacktivate.slack.classes.SlackUserTypes
) – A valid Slack userforce_refresh (bool) – Flag determining whether to flush the cache
- Returns
The Unix timestamp of the most recently recorded login for the user
- Return type
int
-
slacktivate.macros.manage.
user_access_logs
(user, force_refresh=None)¶ Returns a list of the access logs for the requested user.
An individual access log entry can aggregate multiple events or represent a single event (this depends on the value of
count
), for example, the following entry represents a single event:{ "user_id": "UTZLJA2JK", "username": "lumbroso", "date_first": 1603940797, "date_last": 1603940797, "count": 1, "ip": "96.248.68.184", "user_agent": "ApiApp/A0104EA0FPD Python/3.8.5 slackclient/2.9.3 Darwin/19.6.0", "isp": "", "country": "", "region": "" }
There is no way to access the logs randomly, therefore this method relies on a local cache of the full team access logs. This means that the first call to this method may take some time while the access logs are loaded using an internal call to
slacktivate.slack.methods.team_access_logs()
; and the data may be slightly out of date (a refresh of the data can be forced by settingforce_refresh
toTrue
).- Parameters
user (
slacktivate.slack.classes.SlackUserTypes
) – A valid Slack userforce_refresh (bool) – Flag determining whether to flush the cache
- Returns
A list of all available access logs for the user
- Return type
Optional[List[dict]]
-
slacktivate.macros.manage.
user_merge
(user_from, user_to, merge_account=None, merge_username=None, merge_primary_email=None, force_refresh=None)¶ Merges two Slack users into one, combining the attributes using a set of automated rules.
- Parameters
user_from (
slacktivate.slack.classes.SlackUserTypes
) – A valid useruser_to (
slacktivate.slack.classes.SlackUserTypes
) – Another valid usermerge_account (
UserMergeType
) – Determines which account to keep; by default keep the oldest,UserMergeOptionsType.KEEP_OLDEST
merge_username (
UserMergeType
) – Determines which username to keep; by default keep the newest,UserMergeOptionsType.KEEP_NEWEST
merge_primary_email (
UserMergeType
) – Determines which primary email to keep; by default keep the newest,UserMergeOptionsType.KEEP_NEWEST
force_refresh (bool) – Flag determining whether to flush the cache
- Returns
If successful, the merged user, otherwise
None
- Return type
Optional[slacktivate.slack.classes.SlackUser]
slacktivate.macros.provision module¶
This submodule contains a number of high-level macros that focus on the provisioning/deprovisioning of Slack users, in particular using the Slack SCIM API.
-
slacktivate.macros.provision.
channels_ensure
(config, remove_unspecified_members=None, dry_run=False)¶ - Parameters
config (slacktivate.input.config.SlacktivateConfig) –
remove_unspecified_members (Optional[bool]) –
dry_run (bool) –
- Return type
Optional[Dict[str, str]]
-
slacktivate.macros.provision.
groups_ensure
(config, remove_unspecified_members=None, dry_run=False)¶ - Parameters
config (slacktivate.input.config.SlacktivateConfig) –
remove_unspecified_members (Optional[bool]) –
dry_run (bool) –
- Return type
Dict[str, slacktivate.slack.classes.SlackGroup]
-
slacktivate.macros.provision.
users_deactivate
(config, only_active=False, dry_run=False)¶ Deactivates all users that are not described in the provided
config
parameter of typeSlacktivateConfig
.- Parameters
config (slacktivate.input.config.SlacktivateConfig) – A
SlacktivateConfig
object storing the compiled Slacktivate specification for this workspaceonly_active (bool) – Flag to only update users that are currently active
dry_run (bool) – Flag to only return users to be deactivated, rather than taking the action of deactivating them
- Returns
If
dry_run
is set toTrue
, then the list ofSlackUser
of the users to be deactivated; otherwise a tuple summarizing the number of users that were examined, that were to be deactivated, and that were successfully deactivated- Return type
Tuple[List[slacktivate.slack.classes.SlackUser], Tuple[int, int, int]]
-
slacktivate.macros.provision.
users_ensure
(config, dry_run=False, iterator_wrapper=None)¶ Ensures that all users specified by the provided Slackativate configuration,
config
, have been provisioned and are active in the Slack workspace.This method does nothing to deactivate users that are not specified in the configuration—this is handled by a separate method,
users_deactivate()
.- Parameters
config (slacktivate.input.config.SlacktivateConfig) – A
SlacktivateConfig
object storing the compiled Slacktivate specification for this workspacedry_run (bool) – Flag to only return users to be created, rather than taking the action of creating them
iterator_wrapper (Optional[Callable[[Iterator], Iterator]]) – Optional iterator wrapper, to post-process the pairs of
(email, user attributes)
in some way before that information is used to create users
- Returns
If
dry_run
is set toTrue
, returns a dictionary mapping primary emails to the Slack payload that will be used to create the user; otherwise, returns a dictionary mapping emails to the created user objects- Return type
Union[Dict[str, Dict[str, Any]], Dict[str, slacktivate.slack.classes.SlackUser]]
-
slacktivate.macros.provision.
users_iterate
(only_active=True, only_email=False, no_bots=True, refresh=None)¶ Returns an iterator over the existing users in the Slack workspace.
This method uses an internal caching mechanism that can be bypassed with the parameter
refresh
or by calling the internal method_refresh_users_cache()
.This method is implemented using a collection of related internal methods, and should be the main mechanism by which to iterate over users.
- Parameters
only_active (bool) – Flag to only return active users
only_email (bool) – Flag to iterate over emails, not
(email, user)
pairsno_bots (bool) – Flag to filter out bot users
refresh (Optional[bool]) – Flag to force a refresh of the cache
- Returns
An iterator over the existing users in the Slack workspace, either over a sequence of
str
representing emails (ifonly_email
is set toTrue
) or a pair ofstr
andslacktivate.slack.classes.SlackUser
representing, respectively, the primary email and the user object.- Return type
Union[KeysView[str], ItemsView[str, slacktivate.slack.classes.SlackUser]]
-
slacktivate.macros.provision.
users_list
(only_active=True, only_email=False, no_bots=True, as_dict=None, refresh=None)¶ Returns a list (or dictionary) of the existing users in the Slack workspace.
This method uses an internal caching mechanism that can be bypassed with the parameter
refresh
or by calling the internal method_refresh_users_cache()
.This method is implemented using a collection of related internal methods, and should be the main mechanism by which to iterate over users.
- Parameters
only_active (Optional[bool]) – Flag to only return active users
only_email (bool) – Flag to iterate over emails, not
(email, user)
pairsno_bots (bool) – Flag to filter out bot users
as_dict (bool) – Flag to determine whether to return a list or dictionary
refresh (bool) – Flag to force a refresh of the cache
- Returns
A list of emails, or
(email, user)
pairs; or a dictionary mapping emails to users, of the existing users in the Slack workspace.- Return type
Union[List[str], List[Tuple[str, slacktivate.slack.classes.SlackUser]], Dict[str, slacktivate.slack.classes.SlackUser]]
-
slacktivate.macros.provision.
users_update
(config, overwrite_name=None, overwrite_image=None, dry_run=False, iterator_wrapper=None)¶ Updates the profile information of users specified by the provided Slackativate configuration,
config
, of which the accounts have already been created.This method does not create new users (which can be done with
users_ensure()
) or deactivate existing users (which can be done withusers_deactivate()
), it only modifies profile attributes.- Parameters
config (slacktivate.input.config.SlacktivateConfig) – A
SlacktivateConfig
object storing the compiled Slacktivate specification for this workspaceoverwrite_name (Optional[bool]) – Flag to determine whether to allow this method to overwrite customized names set by the user
overwrite_image (Optional[bool]) – Flag to determine whether to allow this method to overwrite customized profile images set by users
dry_run (bool) – Flag to only return users whose profile will be modified, rather than taking the action of modifying them
iterator_wrapper (Optional[Callable[[Iterator], Iterator]]) – Optional iterator wrapper, to post-process the pairs of
(email, user attributes)
in some way before that information is used to update user profiles
- Returns
A dictionary of mapping primary emails to the user objects for the modified users
- Return type
Dict[str, slacktivate.slack.classes.SlackUser]