slacktivate.slack package¶

Submodules¶

slacktivate.slack.classes module¶

This submodule provides a commong abstraction layer over the heterogeneous object types provided by the Slack API client and the Slack SCIM client modules.

class slacktivate.slack.classes.SlackGroup(group_id=None, display_name=None, group=None, resource=None)¶

Bases: object

property created¶

property display_name¶

property exists¶

classmethod from_any(value)¶

Parameters: value (Optional[Union[str, slack_scim.v1.group.Group, slack_scim.v1.users.Group]]) –
Return type: Optional[slacktivate.slack.classes.SlackGroup]

classmethod from_display_name(display_name)¶

Parameters: display_name (str) –
Return type: slacktivate.slack.classes.SlackGroup

classmethod from_group(group)¶

Parameters: group (Union[slack_scim.v1.group.Group, slack_scim.v1.users.Group]) –
Return type: slacktivate.slack.classes.SlackGroup

classmethod from_id(group_id)¶

Parameters: group_id (str) –
Return type: slacktivate.slack.classes.SlackGroup

classmethod from_string(string)¶

Parameters: string (str) –
Return type: slacktivate.slack.classes.SlackGroup

get_members_as_users()¶

Return type: Optional[List[slacktivate.slack.classes.SlackUser]]

property id¶

property member_ids¶

property members¶

refresh()¶

Return type: bool

class slacktivate.slack.classes.SlackGroupMember(*args, **kwargs)¶

Bases: dict

display: str¶

value: str¶

slacktivate.slack.classes.SlackGroupTypes¶

This is a type annotation to describe all the data types supported by the to_slack_group() method:

a string (a Slack group ID or group display name as described in more detail in the documentation for SlackGroup.from_string()),
a slack_scim.Group object, from the Slack API package,
an existing SlackGroup object.

alias of Union[str, slack_scim.v1.group.Group, slack_scim.v1.users.Group, slacktivate.slack.classes.SlackGroup]

class slacktivate.slack.classes.SlackUser(user_id=None, username=None, email=None, user=None, resource=None)¶

Bases: object

This is a wrapper class to abstract the concept of Slack user across the various vendor-provided packages

property active¶

property email¶

property emails¶

property exists¶

classmethod from_any(value)¶

Parameters: value (Optional[Union[str, slack_scim.v1.user.User]]) –
Returns
Return type: Optional[slacktivate.slack.classes.SlackUser]

classmethod from_email(email)¶

Creates a SlackUser wrapper object, given an email address.

Note

This is an internal package method that does not do any validation, and can result in SlackUser representing non-existent users. Use the higher-level to_slack_user() method to do user validation.

Parameters: email (str) – A Slack user ID
Returns: A SlackUser object
Return type: slacktivate.slack.classes.SlackUser

classmethod from_id(user_id)¶

Creates a SlackUser wrapper object, given a Slack user ID.

Note

This is an internal package method that does not do any validation, and can result in SlackUser representing non-existent users. Use the higher-level to_slack_user() method to do user validation.

Parameters: user_id (str) – A Slack user ID
Returns: A SlackUser object
Return type: slacktivate.slack.classes.SlackUser

classmethod from_string(string)¶

Creates a SlackUser wrapper object, given a string that may represent either:

a Slack user ID (alphanumeric string beginning by W or U as described in the Slack API documentation),
an email (string with no spaces containing an @),
or a Slack username.

Note

This is an internal package method that does not do any validation, and can result in SlackUser representing non-existent users. Use the higher-level to_slack_user() method to do user validation.

Parameters: string (str) – A string
Returns: A SlackUser object
Return type: slacktivate.slack.classes.SlackUser

classmethod from_user(user)¶

Creates a SlackUser wrapper object, given a non-null slack_scim.User object.

Parameters: user (slack_scim.v1.user.User) – A slack_scim.User object
Returns: A SlackUser object
Return type: slacktivate.slack.classes.SlackUser

classmethod from_username(username)¶

Creates a SlackUser wrapper object, given a Slack username.

Note

This is an internal package method that does not do any validation, and can result in SlackUser representing non-existent users. Use the higher-level to_slack_user() method to do user validation.

Parameters: username (str) – A Slack user ID
Returns: A SlackUser object
Return type: slacktivate.slack.classes.SlackUser

property fullname¶

property id¶

property image_url¶

refresh()¶

Return type: bool

property scim_obj¶

property username¶

slacktivate.slack.classes.SlackUserTypes¶

This is a type annotation to describe all the data types supported by the to_slack_user() method:

a string (an email, or a Slack user ID or username as described in more detail in the documentation for SlackUser.from_string()),
a slack_scim.User object, from the Slack API package,
an existing SlackUser object.

alias of Union[str, slack_scim.v1.user.User, slacktivate.slack.classes.SlackUser]

slacktivate.slack.classes.lookup_group_by_display_name(display_name)¶

Parameters: display_name (str) –
Return type: Optional[slack_scim.v1.group.Group]

slacktivate.slack.classes.lookup_group_by_id(group_id)¶

Parameters: group_id (str) –
Return type: Optional[slack_scim.v1.group.Group]

slacktivate.slack.classes.lookup_user_by_email(email)¶

Returns the internal slack_scim.User object for a Slack user in the currently logged-in workspace, given one of that user’s emails; if the email does not correspond to an existing user, returns None. This query is live.

Parameters: email (str) – An email address
Returns: A slack_scim.User object or None
Return type: Optional[slack_scim.v1.user.User]

slacktivate.slack.classes.lookup_user_by_id(user_id)¶

Returns the internal slack_scim.User object for a Slack user in the currently logged-in workspace, given that user’s Slack ID; if the Slack user ID does not correspond to an existing user, returns None. This query is live.

Parameters: user_id (str) – A Slack user ID
Returns: A slack_scim.User object or None
Return type: Optional[slack_scim.v1.user.User]

slacktivate.slack.classes.lookup_user_by_username(username)¶

Returns the internal slack_scim.User object for a Slack user in the currently logged-in workspace, given that user’s username; if the username does not correspond to an existing user, returns None. This query is live.

Parameters: username (str) – A Slack username
Returns: A slack_scim.User object or None
Return type: Optional[slack_scim.v1.user.User]

slacktivate.slack.classes.to_slack_group(value, only_existing=True)¶

Parameters

value (Optional[Union[str, slack_scim.v1.group.Group, slack_scim.v1.users.Group, slacktivate.slack.classes.SlackGroup]]) –
only_existing (bool) –

Return type

Optional[slacktivate.slack.classes.SlackGroup]

slacktivate.slack.classes.to_slack_user(value, only_existing=True)¶

Parameters

value (Optional[Union[str, slack_scim.v1.user.User, slacktivate.slack.classes.SlackUser]]) –
only_existing (bool) –

Returns

Return type

Optional[slacktivate.slack.classes.SlackUser]

slacktivate.slack.clients module¶

This submodule

slacktivate.slack.clients.SLACK_TOKEN = '<SLACK TOKEN>'¶

In order to use the Slack SCIM API, you need to be an owner of the workspace, and obtain an API token with admin scope.

As explained in the official Slack SCIM API documentation, the easiest way to obtain a valid token for the purposes of SCIM provisioning is as follows:

As a Workspace/Organization Owner, create a new app for your workspace (see here for the documentation).
Add the admin OAuth scope to the “User Token Scopes” section.
Install the app to your workspace (see here for the documentation).
Use the generated token in the “OAuth & Permissions” tab (if you are provided with multiple tokens, use the “OAuth Access Token” not the “Bot User OAuth Access Token”).

Note that you can easily reinstall your app with different permissions if it turns out you did not select all the necessary permissions.

slacktivate.slack.clients.api(token=None, force_login=False, update_global=None)¶

Parameters

token (Optional[str]) –
force_login (bool) –
update_global (Optional[bool]) –

Return type

slack.web.client.WebClient

slacktivate.slack.clients.login(token=None, silent_error=False, update_global=True)¶

Returns a pair containing a logged-in Slack API and Slack SCIM API client.

Parameters

token (Optional[str]) – A valid Slack OAuth token (if none is provided, will try to obtain it from the environment)
silent_error (bool) – Flag whether to silently fail when no valid token is available or not
update_global (bool) – Flag whether to update the global clients with the result of this operation (useful to globally change which workspace is being affected by this library)

Returns

A pair containing a properly logged-in Slack API client and Slack SCIM API client

Return type

Tuple[slack.web.client.WebClient, slack_scim.v1.client.SCIMClient]

slacktivate.slack.clients.managed_api(token=None, patch_reply_exception=True)¶

Parameters

token (Optional[str]) –
patch_reply_exception (bool) –

Return type

AbstractContextManager[slack.web.client.WebClient]

slacktivate.slack.clients.managed_scim(token=None, patch_reply_exception=True)¶

Parameters

token (Optional[str]) –
patch_reply_exception (bool) –

Return type

AbstractContextManager[slack_scim.v1.client.SCIMClient]

slacktivate.slack.clients.scim(token=None, force_login=False, update_global=None)¶

Parameters

token (Optional[str]) –
force_login (bool) –
update_global (Optional[bool]) –

Return type

slack_scim.v1.client.SCIMClient

slacktivate.slack.exceptions module¶

class slacktivate.slack.exceptions.SlackExceptionHandler(client, patch_reply_exception=True)¶

Bases: contextlib.ExitStack

static wrap(client, patch_reply_exception=True)¶

Parameters

client (Union[slack_scim.v1.client.SCIMClient, slack.web.client.WebClient]) –
patch_reply_exception (bool) –

Return type

slacktivate.slack.exceptions.SlackExceptionHandler

slacktivate.slack.exceptions.handle_slack_errors(exc_val, exc_type=None, exc_tb=None)¶

Parameters

exc_val (Exception) –
exc_type (Optional[Type]) –
exc_tb (Optional[traceback]) –

Return type

bool

slacktivate.slack.methods module¶

This submodule provides an intermediate abstraction layer to the methods provided by the Slack API and Slack SCIM API. This layer handles certain errors (such as rate-limiting exceptions), uses the wrapper classes defined in slacktivate.slack.classes, and provides a coherent, predictable syntax to do typical, elementary administrative operations on the logged-in Slack workspace.

slacktivate.slack.methods.channel_create(name, is_private=False, return_id=True)¶

Parameters

name (str) –
is_private (bool) –
return_id (bool) –

Return type

Optional[Union[str, Dict[str, Any]]]

slacktivate.slack.methods.channels_list(by_id=False, only_name=False)¶

Parameters

by_id (bool) –
only_name (bool) –

Return type

Optional[Dict[str, Dict[str, Any]]]

slacktivate.slack.methods.conversation_member_ids(conversation_id)¶

Parameters: conversation_id (str) –
Return type: List[str]

slacktivate.slack.methods.group_create(display_name)¶

Parameters: display_name (str) –
Return type: Optional[slacktivate.slack.classes.SlackGroup]

slacktivate.slack.methods.group_ensure(display_name, user_ids=None, remove_unspecified_members=True)¶

Parameters

display_name (str) –
user_ids (Optional[List[str]]) –
remove_unspecified_members (bool) –

slacktivate.slack.methods.group_patch(group, changes)¶

Parameters

group (Union[str, slack_scim.v1.group.Group, slack_scim.v1.users.Group, slacktivate.slack.classes.SlackGroup]) –
changes (dict) –

Return type

Optional[slacktivate.slack.classes.SlackGroup]

slacktivate.slack.methods.list_custom_profile_fields(index_by_label=False, silent_error=True)¶

Returns a dictionary of all the custom profile fields defined in the currently logged-in Slack workspace (custom fields are only available in Slack Plus and above plans).

By default, the dictionary is indexed by the fields internal ID:

{
    'Xf01AVK94ASU': {
        'id': 'Xf01AVK94ASU',
        'ordering': 0,
        'field_name': None,
        'label': 'Pronouns',
        'hint': 'E.g.: she/her/hers, he/him/his, they/them/theirs, ze/zim/zirs, ...',
        'type': 'text',
        'possible_values': None,
        'options': None,
        'is_hidden': False
    }
    ...
}

For more information, see Slack’s documentation of the API method.

Parameters

index_by_label (bool) – Flag to indicate whether the returned dictionary should be indexed by the label, rather than the ID
silent_error (bool) – Flag to indicate whether to silently suppress any unexpected error and return an empty dictionary in that case

Raises

If silent_error is False, may raise a slack.errors.SlackApiError

Returns

The dictionary mapping a field ID to the internal dictionary defining a custom Slack profile field

Return type

Dict[str, str]

slacktivate.slack.methods.make_user_dictionary(attributes, include_naming=True, include_image=True, include_fields=True)¶

Returns the payload to update a Slack user’s profile; this is an internal method, that is only useful to make calls directly to the Slack API client.

Parameters

attributes (dict) – A dictionary mapping the profile customized fields to their content for a given user
include_naming (bool) – Flag determining whether to include the naming attributes (such as name, displayName, nickName)
include_image (bool) – Flag determining whether to include the profile image
include_fields (bool) – Flag determining whether to include customized profile fields (as processed by the method make_user_extra_fields_dictionary())

Returns

A dictionary representing the payload to update a Slack user’s profile

Return type

Optional[dict]

slacktivate.slack.methods.make_user_extra_fields_dictionary(attributes)¶

Returns the payload to update a Slack user’s customized profile fields; this is an internal method, that is only useful to make calls directly to the Slack API client.

This method expects to provided a dictionary attributes, mapping the customized fields to the their value, such as:

{
    "Degree": "Ph.D.",
    "GitHub": "https://github.com/jlumbroso/",
}

Internally, a cache is maintained containing the result of a call to list_custom_profile_fields(), which allows this payload to be built by translating the labels into their corresponding field IDs.

The resulting payload might be:

{
    "Xf01957FNX4N": { "value": "Ph.D.", "alt":"" },
    "Xf019AHU8MJ9": { "value": "https://github.com/jlumbroso/", "alt":"" },
}

Parameters: attributes (dict) – A dictionary mapping the profile customized fields to their content for a given user
Returns: A dictionary representing the payload to update a Slack user’s customized profile fields
Return type: Dict[str, Any]

slacktivate.slack.methods.team_access_logs(before=None, count=None, user=None, users=None, page_shifting=True)¶

Parameters

before (Optional[int]) –
count (Optional[int]) –
user (Optional[Union[str, slack_scim.v1.group.Group, slack_scim.v1.users.Group, slacktivate.slack.classes.SlackGroup]]) –
users (Optional[List[Union[str, slack_scim.v1.group.Group, slack_scim.v1.users.Group, slacktivate.slack.classes.SlackGroup]]]) –
page_shifting (bool) –

slacktivate.slack.methods.user_activate(user)¶

Ensures an existing Slack user is active.

Parameters: user (slacktivate.slack.classes.SlackUserTypes) – A valid user object
Returns: True if the status of the user is active
Return type: bool

slacktivate.slack.methods.user_create(attributes)¶

Creates a new Slack user, based on the provided attributes, using Slack SCIM API provisioning.

Note

Only the userName and emails attributes are required to create a user.

Parameters: attributes (dict) – A (possibly nested) dictionary containing the attributes for the user to be created
Returns: A valid Slack user, if successful
Return type: Optional[slacktivate.slack.classes.SlackUser]

slacktivate.slack.methods.user_deactivate(user)¶

Ensures an existing Slack user is deactivate.

Parameters: user (slacktivate.slack.classes.SlackUserTypes) – A valid user object
Returns: True if the status of the user is active
Return type: bool

slacktivate.slack.methods.user_image_set(user, image_url)¶

Parameters

user (Union[str, slack_scim.v1.user.User, slacktivate.slack.classes.SlackUser]) –
image_url (str) –

Return type

Optional[slacktivate.slack.classes.SlackUser]

slacktivate.slack.methods.user_patch(user, changes)¶

Patch an existing Slack user, as provided by the user parameter, with modifications provided in the changes parameter.

slacktivate.slack.retry module¶

This submodule contains a few helper methods that provide a decorator slack_retry() that handles all the rate-limiting API exceptions that are raised by the Slack API and Slack SCIM API packages. This helps streamline the composition of more complex macros.

slacktivate.slack.retry.DEFAULT_SECONDS_TO_WAIT: int = 20¶: Default number of seconds to wait when a rate limiting exception is thrown by the Slack API or Slack SCIM API, but without a valid Retry-After header.

slacktivate.slack.retry.slack_do_we_give_up(err)¶

Parameters: err (Union[slack.errors.SlackApiError, slack_scim.v1.errors.SCIMApiError, Exception]) –
Return type: bool

slacktivate.slack.retry.slack_retry(target)¶

@slack_retry: This is a decorator to automatically handle the Slack vendor exceptions, slack.errors.SlackApiError and slack_scim.SCIMApiError when it is caused by a rate-limiting error (as described in the Slack API documentation and the Slack SCIM API documentation. When such an exception is thrown, this decorator will pause for an unspecified, random amount of time and retry the exact same method call.

Module contents¶

This submodule contains all the code that interacts directly with the Slack API and Slack SCIM API official Python SDKs.