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 class UserMergeOptionsType, 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 setting force_refresh to True).

Parameters
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 parameter force_refresh.

Parameters
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 parameter force_refresh.

Parameters
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 setting force_refresh to True).

Parameters
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
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
Return type

Optional[Dict[str, str]]

slacktivate.macros.provision.groups_ensure(config, remove_unspecified_members=None, dry_run=False)
Parameters
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 type SlacktivateConfig.

Parameters
  • config (slacktivate.input.config.SlacktivateConfig) – A SlacktivateConfig object storing the compiled Slacktivate specification for this workspace

  • only_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 to True, then the list of SlackUser 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 workspace

  • dry_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 to True, 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) pairs

  • no_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 (if only_email is set to True) or a pair of str and slacktivate.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) pairs

  • no_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 with users_deactivate()), it only modifies profile attributes.

Parameters
  • config (slacktivate.input.config.SlacktivateConfig) – A SlacktivateConfig object storing the compiled Slacktivate specification for this workspace

  • overwrite_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]

Module contents