`airflow.providers.imap.hooks.imap`¶

This module provides everything to be able to search in mails for a specific attachment and also to download it. It uses the imaplib library that is already integrated in python 3.

Module Contents¶

Classes¶

`ImapHook`	This hook connects to a mail server by using the imap protocol.
`Mail`	This class simplifies working with mails returned by the imaplib client.
`MailPart`	This class is a wrapper for a Mail object's part and gives it more features.

class airflow.providers.imap.hooks.imap.ImapHook(imap_conn_id=default_conn_name)[source]¶

Bases: airflow.hooks.base.BaseHook

This hook connects to a mail server by using the imap protocol.

Note

Please call this Hook as context manager via with to automatically open and close the connection to the mail server.

Parameters: imap_conn_id (str) -- The imap connection id that contains the information used to authenticate the client.

conn_name_attr = imap_conn_id[source]¶

default_conn_name = imap_default[source]¶

conn_type = imap[source]¶

hook_name = IMAP[source]¶

__enter__(self)[source]¶

__exit__(self, exc_type, exc_val, exc_tb)[source]¶

get_conn(self)[source]¶

Login to the mail server.

Note

Please call this Hook as context manager via with to automatically open and close the connection to the mail server.

Returns: an authorized ImapHook object.
Return type: ImapHook

has_mail_attachment(self, name, *, check_regex=False, mail_folder='INBOX', mail_filter='All')[source]¶

Checks the mail folder for mails containing attachments with the given name.

Parameters

name (str) -- The name of the attachment that will be searched for.
check_regex (bool) -- Checks the name for a regular expression.
mail_folder (str) -- The mail folder where to look at.
mail_filter (str) -- If set other than 'All' only specific mails will be checked. See imaplib.IMAP4.search() for details.

Returns

True if there is an attachment with the given name and False if not.

Return type

bool

retrieve_mail_attachments(self, name, *, check_regex=False, latest_only=False, mail_folder='INBOX', mail_filter='All', not_found_mode='raise')[source]¶

Retrieves mail's attachments in the mail folder by its name.

Parameters

name (str) -- The name of the attachment that will be downloaded.
check_regex (bool) -- Checks the name for a regular expression.
latest_only (bool) -- If set to True it will only retrieve the first matched attachment.
mail_folder (str) -- The mail folder where to look at.
mail_filter (str) -- If set other than 'All' only specific mails will be checked. See imaplib.IMAP4.search() for details.
not_found_mode (str) -- Specify what should happen if no attachment has been found. Supported values are 'raise', 'warn' and 'ignore'. If it is set to 'raise' it will raise an exception, if set to 'warn' it will only print a warning and if set to 'ignore' it won't notify you at all.

Returns

a list of tuple each containing the attachment filename and its payload.

Return type

a list of tuple

download_mail_attachments(self, name, local_output_directory, *, check_regex=False, latest_only=False, mail_folder='INBOX', mail_filter='All', not_found_mode='raise')[source]¶

Downloads mail's attachments in the mail folder by its name to the local directory.

Parameters

name (str) -- The name of the attachment that will be downloaded.
local_output_directory (str) -- The output directory on the local machine where the files will be downloaded to.
check_regex (bool) -- Checks the name for a regular expression.
latest_only (bool) -- If set to True it will only download the first matched attachment.
mail_folder (str) -- The mail folder where to look at.
mail_filter (str) -- If set other than 'All' only specific mails will be checked. See imaplib.IMAP4.search() for details.
not_found_mode (str) -- Specify what should happen if no attachment has been found. Supported values are 'raise', 'warn' and 'ignore'. If it is set to 'raise' it will raise an exception, if set to 'warn' it will only print a warning and if set to 'ignore' it won't notify you at all.

class airflow.providers.imap.hooks.imap.Mail(mail_body)[source]¶

Bases: airflow.utils.log.logging_mixin.LoggingMixin

This class simplifies working with mails returned by the imaplib client.

Parameters: mail_body (str) -- The mail body of a mail received from imaplib client.

has_attachments(self)[source]¶

Checks the mail for a attachments.

Returns: True if it has attachments and False if not.
Return type: bool

get_attachments_by_name(self, name, check_regex, find_first=False)[source]¶

Gets all attachments by name for the mail.

Parameters

name (str) -- The name of the attachment to look for.
check_regex (bool) -- Checks the name for a regular expression.
find_first (bool) -- If set to True it will only find the first match and then quit.

Returns

a list of tuples each containing name and payload where the attachments name matches the given name.

Return type

list(tuple)

class airflow.providers.imap.hooks.imap.MailPart(part)[source]¶

This class is a wrapper for a Mail object's part and gives it more features.

Parameters: part (Any) -- The mail part in a Mail object.

is_attachment(self)[source]¶

Checks if the part is a valid mail attachment.

Returns: True if it is an attachment and False if not.
Return type: bool

has_matching_name(self, name)[source]¶

Checks if the given name matches the part's name.

Parameters: name (str) -- The name to look for.
Returns: True if it matches the name (including regular expression).
Return type: tuple

has_equal_name(self, name)[source]¶

Checks if the given name is equal to the part's name.

Parameters: name (str) -- The name to look for.
Returns: True if it is equal to the given name.
Return type: bool

get_file(self)[source]¶

Gets the file including name and payload.

Returns: the part's name and payload.
Return type: tuple

airflow.providers.imap.hooks.imap¶

Module Contents¶

Classes¶

`airflow.providers.imap.hooks.imap`¶