Reference

Core module - f451_comms.comms

f451 Communications module.

This module acts as a common interface to several communications modules and its main purpose is to make it easy to send messages to several communications channels at the same.

An application can send a message via email, Twitter, Slack, and Twilio (SMS) using the send_message() method. It is also possible to send messages via a specific channel using the send_message_via_<channel>() methods.

Note

  • Store secrets (e.g. API keys, etc.) in a separate configuration file.

  • Store defaults (e.g. default channels and recipients, etc.) in a separate configuration file.

  • Use .ini files that can be parsed by the Python ConfigParser (see example files)

class f451_comms.comms.Comms(config=None)

Main class for f451 Communications module.

Use this main class as default interface to send messages to any of the installed/enabled communications channels.

All available channels and associated attributes (e.g. API keys, etc.) are defined during initialization of the class.

Parameters

config (Any) –

Return type

None

config

set of attributes for ‘secrets’ such as API keys, general attributes, and default settings

property Mailgun: Optional[Union[f451_comms.providers.mailgun.Mailgun, f451_comms.providers.slack.Slack, f451_comms.providers.twilio.Twilio, f451_comms.providers.twitter.Twitter]]

Return ‘Mailgun’ client.

property Slack: Optional[Union[f451_comms.providers.mailgun.Mailgun, f451_comms.providers.slack.Slack, f451_comms.providers.twilio.Twilio, f451_comms.providers.twitter.Twitter]]

Return ‘Slack’ client.

property Twilio: Optional[Union[f451_comms.providers.mailgun.Mailgun, f451_comms.providers.slack.Slack, f451_comms.providers.twilio.Twilio, f451_comms.providers.twitter.Twitter]]

Return ‘Twilio’ client.

property Twitter: Optional[Union[f451_comms.providers.mailgun.Mailgun, f451_comms.providers.slack.Slack, f451_comms.providers.twilio.Twilio, f451_comms.providers.twitter.Twitter]]

Return ‘Twitter’ client.

property channel_map: Optional[Union[configparser.ConfigParser, Dict[str, str], Dict[str, Any], List[str]]]

Return ‘channel_map’ property.

property channels: Optional[Union[configparser.ConfigParser, Dict[str, str], Dict[str, Any], List[str]]]

Return ‘channels’ property.

property default_channels: Optional[Union[configparser.ConfigParser, Dict[str, str], Dict[str, Any], List[str]]]

Return ‘default_channels’ property.

is_enabled_channel(inChannels)

Check if communications channel is enabled.

Parameters

inChannels (Optional[Union[str, List[str]]]) –

Return type

bool

is_valid_channel(inChannels)

Check if communications channel is valid.

Parameters

inChannels (Optional[Union[str, List[str]]]) –

Return type

bool

process_channel_list(inList, strict=False)

Process list of channel names and convert them to list of strings.

The purpose of this method is to process a list with one or more channel names and placing them into a list.

Parameters

  • inList (Optional[Union[str, List[str]]]) – Single string or list with one or more strings

  • strict (bool) – If ‘True’ then include only valid and enabled channel names

Returns

String with zero or more channel names

Return type

List[str]

send_message(msg, **kwargs)

Send message to one or more channels.

This method sends a given message to one or more channels at the same time. The ‘channels’ keyword argument defines which communication channels to use.

The keyword arguments can also include additional message data such as HTML for emails and Slack blocks.

Parameters

  • msg (str) – Simple/plain text version of message to be sent

  • kwargs (Any) – Additional optional arguments

Returns

List of ‘response’ records. We always return a list even though we may only have a single item. This allows us to be consistent across all ‘send_message()’ functions.

Raises

InvalidProviderError – Channel/service provider is not valid/active

Return type

Union[List[f451_comms.providers.provider.Response], Any]

send_message_via_mailgun(msg, **kwargs)

Send email via Mailgun.

This method sends a given message via email using the Mailgun service provider. The keyword arguments can also include additional message data such as an HTML version of the message.

Parameters

  • msg (str) – Simple/plain text version of message to be sent

  • kwargs (Any) – Additional optional arguments

Returns

List of ‘response’ records from email Mailgun service. We always return a list even though we may only have a single item. This allows us to be consistent across all ‘send_message()’ functions.

Raises

InvalidProviderError – Mailgun service is not valid/active

Return type

Union[List[f451_comms.providers.provider.Response], Any]

send_message_via_slack(msg, **kwargs)

Send message via Slack.

This method sends a given message via Slack. The ‘kwargs’ arguments can also include additional message data such Slack blocks.

Parameters

  • msg (Any) – simple/plain text version of message to be sent. The ‘msg’ argument can also be a ‘list’ of Slack blocks.

  • kwargs (Any) – Additional optional arguments

Returns

List of ‘response’ records from Slack. We always return a list even though we may only have a single item. This allows us to be consistent across all ‘send_message()’ functions.

Raises

InvalidProviderError – Slack channel is not valid/active

Return type

Union[List[f451_comms.providers.provider.Response], Any]

send_message_via_twilio(msg, **kwargs)

Send SMS via Twilio.

This method sends a given message via SMS (using Twilio) to one or more recipients. The phone numbers of the recipients must be specified in the ‘to_phone’ keyword argument.

Parameters

  • msg (str) – Simple/plain text version of message to be sent

  • kwargs (Any) – Additional optional arguments

Returns

List of ‘response’ records from Twilio SMS service. We always return a list even though we may only have a single item. This allows us to be consistent across all ‘send_message()’ functions.

Raises

InvalidProviderError – Twilio service is not valid/active

Return type

Union[List[f451_comms.providers.provider.Response], Any]

send_message_via_twitter(msg, **kwargs)

Send message via Twitter.

This method sends a given message via Twitter either as ‘status update’ or as DM to a specific recipient. If the latter, then the recipient must be specified in the ‘kwargs’ arguments.

Parameters

  • msg (str) – simple/plain text version of message to be sent

  • kwargs (Any) – Additional optional arguments

Returns

List of ‘response’ records from Twitter. We always return a list even though we may only have a single item. This allows us to be consistent across all ‘send_message()’ functions.

Raises

InvalidProviderError – Twitter channel is not valid/active

Return type

Union[List[f451_comms.providers.provider.Response], Any]

property valid_channels: List[str]

Return ‘senderName’ property.

Sub-module - f451_comms.providers.provider

Interface/base classes used in f451 Communications module.

This module holds various base classes used for various service providers (e.g. email, Slack, Twilio, Twitter, etc.).

class f451_comms.providers.provider.Media(inList, maxNum)

Processor class for ‘media’ lists.

Parameters

  • inList (Any) –

  • maxNum (int) –

Return type

None

inList

Single filename (string) or list with one or more filenames

maxNum

Max number of filenames in list

property clean: List[str]

Return normalized value from ‘data’ property.

property data: List[str]

Return ‘data’ property.

property maxNum: int

Return ‘maxNum’ property.

property minNum: int

Return ‘minNum’ property.

property raw: List[str]

Return raw value from ‘data’ property.

property totNum: int

Return ‘totNum’ property.

class f451_comms.providers.provider.Provider(serviceType, serviceName, configSection)

Base class for service providers.

Parameters

  • serviceType (str) –

  • serviceName (str) –

  • configSection (str) –

Return type

None

serviceType

communication/service type (e.g. email, SMS, etc.)

serviceName

communication/service name (e.g. Mailgun, Twilio, etc.)

configSection

name of section in config files (e.g. f451_mailgun, f451_twilio, etc.)

property configSection: str

Return ‘configSection’ property.

abstract send_message(msg, **kwargs)

Stub for ‘send_message()’ method.

Parameters

  • msg (str) –

  • kwargs (Any) –

Return type

Any

property serviceName: str

Return ‘serviceName’ property.

property serviceType: str

Return ‘serviceType’ property.

class f451_comms.providers.provider.Response(status, provider, data, response=None, errors=None)

Generic response class.

This class provides a standard interface for responses from sending messages via various communication services.

Parameters

  • status (str) –

  • provider (str) –

  • data (Any) –

  • response (Optional[requests.models.Response]) –

  • errors (Any) –

status

Response status string. const.STATUS_SUCCESS or const.STATUS_SUCCESS

provider

Provider name that returned that response. Correlates to :attr:’~notifiers.core.Provider.name’

data

The notification data that was used for the notification

response

The response object that was returned. Usually :class:’requests.Response’

errors

Holds a list of errors if relevant

Note

This class is inspired by the “Response” class in the “Notifiers” module by Or Carmi: https://github.com/liiight/notifiers

property isOK: bool

Return ‘true’ (boolean) if no errors.

raise_on_errors()

Raise exception on error in request response.

Raises

CommunicationsError – if request response has errors

Return type

None

f451_comms.providers.provider.process_media_list(inList, maxNum=10, strict=False)

Process list of media files.

‘inList’ can be a single string if it’s only 1 attachment. Or it can be a list of one or more file names string.

Parameters

  • inList (Any) – Single filename (string), or list of one or more file name strings.

  • maxNum (int) – Max number of media files

  • strict (bool) – If ‘True’ then exception is raised when file does not exist, otherwise filename is simply skipped

Returns

String with zero or more filenames

Return type

List[str]

f451_comms.providers.provider.verify_file(fName, strict)

Verify that a file exists.

This function will raise an exception if ‘strict’ is set to ‘True’.

Parameters

  • fName (str) – Single filename (string).

  • strict (bool) – If ‘True’ then exception is raised when file does not exist

Returns

‘True’ if files exists. If file does not exist or filename is blank (and ‘strict’ is set to ‘False’) then we return ‘False’.

Raises

InvalidAttributeError – If file does not exist

Return type

bool

f451_comms.providers.provider.verify_media_file(fName, validFmts, strict)

Verify that an image file exists and has proper format.

This function will raise an exception if ‘strict’ is set to ‘True’.

Parameters

  • fName (str) – Single filename (string).

  • validFmts (List[str]) – ‘list’ of valid image formats (e.g. jpeg, png, etc.)

  • strict (bool) – If ‘True’ then exception is raised when file does not exist

Returns

‘True’ if files exists. If file does not exist or filename is blank (and ‘strict’ is set to ‘False’) then we return ‘False’.

Raises

InvalidAttributeError – If file does not exist

Return type

bool

Sub-module - f451_comms.providers.email

Default (base) class for email providers in f451 Communications module.

This is a base class for email providers, and it holds some common methods and attributes used across most/all email providers/services.

class f451_comms.providers.email.Attachments(inList, inType, maxNum)

Processor class for email ‘attachments’ lists.

Parameters

  • inList (Any) –

  • inType (str) –

  • maxNum (int) –

Return type

None

inList

Single filename (string) or list with one or more filenames

inType

Type of email attachment (i.e. ‘attachments’ or ‘inline’)

maxNum

Max number of filenames in list

property clean: List[Tuple[str, Tuple[str, bytes]]]

Return ‘clean’ list of file attachments.

Note: no processing is done. But we keep this method for consistency.

property data: List[Tuple[str, Tuple[str, bytes]]]

Return ‘data’ property.

property maxNum: int

Return ‘maxNum’ property.

property minNum: int

Return ‘minNum’ property.

property raw: List[Tuple[str, Tuple[str, bytes]]]

Return ‘raw’ list of file attachments.

property totNum: int

Return ‘totNum’ property.

class f451_comms.providers.email.BaseEmail(serviceName, configSection, **kwargs)

Base class for email providers.

Parameters

  • serviceName (str) –

  • configSection (str) –

  • kwargs (Any) –

Return type

None

serviceName

Name of email service (e.g. Mailgun, etc.)

configSection

Name of section in config files (e.g. f451_mailgun, etc.)

property defaultSubject: str

Return ‘defaultSubject’ property.

property defaultTags: List[str]

Return ‘defaultTags’ property.

property defaultTo: List[f451_comms.entity.Entity]

Return ‘defaultTo’ property.

send_message(msg, **kwargs)

Stub for ‘send_message()’ method.

Parameters

  • msg (str) –

  • kwargs (Any) –

Return type

Any

property sender: f451_comms.entity.Entity

Return ‘sender’ property.

property senderEmail: str

Return ‘senderEmail’ property.

property senderName: str

Return ‘senderName’ property.

class f451_comms.providers.email.CcEmail(inList, maxNum, keyword='cc_email')

Processor class for email ‘cc’ address lists.

Parameters

  • inList (Any) –

  • maxNum (int) –

  • keyword (str) –

Return type

None

inList

Single email address (string) or list with one or more email addresses

maxNum

Max number of email addresses in list

keyword

Attribute keyword string

property clean: List[str]

Return ‘clean’ list of email address strings.

property data: List[f451_comms.entity.Entity]

Return ‘data’ property.

property maxNum: int

Return ‘maxNum’ property.

property minNum: int

Return ‘minNum’ property.

property raw: List[f451_comms.entity.Entity]

Return ‘raw’ list of ‘Entity’ objects.

property totNum: int

Return ‘totNum’ property.

class f451_comms.providers.email.ToEmail(inList, maxNum, strict=True)

Processor class for email ‘to’ address lists.

inList

Single email address (string) or list with one or more email addresses

maxNum

Max number of email addresses in list

strict

If ‘True’ then exception is raised if email address list is empty

Raises

MissingAttributeError – ‘strict’ mode and list of email addresses is empty

Parameters

  • inList (Any) –

  • maxNum (int) –

  • strict (bool) –

Return type

None

property clean: List[str]

Return ‘clean’ list of email address strings.

property data: List[f451_comms.entity.Entity]

Return ‘data’ property.

property maxNum: int

Return ‘maxNum’ property.

property minNum: int

Return ‘minNum’ property.

property raw: List[f451_comms.entity.Entity]

Return ‘raw’ list of ‘Entity’ objects.

property totNum: int

Return ‘totNum’ property.

f451_comms.providers.email.process_attachment_list(inList, inType='attachments', maxNum=10, strict=False)

Process a list of email attachments.

‘inList’ can be a single string if it’s only 1 attachment. Or it can be a list of one or more file names string.

Parameters

  • inList (Any) – Single filename (string), or list of one or more file name strings.

  • inType (str) – File type label i.e. ‘attachment’ or ‘inline’

  • maxNum (int) – Max number of files/attachments

  • strict (bool) – If ‘True’ then exception is raised when file does not exist, otherwise filename is simply skipped

Returns

List of tuples

Return type

List[Tuple[str, Tuple[str, bytes]]]

f451_comms.providers.email.process_recipient_list(inList, maxNum)

Process list of recipients and return list of ‘Entity’ objects.

Parameters

  • inList (Any) – Single email address (string) or ‘Entity’ object, or list of one or more email addresses or ‘Entity’ objects.

  • maxNum (int) – Max number of email addresses

Returns

List of ‘Entity’ objects

Return type

List[f451_comms.entity.Entity]

Sub-module - f451_comms.providers.mailgun

Mailgun (email) class for f451 Communications module.

This module adds an abstraction layer for the Mailgun email services and the main purpose is to provide a standard interface for some core methods for sending emails (with or without attachments) to one or more recipients.

Note

  • This module assumes that we have an active Mailgun developer account.

  • This module uses the Python ‘requests’ module to connect with the Mailgun service.

class f451_comms.providers.mailgun.Mailgun(apiKey, fromDomain, **kwargs)

Email class for f451 Communications module.

Use this support class to send email via Mailgun service.

Parameters

  • apiKey (str) –

  • fromDomain (str) –

  • kwargs (Any) –

Return type

None

apiKey

Mailgun API key

fromDomain

Mailgun domain

send_message(msg, **kwargs)

Send email to one or more recipients.

Note that the ‘text’ version of the message is included in the ‘msg’ param to ensure API consistency with our communications modules/components.

Parameters

  • msg (str) – Plain text version of email message

  • kwargs (Any) – Additional optional arguments

Returns

‘list’ of ‘Response’ objects from Mailgun service API call. We always return a list even though we’ll only have a single item. This allows us to be consistent across all ‘send_message()’ functions.

Return type

List[f451_comms.providers.provider.Response]

property settings: Dict[str, Any]

Return ‘settings’ property.

class f451_comms.providers.mailgun.RecipientData(inData, maxNum)

Processor class for email tags.

Parameters

  • inData (Any) –

  • maxNum (int) –

Return type

None

inData

‘dict’ with one or more recipient data ‘dict’ records

maxNum

Max number of recipient data records in list

property clean: str

Return ‘data’ property in JSON format.

property data: Dict[str, Any]

Return ‘data’ property.

property maxNum: int

Return ‘maxNum’ property.

property minNum: int

Return ‘minNum’ property.

property raw: Dict[str, Any]

Return ‘raw’ data.

property totNum: int

Return ‘totNum’ property.

class f451_comms.providers.mailgun.Tags(inList, maxNum, minLen, maxLen)

Processor class for email tags.

Parameters

  • inList (Any) –

  • maxNum (int) –

  • minLen (int) –

  • maxLen (int) –

Return type

None

inList

Single tag (string) or list with one or more tags

maxNum

Max number of tags in list

minLen

Min length of any tag in list

maxLen

Max length of any tag in list

property clean: List[str]

Return ‘clean’ data property.

Note: tag data does not get normalized.

property data: List[str]

Return ‘data’ property.

property maxLen: int

Return ‘maxLen’ property.

property maxNum: int

Return ‘maxNum’ property.

property minLen: int

Return ‘minLen’ property.

property minNum: int

Return ‘minNum’ property.

property raw: List[str]

Return ‘raw’ data property.

property totNum: int

Return ‘totNum’ property.

f451_comms.providers.mailgun.process_tag_list(inList, maxNum, minTagLen, maxTagLen)

Process tag list and ensure that there are max N items.

Parameters

  • inList (Any) – Single tag (string) or list with one or more tags

  • maxNum (int) – Max number of tags in list

  • minTagLen (int) – Min length of any tag in list

  • maxTagLen (int) – Max length of any tag in list

Returns

List with zero or more tag strings

Return type

List[str]

Sub-module - f451_comms.providers.sms

Default (base) class for SMS providers in f451 Communications module.

This is a base class for SMS providers, and it holds some common methods and attributes used across most/all SMS providers/services.

class f451_comms.providers.sms.BaseSMS(serviceName, configSection, **kwargs)

Base class for SMS providers.

Parameters

  • serviceName (str) –

  • configSection (str) –

  • kwargs (Any) –

Return type

None

serviceName

Name of SMS service (e.g. Twilio, etc.)

configSection

Name of section in config files (e.g. f451_twilio, etc.)

property defaultTo: List[f451_comms.entity.Entity]

Return ‘defaultTo’ property.

send_message(msg, **kwargs)

Stub for ‘send_message()’ method.

Parameters

  • msg (str) –

  • kwargs (Any) –

Return type

Any

property sender: f451_comms.entity.Entity

Return ‘sender’ property.

property senderName: str

Return ‘senderName’ property.

property senderPhone: str

Return ‘senderPhone’ property.

class f451_comms.providers.sms.ToPhone(inList, maxNum, strict=True)

Processor class for recipient (‘to’) phone number lists.

inList

Single phone number (string) or list with one or more phone numbers

maxNum

Max number of phone numbers in list

strict

If ‘True’ then exception is raised if phone number list is empty

Raises

MissingAttributeError – If ‘strict’ mode and list of phone numbers is empty

Parameters

  • inList (Any) –

  • maxNum (int) –

  • strict (bool) –

Return type

None

property clean: List[str]

Return ‘clean’ list of phone number strings.

property data: List[f451_comms.entity.Entity]

Return ‘data’ property.

property maxNum: int

Return ‘maxNum’ property.

property minNum: int

Return ‘data’ property.

property raw: List[f451_comms.entity.Entity]

Return ‘raw’ list of ‘Entity’ objects.

property totNum: int

Return ‘totNum’ property.

f451_comms.providers.sms.process_recipient_list(inList, maxNum)

Process list of recipients and return list of ‘Entity’ objects.

Parameters

  • inList (Any) – Single phone number (string) or ‘Entity’ object, or list of one or more numbers or ‘Entity’ objects.

  • maxNum (int) – Max number of phone numbers

Returns

List of ‘Entity’ objects

Return type

List[f451_comms.entity.Entity]

Sub-module - f451_comms.providers.twilio

Twilio (SMS) class for f451 Communications module.

This module adds an abstraction layer to the Twilio Rest API client and the main purpose is to provide a standard interface for some core methods for sending SMS messages to specific recipients.

Note

  • This module assumes that we have an active Twilio developer account.

  • This module uses the Twilio REST client.

class f451_comms.providers.twilio.Twilio(acctSID, authToken, **kwargs)

Twilio SMS class for f451 Communications module.

Use this support class to send SMS and voice messages via Twilio API. Please note that the default method is SMS. However, this can be changed with the ‘method’ attribute in the ‘defaults’ dict.

Parameters

  • acctSID (str) –

  • authToken (str) –

  • kwargs (Any) –

Return type

None

acctSID

Twilio account SID

authToken

Twilio auth token

fromPhone

‘from’ phone number

property client: Any

Return ‘client’ property.

send_message(msg, **kwargs)

Send SMS to one or more recipients.

This method provides a standard interface for sending SMS messages using the Twilio API.

Parameters

  • msg (str) – Plain text version of message to be sent

  • kwargs (Any) – Additional optional arguments

Returns

‘list’ of ‘Response’ objects from Twilio service API call. We always return a list even though we’ll only have a single item. This allows us to be consistent across all ‘send_message()’ functions.

Raises

MissingAttributeError – Message text is empty, or ‘to’ and/or ‘from’ phone numbers are empty/missing

Return type

List[f451_comms.providers.provider.Response]

Sub-module - f451_comms.providers.slack

Slack class for f451 Communications module.

This module adds an abstraction layer to the Slack SDK and the main purpose is to provide a standard interface for some core methods for sending Slack updates and files to specific channels.

Note

  • This module assumes that we have an active Slack developer account.

  • This module uses the Slack SDK to connect with the Slack service.

Todo

  • Create ability to DM

class f451_comms.providers.slack.Slack(authToken, signingSecret='', appToken='', **kwargs)

Slack class for f451 Communications module.

Use this support class to send messages via Slack SDK.

Parameters

  • authToken (str) –

  • signingSecret (str) –

  • appToken (str) –

  • kwargs (Any) –

Return type

None

authToken

Slack auth token

signingSecret

Slack signing secret – reserved for future use

appToken

Slack app token – reserved for future use

property appToken: str

Return ‘appToken’ property.

property channel: str

Return ‘channel’ property.

property client: Any

Return ‘client’ property.

send_message(msg, **kwargs)

Post plain text Slack message to a channel.

This method provides a standard interface for posting Slack messages to a given channel using the Slack SDK.

Parameters

  • msg (str) – simple/plain text version of message to be sent

  • kwargs (Any) – Additional optional arguments

Returns

‘list’ of ‘Response’ objects from Slack service API call. We always return a list even though we’ll only have a single item. This allows us to be consistent across all ‘send_message()’ functions.

Raises

MissingAttributeError – Message text is empty, or Slack channel name is empty/missing

Return type

List[f451_comms.providers.provider.Response]

send_message_with_blocks(blocks, **kwargs)

Post Slack message using blocks to a channel.

This method provides a standard interface for posting Slack messages to a given channel using the Slack SDK.

Parameters

  • blocks (List[Dict[str, Any]]) – ‘list’ of Slack blocks as ‘dicts’

  • kwargs (Any) – Additional optional arguments

Returns

‘list’ of ‘Response’ objects from Slack service API call. We always return a list even though we’ll only have a single item. This allows us to be consistent across all ‘send_message()’ functions.

Raises

MissingAttributeError – Message text is empty, or Slack channel name is empty/missing

Return type

List[f451_comms.providers.provider.Response]

send_message_with_file(msg, **kwargs)

Post Slack message with file attachment to a channel.

This method provides a standard interface for posting Slack messages with file attachments to a given channel using the Slack SDK.

Note

Only 1 file attachment per message is allowed. If more than 1 file is included with the message, then only the 1st file is used.

Parameters

  • msg (str) – Simple/plain text version of message to be sent

  • kwargs (Any) – Additional optional arguments

Returns

‘list’ of ‘Response’ objects from Slack service API call. We always return a list even though we’ll only have a single item. This allows us to be consistent across all ‘send_message()’ functions.

Raises

MissingAttributeError – Message text is empty, or Slack channel name is empty/missing

Return type

List[f451_comms.providers.provider.Response]

property sender: f451_comms.entity.Entity

Return ‘sender’ property.

property signingSecret: str

Return ‘signingSecret’ property.

f451_comms.providers.slack.process_file_attachment(inFile, inTitle='', strict=False)

Process a file to be uploaded.

‘inList’ can be a single string if it’s only 1 attachment. Or it can be a list of one or more file names string.

Note

We only allow 1 file to be uploaded at once. However, since the ‘attachment’ attribute can be used with multiple send functions (e.g. email, etc.), we need to handle situation where there potentially are more than 1 filename listed. In the case where there are multiple filenames, we’ll use the first valid filename in the list.

Parameters

  • inFile (Any) – Single filename (string), or list of one or more file name strings.

  • inTitle (str) – Optional file title (string)

  • strict (bool) – If ‘True’ then exception is raised when file does not exist, otherwise filename is simply skipped

Returns

‘Tuple[’ with filename, file stream, and (optional) file title string

Return type

Tuple[str, bytes, str]

f451_comms.providers.slack.process_icon_emoji(inIconEmoji)

Process an ‘icon_emoji’ string.

Parameters

inIconEmoji (str) – Single icon emoji string.

Returns

Properly formatted ‘icon_emoji’ string

Return type

str

Sub-module - f451_comms.providers.twitter

Twitter class for f451 Communications module.

This module adds an abstraction layer to the Tweepy Twitter API package and the main purpose is to provide a standard interface for some core methods for sending Twitter status updates and DMs to specific recipients.

Note

This module assumes that we have an active Twitter developer account.

Note

We use Twitter API v1.1 for all Tweets as the new Twitter API v2 does not yet support media uploads.

class f451_comms.providers.twitter.ToTwitter(inList, maxNum, strict=True)

Processor class for recipient (‘to’) Twitter name lists.

This class is only used for DM recipients. For normal status updates, ‘to’-lists are simply converted to ‘@’-lists.

inList

Single Twitter name (string) or list with one or more Twitter names

maxNum

Max number of Twitter names in list

strict

If ‘True’ then exception is raised if Twitter names list is empty

Raises

MissingAttributeError – ‘strict’ mode and list of Twitter names is empty

Parameters

  • inList (Any) –

  • maxNum (int) –

  • strict (bool) –

Return type

None

property clean: List[str]

Return ‘clean’ list of Twitter name strings.

property data: List[f451_comms.entity.Entity]

Return ‘data’ property.

property maxNum: int

Return ‘maxNum’ property.

property minNum: int

Return ‘minNum’ property.

property raw: List[f451_comms.entity.Entity]

Return ‘raw’ list of ‘Entity’ objects.

property totNum: int

Return ‘totNum’ property.

class f451_comms.providers.twitter.Twitter(usrKey, usrSecret, authToken, authSecret, **kwargs)

Twitter class for f451 Communications module.

Use this support class to send messages via Twilio.

Parameters

  • usrKey (str) –

  • usrSecret (str) –

  • authToken (str) –

  • authSecret (str) –

  • kwargs (Any) –

Return type

None

usrKey

Twitter user/consumer key

usrSecret

Twitter user/consumer secret

authToken

Twitter auth/access token

authSecret

Twitter auth/access token secret

property client: Any

Return ‘totNum’ property.

property defaultTags: List[str]

Return ‘defaultTags’ property.

property defaultTo: List[f451_comms.entity.Entity]

Return ‘defaultTo’ property.

get_user_id(dmUserName, strict=False)

Get Twitter user ID.

This method provides a standard interface for retrieving the user ID for a given Twitter username.

Parameters

  • dmUserName (str) – simple/plain text version of message to be sent

  • strict (bool) – If ‘True’ then exception is raised when user does not exist, otherwise empty string is returned

Returns

Twitter user ID for a given username

Raises

  • MissingAttributeError – Twitter DM username is blank

  • CommunicationsError – Twitter/Tweepy API returns an error or Twitter creds are invalid

Return type

str

property isValidCreds: bool

Return ‘isValidCreds’ property.

send_dm(msg, **kwargs)

Send Twitter DM.

This method provides a standard interface for sending Twitter DMs to a specific recipient/username. The recipient name must be listed using the ‘to_twitter’ key.

Note

No need to validate Twitter credentials here as this is done when retrieving Twitter ID for recipient.

Parameters

  • msg (str) – Simple/plain text version of message to be sent

  • kwargs (Any) – Additional optional arguments

Returns

‘list’ of ‘Response’ objects from Tweepy API call. We always return a list even though we’ll only have a single item. This allows us to be consistent across all ‘send_message()’ functions.

Raises

  • MissingAttributeError – Twitter message is blank

  • CommunicationsError – Twitter/Tweepy API returns an error or Twitter creds are invalid

Return type

List[f451_comms.providers.provider.Response]

send_message(msg, **kwargs)

Post Twitter status update or send DM.

This method provides a standard interface for posting a Twitter status update or send a Twitter DM to a specific user. The ‘method_dm’ key is used to indicate how the message will be sent.

Note

We determine whether to send a DM or a regular status update (i.e. tweet) based on the ‘method_<xxxx>’ attribute. The strategy is to check for explicit ‘DM’ first. We’ll go with status update if ‘method_dm’ is set to ‘False’ or is missing, unless ‘method_update’ is set to ‘False’.

  1. ‘method_dm’ is ‘True’ –> send DM

  2. ‘method_dm’ is ‘False’ –> send status update

  3. ‘method_dm’ is missing –> check ‘method_update’

  4. ‘method_dm’ is missing and ‘method_update’ is ‘True’ –> send status update

  5. ‘method_dm’ is missing and ‘method_update’ is ‘False’ –> send DM

  6. ‘method_dm’ is missing and ‘method_update’ is missing –> send status update

  7. ‘method_dm’ is ‘True’ and ‘method_update’ is ‘True’ –> send DM as ‘method_dm’ has priority

Parameters

  • msg (str) – Simple/plain text version of message to be sent

  • kwargs (Any) – Additional optional arguments

Returns

‘list’ of ‘Response’ objects from Tweepy API call. We always return a list even though we’ll only have a single item. This allows us to be consistent across all ‘send_message()’ functions.

Return type

List[f451_comms.providers.provider.Response]

send_status_update(msg, **kwargs)

Post Twitter status update.

This method provides a standard interface for posting Twitter status update messages.

Parameters

  • msg (str) – simple/plain text version of message to be sent

  • kwargs (Any) – Additional optional arguments

Returns

‘list’ of ‘Response’ objects from Tweepy API call. We always return a list even though we’ll only have a single item. This allows us to be consistent across all ‘send_message()’ functions.

Raises

  • MissingAttributeError – Twitter message is blank

  • CommunicationsError – Twitter/Tweepy API returns an error or Twitter creds are invalid

Return type

List[f451_comms.providers.provider.Response]

property timeline: Any

Return ‘timeline’ property.

f451_comms.providers.twitter.process_recipient_list(inList, maxNum)

Process list of recipients and return list of ‘Entity’ objects.

Parameters

  • inList (Any) – Single Twitter name (string) or ‘Entity’ object, or list of one or more names or ‘Entity’ objects.

  • maxNum (int) – Max number of Twitter names

Returns

List of ‘Entity’ objects

Return type

List[f451_comms.entity.Entity]

Sub-module - f451_comms.entity

‘Entity’ data class for f451 Communications module.

This data class is used to define entities (e.g. humans, systems, bots, Yetis, ghosts, etc.) that can can send or receive communications.

Note

Todo

  • Verify max length for Slack names.

  • Find correct regex for email

  • Find correct regex for phone

  • Find correct regex for twitter

class f451_comms.entity.Entity(name='', email='', phone='', slack='', twitter='')

Base class for represting users (senders and recipients).

Parameters

  • name (str) –

  • email (str) –

  • phone (str) –

  • slack (str) –

  • twitter (str) –

serviceType

communication/service type (e.g. email, SMS, etc.)

serviceName

communication/service name (e.g. Mailgun, Twilio, etc.)

configSection

name of section in config files (e.g. f451_mailgun, f451_twilio, etc.)

property email: str

Return ‘email’ property.

property name: str

Return ‘name’ property.

property phone: str

Return ‘phone’ property.

property slack: str

Return ‘slack’ property.

to_dict()

Return properties as ‘dict’ structure.

Return type

Dict[str, Any]

property twitter: str

Return ‘twitter’ property.

f451_comms.entity.dedupe_by_attribute(inList, key)

Dedupe list of objects by key.

Theis function will search through a given list of objects and compare the value of the ‘key’ attribute. Only one object with a given key value is kept. If an object does not have the ‘key’ attribute or of that attribute is empty/none, then the object is excluded from the resulting list as well.

Parameters

  • inList (List[f451_comms.entity.Entity]) – list of objects to dedupe

  • key (str) – object attribute to be used as key value for filtering

Yields

List item

Return type

Iterator[f451_comms.entity.Entity]

f451_comms.entity.process_entity_list_by_key(inList, key, prefix='', suffix='', spacer='')

Process specific key/attribute in list of ‘Entity’ objects.

Parameters

  • inList (Any) –

  • key (str) –

  • prefix (str) –

  • suffix (str) –

  • spacer (str) –

Return type

str

Sub-module - f451_comms.exceptions

Exceptions classes for f451 Communications module.

This module holds the custom exceptions used across all providers in the f451 Communications module.

Note

This module is inspired by the “Exceptions” module in the “Notifiers” module by Or Carmi: https://github.com/liiight/notifiers

exception f451_comms.exceptions.CommunicationsError(*args, **kwargs)

Communications error.

This is raised when a service returns an error.

Requires:

‘kwargs’ keyword: ‘errors’

Parameters

  • args (Any) – exception arguments

  • kwargs (Any) – exception kwargs

Return type

None

exception f451_comms.exceptions.InvalidAttributeError(errMsg, *args, **kwargs)

Invalid attribute error.

Raised when given value is out of bounds and/or does not meet requirements for a given attribute/argument.

Parameters

  • errMsg (str) – error message for ‘validation’ failure

  • args (Any) – exception arguments

  • kwargs (Any) – exception kwargs

Return type

None

exception f451_comms.exceptions.InvalidProviderError(providerName, *args, **kwargs)

Invalid service provider.

Service provider is either unknown or not enabled.

Parameters

  • errMsg – error message for missing (required) ‘attribute’

  • args (Any) – exception arguments

  • kwargs (Any) – exception kwargs

  • providerName (str) –

Return type

None

exception f451_comms.exceptions.MissingAttributeError(errMsg, *args, **kwargs)

Missing attribute error.

Raised when required data attributes are missing.

Parameters

  • errMsg (str) – Error message for missing (required) ‘attribute’

  • args (Any) – Exception arguments

  • kwargs (Any) – Exception kwargs

Return type

None

exception f451_comms.exceptions.f451CommsExceptionError(*args, **kwargs)

Exception base class for f451 Communications module.

Catch this exception to catch all custom exceptions from the f451 Communications module.

Looks for provider, message and data in kwargs

Requires:

‘kwargs’ keyword: ‘errors’

Parameters

  • args (Any) – exception arguments

  • kwargs (Any) – exception kwargs

Return type

None

Sub-module - f451_comms.processor

Interface/base class for ‘attribs’ processors used in f451 Communications module.

This module is a base class for attribute processor objects used to handle various message attributes across all services in the f451 Communications module.

class f451_comms.processor.AttributeProcessor(keyword, required)

Attribute validator base class for SciLab Communications module.

Parameters

  • keyword (str) – ‘attribs’ keyword string

  • required (bool) – ‘attrib’ is required if True, else it’s optional

Return type

None

abstract property clean: Any

Stub for class method/property.

property isRequired: bool

Return ‘isRequired’ property.

property isValid: bool

Return ‘isValid’ property.

property keyword: str

Return ‘keyword’ property.

abstract property raw: Any

Stub for class method/property.

Misc. utilities - f451_comms.utils

Utility functions for f451 Communications module.

This module includes several functions that are used throughout the f451 Communications module to handle common tasks like processing lists, parsing strings, and more.

f451_comms.utils.convert_attrib_str_to_list(inStr, itemDelim='|', itemFmt=<class 'str'>)

Convert a given attribute string to list format.

This method is used throughout the f451 Communications module and its purpose is to convert multi-value attribute strings to list format. By default, the output will be a list of strings. But the ‘itemFmt’ function can convert the output to a list of any type.

Example

>>> myList = convert_attrib_str_to_list("item")
>>> assert myList == ["item"]

>>> myList = convert_attrib_str_to_list("item1|item2|item3")
>>> assert myList == ["item1", "item2", "item3"]

>>> myList = convert_attrib_str_to_list("item")
>>> assert myList == ["item"]

>>> myList = convert_attrib_str_to_list("5")
>>> assert myList == ["5"]

>>> myList = convert_attrib_str_to_list("5")
>>> assert myList == ["5"]

>>> myList = convert_attrib_str_to_list(5)
>>> assert myList == ["5"]

>>> myList = convert_attrib_str_to_list("1|2|3|4|5")
>>> assert myList == ["1", "2", "3", "4", "5"]

>>> myList = convert_attrib_str_to_list("5", "|", int)
>>> assert myList == [5]

>>> myList = convert_attrib_str_to_list(5, "|", int)
>>> assert myList == [5]

>>> myList = convert_attrib_str_to_list("1|2|3|4|5", "|", int)
>>> assert myList == [1, 2, 3, 4, 5]
Parameters

  • inStr (Any) – configuration string to be converted.

  • itemDelim (str) – item delimiter

  • itemFmt (Any) – item (data) formatter

Returns

List with zero or more attribute values

Return type

List[Any]

f451_comms.utils.convert_config_str_to_dict(inStr, sectnDelim='|', itemDelim=',', keyDelim=':')

Convert ‘config’ string to dict format.

This method is used throughout the f451 Communications module and its purpose is to convert configuration strings to dict format which then can be read by ConfigParser.

Note

This technique should only be used to represent a single section.

Example

>>> myDict = convert_config_str_to_dict("section1|key1:val1,key2:val2")
>>> assert myDict == {"section1": {"key1": "val1", "key2": "val2"}}
Parameters

  • inStr (str) – configuration string to be converted

  • sectnDelim (str) – section delimiter

  • itemDelim (str) – item delimiter

  • keyDelim (str) – key delimiter

Returns

Configuration values in dict format

Raises

ValueError – String has more than 1 section, or section label is missing, or there are no section items

Return type

Dict[str, Any]

f451_comms.utils.is_valid_email(inStr)

Validate string has valid email address format.

Parameters

inStr (str) –

Return type

bool

f451_comms.utils.is_valid_phone(inStr)

Validate string has valid phone number format.

Parameters

inStr (str) –

Return type

bool

f451_comms.utils.is_valid_twitter(inStr)

Validate string has valid Twitter name format.

Parameters

inStr (str) –

Return type

bool

f451_comms.utils.parse_attribs(attribs, key, default=None)

Retrieve value from attributes.

This method is used throughout the f451 Communications module and its purpose is to retrieve a value from the ‘attribs’ dict which acts as a (temp) key-value store mechanism to supply various methods with any number of additional optional values. If the key cannot be found, then the method can return a default value.

Example

>>> myVal = parse_attribs({"key1": "val1", "key2": "val2"}, "key1", "NOT FOUND")
>>> assert myVal == "val1"

>>> myVal = parse_attribs({"key1": "val1", "key2": "val2"}, "xyz", "NOT FOUND")
>>> assert myVal == "NOT FOUND"

Note

This method will only search for top-level keys. However, each key can be associated with any type of value including dict and list types.

Parameters

  • attribs (Any) – dict with set of key-value pairs

  • key (str) – key string to find in ‘attribs’

  • default (Optional[Any]) – default value to be returned if key is not found

Returns

Value from ‘attribs’ if key is found, else ‘default value

Return type

Any

f451_comms.utils.parse_defaults(inConfig, sections)

Parse default values.

Parameters

  • inConfig (configparser.ConfigParser) – ConfigParser object with default data

  • sections (List[str]) – list of one or more section names

Returns

‘dict’ structure with default value(s)

Return type

Dict[str, Any]

f451_comms.utils.process_config(inConfig, force=True)

Process config files.

Parameters

  • inConfig (Any) – configuration string to be converted

  • force (bool) – section delimiter

Returns

Config parser object

Raises

ValueError – Invalid config data source

Return type

configparser.ConfigParser

f451_comms.utils.process_string_list(inList, prefix='', suffix='', spacer='')

Process list of strings convert them to single string.

This method is used throughout the f451 Communications module and its purpose is to process a list with one or more strings by adding prefix and suffix, and combining them into a single string with spaces between them.

Parameters

  • inList (Any) – single string or list with one or more strings

  • prefix (str) – optional prefix for each item in the list

  • suffix (str) – optional suffix for each item in the list

  • spacer (str) – spacer to place between string items

Returns

String with zero or more hashtags

Return type

str

Keywords and values for attribs argument and config files

The following keywords and values are primarily used to pass additional arguments via the **kwargs parameter to the various send_message_<xxxx> functions. Please note that some keywords can also be used for defining API credentials and various default values for use in config files (e.g. config.ini).

  • account_sid
    • Required for:

      • SMS (Twilio) – Twilio account SID as str

    • Example .ini entry:

      • acct_sid = XX0x00x0x0xxxxx000x0x0x0x000xxx00x

    Warning

    Do NOT store this value in source code!

  • app_token
    • Required for:

      • Slack – Slack app token as str

    • Example .ini entry:

      • app_token = xapp-0-X00000000-000000000-00000000xxxxx00000000xxxxx00000000

    Warning

    Do NOT store this value in source code!

  • attachments
    • Optional for:

      • Email (Mailgun) – one or more file names as str or list of str

      • Slack – one or more file names as str or list of str

    • Examples:

      • Single attachment: {"attachments": path/to/file1.txt"}

      • Multiple attachments: {"attachments": ["path/to/file1.txt", "path/to/file2.txt"]}

  • auth_secret
    • Required for:

      • Twitter – Twitter auth secret as str

    • Example .ini entry:

      • auth_secret = xx0000000000xx000000x0000000x0xx00000xxx00000

    Warning

    Do NOT store this value in source code!

  • auth_token
    • Required for:

      • Slack – Slack auth token as str

      • SMS (Twilio) – Twilio auth token as str

      • Twitter – Twitter auth token as str

    • Example .ini entry:

      • auth_token = 000000000000000000000000000000000000000000000

    Warning

    Do NOT store this value in source code!

  • bcc_email
    • Optional for:

      • Email (Mailgun) – see to_email attribute

  • cc_email
    • Optional for:

      • Email (Mailgun) – see to_email attribute

  • channels
    • Required for:

      • Comms.send_message() method – one or more tags as str or list of str

    • Examples:

      • Send message to all available channels: {"channels": "all"}

      • Send message to Twitter and Slack: {"channels": ["f451_twitter", "f451_slack"]} or {"channels": "f451_twitter|f451_slack"}

    • Valid options:

      • all – all channels

      • f451_mailgun – email via Mailgun service

      • f451_slack – Slack message

      • f451_twilio – SMS via Twilio service

      • f451_twitter – Twitter status updates and DMs

    Note

    Use channel_map attribute to map custom keywords against channel names.

  • channel_map

    • Optional for: main section

    • Examples:

      • Map email and sms keywords: channel_map = email:f451_mailgun|sms:f451_twilio

  • debug

    • Reserved

  • file_title
    • Optional for:

      • Slack – file title as str

    • Examples:

      • Simple title: {"file_title": "List of Gotham City crime bosses"}

  • from

    • Optional for: main section. Complete sender info (e.g. name, phone, email, etc.) as str or list of str

    • Examples:

      • Complete sender info: from = name:Batman|email:batman@example.com|phone:+12125550001|slack:Batman|twitter:Batman

    Note

    Use from attribute instead of individual attributes (e.g from_name, from_email, from_phone, etc.).

  • from_domain
    • Required for:

      • Email (Mailgun) – Mailgun domain as str

    • Example .ini entry:

      • from_domain = xxxxxxx00000000000000000000.mailgun.org

    Warning

    Do NOT store this value in source code!

  • from_email

    • Reserved

  • from_name
    • Optional for:

      • Email (Mailgun) – sender name str

  • from_phone
    • Required for:

      • SMS (Twilio) – Twilio sender phone number as str

    • Example .ini entry:

      • from_phone = +12125150000

    Warning

    Do NOT store this value in source code!

  • from_slack
    • Optional for:

      • Slack – sender name str

  • from_twitter
    • Required for:
  • html
    • Optional for:

      • Email (Mailgun) – HTML version of email message as str

    • Example:

      • Simple: {"html": "<html>Hello world!</html>"}

  • icon_emoji
    • Optional for:

      • Slack – a str that represents the emoji short code.

    • Examples:

      • Use See No Evil emoji: {"icon_emoji": ":see_no_evil:"}

  • inline
    • Optional for:

      • Email (Mailgun) – one or more file names as str or list of str

    • Valid formats: .png, .jpg, .gif

    • Examples:

      • Single inline image: {"inline": path/to/image1.jpg"}

      • Multiple inline images: {"inline": ["path/to/image1.jpg", "path/to/image2.jpg"]}

  • log_level
    • Optional for:

      • all channels – int or str

    • Default: logging.INFO

    • Valid options:

      • -1 or OFF – no logging

      • int from 0 to 100 – log level is set to this value.

      • standard log levels defined in Python ‘logging’ package package as logging.<CONST> or equivalent string name

    • Examples:

      • Enable logging: {"log_level": logging.INFO} or {“log_level”: “INFO”}

      • Disable logging: {"log_level": -1} or {"log_level": "OFF"}

  • media
    • Optional for:

      • SMS (Twilio) – one or more file names as str or list of str

      • Twitter – one or more file names as str or list of str

    • Valid formats: .png, .jpg, .gif

    • Examples:

      • Single attachment: {"attachments": path/to/file1.txt"}

      • Multiple attachments: {"attachments": ["path/to/file1.txt", "path/to/file2.txt"]}

  • method_update

    • Reserved

  • method_dm
    • Optional for:

      • Twitter – boolean flag. If True message is sent as DM. This also requires at least one name listed in to_twitter attribute.

    • Default: False

    • Examples:

      • Send message as DM: {"method_dm": True}

  • name

    • Reserved

  • phone

    • Reserved

  • priv_api_key
    • Required for:

      • Email (Mailgun) – Mailgun private API key as str

    • Example .ini entry:

      • priv_api_key = key-00000000000000000000000000000000

    Warning

    Do NOT store this value in source code!

  • publ_val_key
    • Required for:

      • Email (Mailgun) – Mailgun public API key as str

    • Example .ini entry:

      • publ_val_key = pubkey-00000000000000000000000000000000

    Warning

    Do NOT store this value in source code!

  • recipient

    • Reserved

  • recipient_data
    • Optional for:

      • Email (Mailgun) – list of additional recipient info for batch emails as struct

    • Example:

      • Email address used as key: {"recipient_data": {"batman@example.com": {"name":"Batman", "lucky": 13}, ...}}

  • signing_secret
    • Required for:

      • Slack – signing secret as str

    • Example .ini entry:

      • signing_secret = xxxxx0000000000xxx000000000xxxx00000

    Warning

    Do NOT store this value in source code!

  • slack

    • Reserved

  • subject
    • Required for:

      • Email (Mailgun) – email subject line as str

    • Examples:

      • Simple: {"subject": "Hello world!"}

      • Personalized using recipients info: {"subject": "Hello %recipients.name%"}

  • suppress_errors
    • Optional for:

      • Email (Mailgun) – boolean flag. If True Mailgun exceptions are suppressed.

      • SMS (Twilio) – boolean flag. If True Twilio exceptions are suppressed.

      • Twitter DM – boolean flag. If True Twitter exceptions are suppressed.

    • Default: False

    • Examples:

      • Suppress errors: {"suppress_error": True}

  • tags
    • Optional for:

      • Email (Mailgun) – one or more (max 3) tags as str or list of str

    • Examples:

      • Single tag: {"tags": "greeting"}

      • Multiple tags: {"tags": ["greeting", "salutation"]} or {"tags": "greeting|salutation"}

  • testmode
    • Optional for:

      • Email (Mailgun) – boolean flag. If True test mode is enabled.

    • Default: False

    • Examples:

      • Enable test mode: {"testmode": True}

  • to

    • Optional for: main section. Complete recipient info (e.g. name, phone, email, etc.) as str or list of str

    • Examples:

      • Complete recipient info: from = name:Batman|email:batman@example.com|phone:+12125550001|slack:Batman|twitter:Batman

    Note

    Use to attribute instead of individual attributes (e.g to_name, to_email, to_phone, etc.).

  • to_channel
    • Required for:

      • Slack – one or more Slack channels as str or list of str

    • Examples:

      • Single channel: {"to_channel": "#GothamCrime"}

      • Multiple recipients: {"to_channel": ["#GothamCrime", "#NewVillains"]} or {"to_channel": "GothamCrime|NewVillains"}

  • to_email
    • Required for:

      • Email (Mailgun) – one or more email addresses as str or list of str

    • Examples:

      • Single recipient: {"to_email": "batman@example.com"}

      • Multiple recipients: {"to_email": ["batman@example.com", "robin@example.com"]} or {"to_email": "batman@example.com|robin@example.com"}

    Note

    If you send an email to multiple recipients, then also use the recipient_data attribute for additional recipient info.

  • to_phone
    • Required for:

      • SMS (Twilio) – one or more phone numbers as str or list of str

    • Examples:

      • Single recipient: {"to_phone": "+12125550000"}

      • Multiple recipients: {"to_phone": ["+12125550000", "+12125551111"]} or {"to_phone": "+12125550000|+12125551111"}

  • to_slack
    • Optional for:

      • Slack – one or more Slack user Names as str or list of str. Names listed here will be included with ‘@’ symbol in the beginning of the Slack message.

    • Examples:

      • Single name: {"to_slack": "batman"}

      • Multiple names: {"to_slack": ["batman", "robin"]} or {"to_slack": "batman|robin"}

  • to_twitter
    • Optional for:

      • Twitter – one or more Twitter user names as str or list of str. If method_dm is False, then names listed here will be included with ‘@’ symbol in the beginning of the Twitter status update message.

    • Examples:

      • Single name: {"to_twitter": "batman"}

      • Multiple names: {"to_twitter": ["batman", "robin"]} or {"to_twitter": "batman|robin"}

  • tracking
    • Optional for:

      • Email (Mailgun) – boolean flag. If True tracking is enabled.

    • Default: False

    • Examples:

      • Enable tracking: {"tracking": True}

  • twitter

    • Reserved

  • user_key
    • Required for:

      • Twitter – Twitter user key as str

    • Example .ini entry:

      • user_key = xxxxx0000000000xxx000000000xxxx00000

    Warning

    Do NOT store this value in source code!

  • user_secret
    • Required for:

      • Twitter – Twitter user secret as str

    • Example .ini entry:

      • user_secret = xxxxx0000000000xxx000000000xxxx00000xxxxx00000xxxxx0000

    Warning

    Do NOT store this value in source code!

  • webhook_sign_key
    • Required for:

      • Email (Mailgun) – Mailgun webhook sign key as str

    • Example .ini entry:

      • webhook_sign_key = key-xxxxx0000000000xxx000000000

    Warning

    Do NOT store this value in source code!

Note

Attributes that support str and list of str can process the lists either as a string using pipe character (|) as delimiter between values, or as a true lst of str:

  • list of values as simple str: "apple|banana|orange"

  • list of values as lst of str: ["apple", "banana", "orange"]