core.models.Mailbox module

Module with the Mailbox model class.

core.models.Mailbox.logger = <Logger core.models.Mailbox (INFO)>

The logger instance for this module.

class core.models.Mailbox.Mailbox(*args, **kwargs)

Bases: ExportModelOperationsMixin('mailbox'), DirtyFieldsMixin, URLMixin, UploadMixin, DownloadMixin, FavoriteModelMixin, HealthModelMixin, TimestampModelMixin, Model

Database model for a mailbox in a mail account.

BASENAME = 'mailbox'

DELETE_NOTICE = 'This will delete the record of this mailbox and all emails and attachments found in it!'

DELETE_NOTICE_PLURAL = 'This will delete the records of these mailboxes and all emails and attachments found in them!'

name

The mailaccount internal name of the mailbox. Unique together with account.

type

The mailaccount internal role or distinguished id of the mailbox.

account: models.ForeignKey[Account]

The mailaccount this mailbox was found in. Unique together with name. Deletion of that account deletes this mailbox.

save_attachments

Whether to save attachments of the mails found in this mailbox. constance.get_config('DEFAULT_SAVE_ATTACHMENTS') by default.

save_to_eml

Whether to save the mails found in this mailbox as .eml files. constance.get_config('DEFAULT_SAVE_TO_EML') by default.

__str__()

Returns a string representation of the model data.

Return type:

str

Returns:

The string representation of the mailbox, using name and account.

test()

Tests whether the data in the model is correct.

Tests connecting and logging in to the mailhost and account. The core.models.Mailbox.is_healthy flag is set accordingly. Relies on the test method of the core.utils.fetchers classes.

Raises:

• MailAccountError – If the test is fails due to an issue with the account.

• MailboxError – If the test is fails due to an issue with the mailbox.

Return type:

None

fetch(criterion)

Fetches emails from this mailbox based on criterion and adds them to the db.

If successful, marks this mailbox as healthy, otherwise unhealthy.

Parameters:

criterion (FetchingCriterion) – The criterion used to fetch emails from the mailbox.

Raises:

• MailboxError – Reraised if fetching failed due to a MailboxError.

• MailAccountError – Reraised if fetching failed due to a MailAccountError.

Return type:

None

_add_email_from_eml(file)

Reads emails from a zipped mailbox dir.

Return type:

None

Parameters:

file (BinaryIO)

_add_emails_from_zip_eml(file)

Reads emails from a zip of eml files.

Return type:

None

Parameters:

file (BinaryIO)

_add_emails_from_mailbox_file(file, file_format)

Reads emails from a mailbox file.

Note

Does not validate file_format! This has to be done beforehand.

Return type:

None

Parameters:

• file (BinaryIO)

• file_format (str)

_add_emails_from_mailbox_zip(file, file_format)

Reads emails from a zipped mailbox dir.

Note

Does not validate file_format! This has to be done beforehand.

Return type:

None

Parameters:

• file (BinaryIO)

• file_format (str)

add_emails_from_file(file, file_format)

Adds emails from a file to the db.

Parameters:

• file (BinaryIO) – The mailbox file.

• file_format (str) – The format of the mailbox file. Case-insensitive.

Raises:

ValueError – If the file format is not implemented or the file failed to open.

Return type:

None

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

_meta = <Options for Mailbox>

account_id

created

The datetime the model instance was created. Is set automatically.

daemons

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

emails

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

get_next_by_created(*, field=<django.db.models.fields.DateTimeField: created>, is_next=True, **kwargs)

get_next_by_updated(*, field=<django.db.models.fields.DateTimeField: updated>, is_next=True, **kwargs)

get_previous_by_created(*, field=<django.db.models.fields.DateTimeField: created>, is_next=False, **kwargs)

get_previous_by_updated(*, field=<django.db.models.fields.DateTimeField: updated>, is_next=False, **kwargs)

get_type_display(*, field=<django.db.models.fields.CharField: type>)

property has_download: bool

Checks whether a download is possible for the instance.

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

is_favorite

Flags favorite accounts. False by default.

is_healthy

Flags whether the model instance is subject to errors. None by default.

last_error

The latest error in connection with the model instance.

last_error_occurred_at

The time of occurrence of the latest error.

objects = <django.db.models.manager.Manager object>

updated

The datetime the model instance entry was last updated. Is set automatically.

property available_fetching_criteria: tuple[str, ...]

Gets the available fetching criteria based on the mail protocol of this mailbox.

Returns:

A tuple of all available fetching criteria for this mailbox.

Raises:

ValueError – If the account has an unimplemented protocol.

property available_no_arg_fetching_criteria: tuple[str, ...]

Gets the available fetching criteria that do not require an argument based on the mail protocol of this mailbox.

Returns:

A tuple of all available fetching criteria that do not require an argument for this mailbox.

Raises:

ValueError – If the account has an unimplemented protocol.

property available_fetching_criterion_choices: list[tuple[str, StrOrPromise]]

Gets the available fetching criterion choices based on the mail protocol of this mailbox.

Returns:

A choices-type tuple of all available fetching criteria for this mailbox.

Raises:

ValueError – If the account has an unimplemented protocol.

property available_no_arg_fetching_criterion_choices: list[tuple[str, StrOrPromise]]

Gets the available fetching criterion choices that do not require an argumentbased on the mail protocol of this mailbox.

Returns:

A choices-type tuple of all available fetching criteria that do not require an argument for this mailbox.

Raises:

ValueError – If the account has an unimplemented protocol.

property available_download_formats: list[tuple[str, StrOrPromise]]

Get all formats that emails in this mailbox can be downloaded in.

Returns:

A list of download formats and format names.

classmethod create_from_data(mailbox_name, mailbox_type, account)

Creates a core.models.Mailbox from the mailboxdata.

Note

Mailbox created from data is considered healthy by default.

Parameters:

• mailbox_name (str) – The name of the mailbox.

• mailbox_type (str) – The type of the mailbox.

• account (Account) – The account the mailbox is in.

Return type:

Mailbox | None

Returns:

The core.models.Mailbox instance with data from the bytes. None if the mailbox name is ignored.

Raises:

ValueError – If the given account is not in the db.

static queryset_as_file(queryset, file_format)

Processes the files of the emails in the mailboxes in the queryset into a temporary file.

Parameters:

• queryset (QuerySet) – The mailbox queryset to compile into a file.

• file_format (str) – The desired format of the mailbox files. Must be one of core.constants.SupportedEmailDownloadFormats. Case-insensitive.

Return type:

_TemporaryFileWrapper

Returns:

The temporary file wrapper.

Raises:

• ValueError – If the given file_format is not supported.

• Mailbox.DoesNotExist – If the queryset is empty.