dkutils.gmail_api.gmail_client module¶

exception dkutils.gmail_api.gmail_client.GmailClientException[source]¶: Bases: Exception

class dkutils.gmail_api.gmail_client.GMailClient(credentials: google.oauth2.credentials.Credentials)[source]¶

Bases: object

Client object for access the GMail API. The create_base64_encoded_token function can be used to initially create a set of credentials which are base64 encoded in a file that can be looded into vault. This value from vault can then be used as an environment variable in a variation. The get_object_from_environment can be used to reconstitute the credentials from the environment variable.

Parameters: credentials (Credentials) – the credentials needed to access the API

__init__(credentials: google.oauth2.credentials.Credentials)[source]¶

Client object for access the GMail API. The create_base64_encoded_token function can be used to initially create a set of credentials which are base64 encoded in a file that can be looded into vault. This value from vault can then be used as an environment variable in a variation. The get_object_from_environment can be used to reconstitute the credentials from the environment variable.

Parameters: credentials (Credentials) – the credentials needed to access the API

has_approval(subject, approval_string='Approved', sleep_seconds=10, max_wait=30)[source]¶

This function can be used to determine if a response has been received containing the specified approval string. The given subject is used to retrieve messages of interest. This function will poll for new email every sleep seconds until the max wait seconds have been exceeded.

Parameters

subject (str) – The subject to use to retrieve messages from the inbox
approval_string (str, opt) – If the message body of a message retrieved starts with the given string True will be returned by the function indicating that approval has been received. Will default to Approved if not specified
sleep_seconds (int, opt) – Number of seconds to wait between retrieving email. If not specified will default to 10
max_wait (int, opt) – The maximum number of seconds to wait for approval to be recieved. If not specified will default to 30

Returns

True or False with True indicating that approval has been received

Return type

bool

send_message(message, user_id='me')[source]¶

Send an email message.

Parameters

message (str) – The message to be sent
user_id (str, optional) – User’s email address. The special value “me” will be used to indicate the authenticated user if no value is provided

Returns

The sent message

Return type

dict

class dkutils.gmail_api.gmail_client.Scope(value)[source]¶

Bases: enum.Enum

An enumeration.

BASIC = 'https://www.googleapis.com/auth/gmail.settings.basic'¶

COMPOSE = 'https://www.googleapis.com/auth/gmail.compose'¶

FULL = 'https://mail.google.com/'¶

INSERT = 'https://www.googleapis.com/auth/gmail.insert'¶

LABELS = 'https://www.googleapis.com/auth/gmail.labels'¶

METADATA = 'https://www.googleapis.com/auth/gmail.metadata'¶

MODIFY = 'https://www.googleapis.com/auth/gmail.modify'¶

READ_ONLY = 'https://www.googleapis.com/auth/gmail.readonly'¶

SEND = 'https://www.googleapis.com/auth/gmail.send'¶

SHARING = 'https://www.googleapis.com/auth/gmail.settings.sharing'¶

dkutils.gmail_api.gmail_client.create_base64_encoded_token(credentials_path: pathlib.Path, token_path: pathlib.Path, scopes: typing.List[dkutils.gmail_api.gmail_client.Scope] = [<Scope.READ_ONLY: 'https://www.googleapis.com/auth/gmail.readonly'>])[source]¶

This will use the provided Path for the json.credentials file and create a token with the scopes provided and base64 encode it at the path specified. The base64 encoded file can then be loaded into vault for use by other methods in this library. When you run this function keep in mind that a browser window will be opened for you to authorize access.

Parameters

credentials_path (Path) – The path to the file containing the credentials. To create this file follow the instructions found at https://developers.google.com/gmail/api/quickstart/python Under Step1: Turn on the GMAIL API
token_path (Path) – The path to the file that will contain the base64 encoded token that can uploaded to vault.
scopes (list, optional) – A list containing the requested scopes. See https://developers.google.com/gmail/api/auth/scopes for a list of the scopes. Will default to [Scope.READ_ONLY]

dkutils.gmail_api.gmail_client.create_message(sender, to, subject, message_text)[source]¶

Create a message for an email.

Parameters

sender (str) – Email address of the sender.
to (str) – Email address of the receiver.
subject (str) – The subject of the email message.
message_text (str) – The text of the email message.

Returns

An object containing a base64url encoded email object.

Return type

object

dkutils.gmail_api.gmail_client.create_message_with_attachment(sender, to, subject, message_text, file)[source]¶

Create a message for an email.

Parameters

sender (str) – Email address of the sender.
to (str) – Email address of the receiver.
subject (str) – The subject of the email message.
message_text (str) – The text of the email message.
file (str) – The path to the file to be attached.

Returns

An object containing a base64url encoded email object.

Return type

object

dkutils.gmail_api.gmail_client.get_object_from_environment(environment_variable_name)[source]¶

This function will get an object that has been pickled and base64 encoded from an environment variable with the specified name. This was intended to be used for retrieving the credentials for using the GMail API from an environment variable but it can be used to retrieve any python object that has been pickled and base64 encoded as an environment variable.

Parameters: environment_variable_name (str) – A string specifying the name of the environment variable containing the object.
Return type: object