Notifications
Slack
Overview
The Slack module leverages the Slack API and provides way to easily send notifications through Slack. It is recommended that you reference the Slack API documentation for additional details and information.
Note
- API Tokens
Slack API Tokens are required to use this module. To obtain an API Token, create a Slack App associated with the desired Slack workspace. Once you create the app, navigate to ‘OAuth & Permissions’ and add the following OAuth scopes:
channels:read, users:read, chat:write, and files:write
You can now install the Slack App, which will produce an API Token. Note that you can change the scopes any time, but you must reinstall the app each time (your API Token will stay the same).
Slack has rate limits on all its endpoints.
QuickStart
To call the Slack class you can either store the API Token as an environment variable SLACK_API_TOKEN or pass it in as an argument.
from parsons import Slack
slack = Slack() # Initiate class via environment variable api token
slack = Slack(api_key='my-api-tkn') # Pass api token directly
You can then send messages:
from parsons import Slack
slack = Slack()
# send a simple messsage
slack.message_channel("my_channel", "Hello from python script")
# share a file
slack.upload_file(["channel_1", "channel_2"], "my_slack_file.txt")
API
- class parsons.Slack(api_key=None)[source]
- channels(fields=['id', 'name'], exclude_archived=False, types=['public_channel'])[source]
Return a list of all channels in a Slack team.
- Args:
- fields: list
A list of the fields to return. By default, only the channel id and name are returned. See https://api.slack.com/methods/conversations.list for a full list of available fields. Notes: nested fields are unpacked.
- exclude_archived: bool
Set to True to exclude archived channels from the list. Default is false.
- types: list
Mix and match channel types by providing a list of any combination of public_channel, private_channel, mpim (aka group messages), or im (aka 1-1 messages).
- Returns:
- Parsons Table
See Parsons Table for output options.
- users(fields=['id', 'name', 'deleted', 'profile_real_name_normalized', 'profile_email'])[source]
Return a list of all users in a Slack team.
- Args:
- fields: list
A list of the fields to return. By default, only the user id and name and deleted status are returned. See https://api.slack.com/methods/users.list for a full list of available fields. Notes: nested fields are unpacked.
- Returns:
- Parsons Table
See Parsons Table for output options.
- classmethod message(channel, text, webhook=None, parent_message_id=None)[source]
Send a message to a Slack channel with a webhook instead of an api_key. You might not have the full-access API key but still want to notify a channel Args:
- channel: str
The name or id of a public_channel, a private_channel, or an im (aka 1-1 message).
- text: str
Text of the message to send.
- webhook: str
If you have a webhook url instead of an api_key Looks like: https://hooks.slack.com/services/Txxxxxxx/Bxxxxxx/Dxxxxxxx
- parent_message_id: str
The ts value of the parent message. If used, this will thread the message.
- message_channel(channel, text, parent_message_id=None, **kwargs)[source]
Send a message to a Slack channel
- Args:
- channel: str
The name or id of a public_channel, a private_channel, or an im (aka 1-1 message).
- text: str
Text of the message to send.
- parent_message_id: str
The ts value of the parent message. If used, this will thread the message.
- **kwargs: kwargs
- as_user: str
This is a deprecated argument. Use optional username, icon_url, and icon_emoji args to customize the attributes of the user posting the message. See https://api.slack.com/methods/chat.postMessage#legacy_authorship for more information about legacy authorship
Additional arguments for chat.postMessage API call. See documentation <https://api.slack.com/methods/chat.postMessage>` for more info.
- Returns:
- dict:
A response json
- upload_file(channels, filename, filetype=None, initial_comment=None, title=None, is_binary=False)[source]
Upload a file to Slack channel(s).
- Args:
- channels: list
The list of channel names or IDs where the file will be shared.
- filename: str
The path to the file to be uploaded.
- filetype: str
A file type identifier. If None, type will be inferred base on file extension. This is used to determine what fields are available for that object. See https://api.slack.com/types/file for a list of valid types and for more information about the file object.
- initial_comment: str
The text of the message to send along with the file.
- title: str
Title of the file to be uploaded.
- is_binary: bool
If True, open this file in binary mode. This is needed if uploading binary files. Defaults to False.
- Returns:
- dict:
A response json
Gmail
Overview
The Gmail module leverages the Gmail API and provides an way to easily send notifications through email. It is recommended that you reference the Gmail API documentation for additional details and information.
Note
- Credentials and token
Credentials are required to use the class
You will need to pass in the path to the credentials and to where a generated token will be saved. Typically you’ll get the credentials from the Google Developer Console (look for the “Gmail API”).
Note
- 6MB Attachment Size Limit
Currently there is a limit of 6MB when sending attachments.
QuickStart
To call the Gmail class you will need to pass in the path to a credentials.json and the path to tokens.json.
from parsons import Gmail
gmail = Gmail(
creds_path="~/secret_location/credentials.json",
token_path="~/secret_location/token.json")
The easiest way to send a message:
gmail.send_email(
"sender@email.com",
"recipient@email.com",
"The Subject",
"This is the text body of the email")
The current version also supports sending html emails and emails with attachments.
gmail.send_email(
"sender@email.com",
"recipient@email.com",
"An html email with attachments",
"This is the text body of the email",
html="<p>This is the html part of the email</p>",
files=['file1.txt', 'file2.txt'])
Additionally, you can create a raw email messages and send it. See below for more details.
API
- class parsons.Gmail(creds_path=None, token_path=None, user_id='me')[source]
Create a Gmail object, for sending emails.
- Args:
- creds_path: str
The path to the credentials.json file.
- token_path: str
The path to the token.json file.
- user_id: str
Optional; Sender email address. Defaults to the special value “me” which is used to indicate the authenticated user.
- send_email(sender, to, subject, message_text, message_html=None, files=None)
Send an email message.
- Args:
- sender: str
Email address of the sender.
- to: str or list
Email address(es) of the receiver(s). Must be in correct email string syntax. For example, name@email.com or “Name” <email@email.com>.
- subject: str
The subject of the email message.
- message_text: str
The text of the email message.
- message_html: str
The html formatted text of the email message. If ommitted, the email is sent a text-only body.
- files: str or list
The path to the file(s) to be attached.
- Returns:
None
:inherited-members:
SMTP
Overview
The SMTP module enables the sending of email through a generic SMTP server. If you have an email server other than Gmail this is likely the best way to send emails with Parsons.
Note
- Credentials
Credentials are required to use the class. You’ll need to provide a valid username and password for the SMTP server you are using.
QuickStart
To initialize the SMTP class you will need to tell it how to connect to the SMTP server:
from parsons import SMTP
smtp = SMTP(
host="fake.host.com",
port=9999,
username="my_username",
password="dont_use_this_password"
)
Note
- Environment Variables
Instead of passing in values to initialize an instance of the SMTP class, you can set environment variables to hold the values. The names of the environment variables are the names of the arguments capitalized and prefixed with
SMTP_
. For example,SMTP_HOST
orSMTP_PASSWORD
. If both an environment variable and an initialization argument are present, the argument will take precedence.
The easiest way to send a message:
smtp.send_email(
"sender@email.com",
"recipient@email.com",
"The Subject",
"This is the text body of the email"
)
The current version also supports sending html emails and emails with attachments.
smtp.send_email(
"sender@email.com",
"recipient@email.com",
"An html email with attachments",
"This is the text body of the email",
html="<p>This is the html part of the email</p>",
files=['file1.txt', 'file2.txt']
)
API
- class parsons.SMTP(host=None, port=None, username=None, password=None, tls=None, close_manually=False)[source]
Create a SMTP object, for sending emails.
- Args:
- host: str
The host of the SMTP server
- port: int
The port of the SMTP server (Default is 587 for TLS)
- username: str
The username of the SMTP server login
- password: str
The password of the SMTP server login
- tls: bool
Defaults to True – pass “0” or “False” to SMTP_TLS to disable
- close_manually: bool
When set to True, send_message will not close the connection
- send_email(sender, to, subject, message_text, message_html=None, files=None)
Send an email message.
- Args:
- sender: str
Email address of the sender.
- to: str or list
Email address(es) of the receiver(s). Must be in correct email string syntax. For example, name@email.com or “Name” <email@email.com>.
- subject: str
The subject of the email message.
- message_text: str
The text of the email message.
- message_html: str
The html formatted text of the email message. If ommitted, the email is sent a text-only body.
- files: str or list
The path to the file(s) to be attached.
- Returns:
None