core.utils.fetchers package¶

core.utils.fetchers package containing the email fetcher classes for Eonvelope project.

class core.utils.fetchers.BaseFetcher(account)[source]¶

Bases: ABC

Template class for the mailfetcher classes.

Provides arg-checking for methods.

Parameters:: account (Account)

PROTOCOL = ''¶: Name of the used protocol, should be one of MailFetchingProtocols.

AVAILABLE_FETCHING_CRITERIA: tuple[str, ...] = ('',)¶: Tuple of all criteria available for fetching. Should refer to MailFetchingCriteria. Must be immutable!

DEFAULT_FETCHING_CRITERION = <core.utils.FetchingCriterion.FetchingCriterion object>¶: Default criterion to use for fetching emails with the fetcher class.

abstractmethod __init__(account)[source]¶

Constructor basis, sets up the instance logger.

Parameters:: account (Account) – The model of the account to fetch from.
Return type:: None

abstractmethod connect_to_host()[source]¶

Opens the connection to the mailserver.

Return type:: None

abstractmethod test(mailbox=None)[source]¶

Tests the connection to the mailaccount and, if given, the mailbox.

Parameters:: mailbox (Mailbox | None) – The mailbox to be tested. Default is None.
Raises:: ValueError – If the mailbox argument does not belong to self.account.
Return type:: None

abstractmethod fetch_emails(mailbox, criterion=<core.utils.FetchingCriterion.FetchingCriterion object>)[source]¶

Fetches emails based on a criterion from the server.

Parameters:

mailbox (Mailbox) – The model of the mailbox to fetch data from.
criterion (FetchingCriterion) – Formatted criterion to filter mails by. Defaults to core.constants.EmailFetchingCriterionChoices.ALL.

Yields:

Mails in the mailbox matching the criterion as bytes.

Raises:

ValueError – If the fetching_criterion is not available for this fetcher.

Return type:

Generator[bytes]

abstractmethod fetch_mailboxes()[source]¶

Fetches all mailbox names from the server.

Return type:: list[tuple[str, str]]
Returns:: List of data of all mailboxes in the account. Empty if none are found.

abstractmethod restore(email)[source]¶

Restores an email to a mailbox.

Parameters:

email (Email) – The email to restore.

Raises:

ValueError – If the emails mailbox is not in this fetchers account.
FileNotFoundError – If the emails file_path is not set.

Return type:

None

abstractmethod close()[source]¶

Closes the connection to the mail server.

Return type:: None

__str__()[source]¶

Returns a string representation of the BaseFetcher instances.

Return type:: str
Returns:: The string representation of the fetcher instance.

class core.utils.fetchers.ExchangeFetcher(account)[source]¶

Bases: BaseFetcher

Maintains a connection to the Exchange server and fetches data using imaplib.

Opens a connection to the Exchange server on construction and is preferably used in a ‘with’ environment. Allows fetching of mails and mailboxes from an account on an Exchange host.

Parameters:: account (Account)

PROTOCOL = 'EXCHANGE'¶: Name of the used protocol, refers to MailFetchingProtocols.Exchange.

AVAILABLE_FETCHING_CRITERIA: tuple[str, ...] = (EmailFetchingCriterionChoices.ALL, EmailFetchingCriterionChoices.SEEN, EmailFetchingCriterionChoices.UNSEEN, EmailFetchingCriterionChoices.DRAFT, EmailFetchingCriterionChoices.UNDRAFT, EmailFetchingCriterionChoices.DAILY, EmailFetchingCriterionChoices.WEEKLY, EmailFetchingCriterionChoices.MONTHLY, EmailFetchingCriterionChoices.ANNUALLY, EmailFetchingCriterionChoices.SUBJECT, EmailFetchingCriterionChoices.BODY)¶: Tuple of all criteria available for fetching. Refers to EmailFetchingCriterionChoices. Constructed analogous to the IMAP4 criteria. Must be immutable!

EMAIL_FETCH_BATCH_SIZE = 20¶

__init__(account)[source]¶

Constructor, starts the Exchange connection and logs into the account.

Parameters:: account (Account) – The model of the account to be fetched from.
Return type:: None

connect_to_host()[source]¶

Opens the connection to the Exchange server using the credentials from account.

Raises:: MailAccountError – If an error occurs accessing the msg_folder_root.
Return type:: None

test(mailbox=None)[source]¶

Tests the connection to the mailserver and, if a mailbox is provided, whether it can be opened and listed.

Parameters:

mailbox (Mailbox | None) – The mailbox to be tested. Default is None.

Raises:

ValueError – If the mailbox does not belong to self.account.
MailAccountError – If the account test fails because an error occurs or a bad response is returned.
MailboxError – If the mailbox test fails because an error occurs or a bad response is returned testing the mailbox.

Return type:

None

fetch_emails(mailbox, criterion=<core.utils.FetchingCriterion.FetchingCriterion object>)[source]¶

Fetches and returns maildata from a mailbox based on a given criterion.

Todo

Rewrite this into a generator.

Parameters:

mailbox (Mailbox) – Database model of the mailbox to fetch data from.
criterion (FetchingCriterion) – Formatted criterion to filter mails in the Exchange server. Defaults to eonvelope.MailFetchingCriteria.ALL.

Yields:

Mails in the mailbox matching the criterion as bytes.

Raises:

ValueError – If the mailbox does not belong to self.account. If criterion is not in ExchangeFetcher.AVAILABLE_FETCHING_CRITERIA.
MailboxError – If an error occurs or a bad response is returned during an action on the mailbox..

Return type:

Generator[bytes]

fetch_mailboxes()[source]¶

Retrieves and returns the data of the mailboxes in the account.

Todo

Rewrite this into a generator.

Note

Considers only children of the msg_folder_root.

Return type:: list[tuple[str, str]]
Returns:: List of paths of all mailboxes in the account relative to the parent folder of the inbox. Empty if none are found.
Raises:: MailAccountError – If an error occurs or a bad response is returned.

restore(email)[source]¶

Places an email in its mailbox.

Parameters:

email (Email) – The email to restore.

Raises:

ValueError – If the emails mailbox is not in this fetchers account.
FileNotFoundError – If the email has no eml file in storage.
MailboxError – If uploading the email to the mailserver fails or returns a bad response.

Return type:

None

close()[source]¶

No cleanup of exchangelib.Account required.

Return type:: None

open_mailbox(mailbox)[source]¶

Helper method to correctly open a mailbox folder.

Note

This may cause problems with mailboxes that have / in their name (should be very uncommon).

Return type:: Folder
Returns:: The mailbox folder instance.
Parameters:: mailbox (Mailbox)

class core.utils.fetchers.IMAP4Fetcher(account)[source]¶

Bases: BaseFetcher, SafeIMAPMixin

Maintains a connection to the IMAP server and fetches data using imaplib.

Opens a connection to the IMAP server on construction and is preferably used in a ‘with’ environment. Allows fetching of mails and mailboxes from an account on an IMAP host.

Parameters:: account (Account)

PROTOCOL = 'IMAP'¶: Name of the used protocol, refers to MailFetchingProtocols.IMAP.

AVAILABLE_FETCHING_CRITERIA: tuple[str, ...] = (EmailFetchingCriterionChoices.ALL, EmailFetchingCriterionChoices.UNSEEN, EmailFetchingCriterionChoices.SEEN, EmailFetchingCriterionChoices.RECENT, EmailFetchingCriterionChoices.NEW, EmailFetchingCriterionChoices.OLD, EmailFetchingCriterionChoices.FLAGGED, EmailFetchingCriterionChoices.UNFLAGGED, EmailFetchingCriterionChoices.DRAFT, EmailFetchingCriterionChoices.UNDRAFT, EmailFetchingCriterionChoices.ANSWERED, EmailFetchingCriterionChoices.UNANSWERED, EmailFetchingCriterionChoices.DELETED, EmailFetchingCriterionChoices.UNDELETED, EmailFetchingCriterionChoices.DAILY, EmailFetchingCriterionChoices.WEEKLY, EmailFetchingCriterionChoices.MONTHLY, EmailFetchingCriterionChoices.ANNUALLY, EmailFetchingCriterionChoices.SENTSINCE, EmailFetchingCriterionChoices.SUBJECT, EmailFetchingCriterionChoices.BODY, EmailFetchingCriterionChoices.FROM, EmailFetchingCriterionChoices.KEYWORD, EmailFetchingCriterionChoices.UNKEYWORD, EmailFetchingCriterionChoices.LARGER, EmailFetchingCriterionChoices.SMALLER)¶: Tuple of all criteria available for fetching. Refers to MailFetchingCriteria. Must be immutable! IMAP4 does not accept time lookups, only date based. For a list of all existing IMAP criteria see https://datatracker.ietf.org/doc/html/rfc3501.html#section-6.4.4.

EMAIL_FETCH_BATCH_SIZE = 100¶

__init__(account)[source]¶

Constructor, starts the IMAP connection and logs into the account.

Parameters:: account (Account) – The model of the account to be fetched from.
Return type:: None

connect_to_host()[source]¶

Opens the connection to the IMAP server using the credentials from account.

Raises:: MailAccountError – If an error occurs or a bad response is returned.
Return type:: None

test(mailbox=None)[source]¶

Tests the connection to the mailserver and, if a mailbox is provided, whether it can be opened and listed.

Parameters:

mailbox (Mailbox | None) – The mailbox to be tested. Default is None.

Raises:

ValueError – If the mailbox does not belong to self.account.
MailAccountError – If the account test fails because an error occurs or a bad response is returned.
MailboxError – If the mailbox test fails because an error occurs or a bad response is returned testing the mailbox.

Return type:

None

fetch_emails(mailbox, criterion=<core.utils.FetchingCriterion.FetchingCriterion object>)[source]¶

Fetches and returns maildata from a mailbox based on a given criterion.

Parameters:

mailbox (Mailbox) – Database model of the mailbox to fetch data from.
criterion (FetchingCriterion) – Formatted criterion to filter mails in the IMAP request. Defaults to eonvelope.MailFetchingCriteria.ALL.

Yields:

Mails in the mailbox matching the criterion as bytes.

Raises:

ValueError – If the mailbox does not belong to self.account. If criterion is not in IMAP4Fetcher.AVAILABLE_FETCHING_CRITERIA.
MailboxError – If an error occurs or a bad response is returned during an action on the mailbox.

Return type:

Generator[bytes]

fetch_mailboxes()[source]¶

Retrieves and returns the data of the mailboxes in the account.

Todo

Rewrite this into a generator.

Return type:: list[tuple[str, str]]
Returns:: List of data of all mailboxes in the account. Empty if none are found.
Raises:: MailAccountError – If an error occurs or a bad response is returned.

restore(email)[source]¶

Places an email in its mailbox.

Parameters:

email (Email) – The email to restore.

Raises:

ValueError – If the emails mailbox is not in this fetchers account.
FileNotFoundError – If the email has no eml file in storage.
MailboxError – If uploading the email to the mailserver fails or returns a bad response.

Return type:

None

close()[source]¶

Logs out of the account and closes the connection to the IMAP server if it is open.

Return type:: None

class core.utils.fetchers.IMAP4_SSL_Fetcher(account)[source]¶

Bases: IMAP4Fetcher

Subclass of core.utils.fetchers.IMAP4Fetcher.

Does the same things, just using IMAP4_SSL protocol.

Parameters:: account (Account)

PROTOCOL = 'IMAP4_SSL'¶: Name of the used protocol, refers to constants.MailFetchingProtocols.IMAP4_SSL.

connect_to_host()[source]¶

Overrides core.utils.fetchers.IMAP4Fetcher.connect_to_host() to use imaplib.IMAP4_SSL.

Important

Using ssl_context is urgently required, see https://www.pentagrid.ch/en/blog/python-mail-libraries-certificate-verification/ .

Return type:: None

class core.utils.fetchers.JMAPFetcher(account)[source]¶

Bases: BaseFetcher

Maintains a connection to the JMAP server and fetches data using jmapc.

Opens a connection to the JMAP server on construction and is preferably used in a ‘with’ environment. Allows fetching of mails and mailboxes from an account on an JMAP host.

Parameters:: account (Account)

PROTOCOL = 'JMAP'¶: Name of the used protocol, refers to MailFetchingProtocols.JMAP.

AVAILABLE_FETCHING_CRITERIA: tuple[str, ...] = (EmailFetchingCriterionChoices.ALL, EmailFetchingCriterionChoices.SEEN, EmailFetchingCriterionChoices.UNSEEN, EmailFetchingCriterionChoices.DRAFT, EmailFetchingCriterionChoices.UNDRAFT, EmailFetchingCriterionChoices.ANSWERED, EmailFetchingCriterionChoices.UNANSWERED, EmailFetchingCriterionChoices.DAILY, EmailFetchingCriterionChoices.WEEKLY, EmailFetchingCriterionChoices.MONTHLY, EmailFetchingCriterionChoices.ANNUALLY, EmailFetchingCriterionChoices.BODY, EmailFetchingCriterionChoices.FROM, EmailFetchingCriterionChoices.SENTSINCE, EmailFetchingCriterionChoices.LARGER, EmailFetchingCriterionChoices.SMALLER)¶: Tuple of all criteria available for fetching. Refers to MailFetchingCriteria. Must be immutable!

__init__(account)[source]¶

Constructor basis, sets up the instance logger.

Parameters:: account (Account) – The model of the account to fetch from.
Return type:: None

connect_to_host()[source]¶

Opens the connection to the mailserver.

Return type:: None

test(mailbox=None)[source]¶

Tests the connection to the mailaccount and, if given, the mailbox.

Parameters:: mailbox (Mailbox | None) – The mailbox to be tested. Default is None.
Raises:: ValueError – If the mailbox argument does not belong to self.account.
Return type:: None

fetch_emails(mailbox, criterion=<core.utils.FetchingCriterion.FetchingCriterion object>)[source]¶

Fetches emails based on a criterion from the server.

Parameters:

mailbox (Mailbox) – The model of the mailbox to fetch data from.
criterion (FetchingCriterion) – Formatted criterion to filter mails by. Defaults to core.constants.EmailFetchingCriterionChoices.ALL.

Yields:

Mails in the mailbox matching the criterion as bytes.

Raises:

ValueError – If the fetching_criterion is not available for this fetcher.

Return type:

Generator[bytes]

fetch_mailboxes()[source]¶

Fetches all mailbox names from the server.

Return type:: list[tuple[str, str]]
Returns:: List of data of all mailboxes in the account. Empty if none are found.

restore(email)[source]¶

Restores an email to a mailbox.

Parameters:

email (Email) – The email to restore.

Raises:

ValueError – If the emails mailbox is not in this fetchers account.
FileNotFoundError – If the emails file_path is not set.

Return type:

None

close()[source]¶

No cleanup of jmapc.Client required.

Return type:: None

class core.utils.fetchers.POP3Fetcher(account)[source]¶

Bases: BaseFetcher, SafePOPMixin

Maintains a connection to the POP server and fetches data using poplib.

Opens a connection to the POP server on construction and is preferably used in a ‘with’ environment. Allows fetching of mails and mailboxes from an account on an POP host.

Since POP does not have any mailboxes, none of the methods should raise a MailboxError.

Parameters:: account (Account)

PROTOCOL = 'POP3'¶: Name of the used protocol, refers to MailFetchingProtocols.POP3.

AVAILABLE_FETCHING_CRITERIA: tuple[str, ...] = (EmailFetchingCriterionChoices.ALL,)¶: Tuple of all criteria available for fetching. Refers to MailFetchingCriteria. Must be immutable!

__init__(account)[source]¶

Constructor, starts the POP connection and logs into the account.

Parameters:: account (Account) – The model of the account to be fetched from.
Return type:: None

connect_to_host()[source]¶

Opens the connection to the POP server using the credentials from account.

Raises:: MailAccountError – If an error occurs or a bad response is returned.
Return type:: None

test(mailbox=None)[source]¶

Tests the connection to the mailserver and, if a mailbox is provided, whether messages can be listed.

Parameters:

mailbox (Mailbox | None) – The mailbox to be tested. Default is None.

Raises:

ValueError – If the mailbox does not belong to self.account.
MailAccountError – If the test fails because an error occurs or a bad response is returned.

Return type:

None

fetch_emails(mailbox, criterion=<core.utils.FetchingCriterion.FetchingCriterion object>)[source]¶

Fetches and returns all maildata from the server.

Parameters:

mailbox (Mailbox) – Database model of the mailbox to fetch data from.
criterion (FetchingCriterion) – POP only supports ALL lookups. Defaults to eonvelope.MailFetchingCriteria.ALL. This arg ensures compatibility with the other fetchers.

Yields:

Mails in the mailbox.

Raises:

ValueError – If the mailbox does not belong to self.account. If criterion is not eonvelope.MailFetchingCriteria.ALL.
MailAccountError – If an error occurs or a bad response is returned.

Return type: