`pymap.backend`¶

Contents:

pymap.backend.backends: Plugin[BackendInterface] = Plugin('pymap.backend')¶: Registers new backend plugins.

`pymap.backend.mailbox`¶

class pymap.backend.mailbox.MailboxDataT¶

Type variable with an upper bound of MailboxDataInterface.

alias of TypeVar(‘MailboxDataT’, bound=MailboxDataInterface[Any])

class pymap.backend.mailbox.MailboxDataT_co¶

Covariant type variable with an upper bound of MailboxDataInterface.

alias of TypeVar(‘MailboxDataT_co’, bound=MailboxDataInterface[Any], covariant=True)

class pymap.backend.mailbox.MailboxDataInterface(*args, **kwargs)[source]¶

Manages the messages and metadata associated with a single mailbox.

abstract property mailbox_id: ObjectId¶: The mailbox object ID.

See also

mailbox_id

abstract property readonly: bool¶: Whether the mailbox is read-only or read-write.

abstract property uid_validity: int¶: The mailbox UID validity value.

property permanent_flags: frozenset[Flag]¶: The permanent flags allowed in the mailbox.

property session_flags: frozenset[Flag]¶: The session flags allowed in the mailbox.

abstract property selected_set: SelectedSet¶: The set of selected mailbox sessions currently active.

abstract async update_selected(selected, *, wait_on=None)[source]¶

Populates and returns the selected mailbox object with the state needed to discover updates.

Parameters:

selected (SelectedMailbox) – the selected mailbox object.
wait_on (Event | None) – If given, block until this event signals or mailbox activity occurs.

Return type:

SelectedMailbox

abstract async append(append_msg, *, recent=False)[source]¶

Adds a new message to the end of the mailbox, returning a copy of message with its assigned UID.

Parameters:

append_msg (AppendMessage) – The new message data.
recent (bool) – True if the message should be marked recent.

Return type:

MessageT_co

abstract async copy(uid, destination, *, recent=False)[source]¶

Copies a message, if it exists, from this mailbox to the destination mailbox.

Parameters:

uid (int) – The UID of the message to copy.
destination (MailboxDataT) – The destination mailbox.
recent (bool) – True if the message should be marked recent.
self (MailboxDataT)

Return type:

int | None

abstract async move(uid, destination, *, recent=False)[source]¶

Moves a message, if it exists, from this mailbox to the destination mailbox.

Parameters:

uid (int) – The UID of the message to move.
destination (MailboxDataT) – The destination mailbox.
recent (bool) – True if the message should be marked recent.
self (MailboxDataT)

Return type:

int | None

abstract async get(uid, cached_msg)[source]¶

Return the message with the given UID.

Parameters:

uid (int) – The message UID.
cached_msg (CachedMessage) – The last known cached message.

Return type:

MessageT_co

abstract async update(uid, cached_msg, flag_set, mode)[source]¶

Update the permanent flags of the message.

Parameters:

uid (int) – The message UID.
cached_msg (CachedMessage) – The last known cached message.
flag_set (frozenset[Flag]) – The set of flags for the update operation.
flag_op – The mode to change the flags.
mode (FlagOp)

Return type:

MessageT_co

abstract async delete(uids)[source]¶

Delete messages with the given UIDs.

Parameters:: uids (Iterable[int]) – The message UIDs.
Return type:: None

abstract async claim_recent(selected)[source]¶

Messages that are newly added to the mailbox are assigned the \Recent flag in the current selected mailbox session.

Parameters:: selected (SelectedMailbox) – The selected mailbox session.
Return type:: None

abstract async cleanup()[source]¶

Perform any necessary “housekeeping” steps. This may be a slow operation, and may run things like garbage collection on the backend.

See also

check_mailbox()

Return type:: None

abstract async snapshot()[source]¶

Returns a snapshot of the current state of the mailbox.

Return type:: MailboxSnapshot

async find(seq_set, selected)[source]¶

Find the active message UID and message pairs in the mailbox that are contained in the given sequences set. Message sequence numbers are resolved by the selected mailbox session.

Parameters:

seq_set (SequenceSet) – The sequence set of the desired messages.
selected (SelectedMailbox) – The selected mailbox session.

Return type:

AsyncIterable[tuple[int, MessageT_co]]

async find_deleted(seq_set, selected)[source]¶

Return all the active message UIDs that have the \Deleted flag.

Parameters:

seq_set (SequenceSet) – The sequence set of the possible messages.
selected (SelectedMailbox) – The selected mailbox session.

Return type:

Sequence[int]

class pymap.backend.mailbox.MailboxSetInterface(*args, **kwargs)[source]¶

Manages the set of mailboxes available to the authenticated user.

abstract property delimiter: str¶: The delimiter used in mailbox names to indicate hierarchy.

abstract async set_subscribed(name, subscribed)[source]¶

Add or remove the subscribed status of a mailbox.

See also

subscribe() unsubscribe()

Parameters:

name (str) – The name of the mailbox.
subscribed (bool) – True if the mailbox should be subscribed.

Return type:

None

abstract async list_subscribed()[source]¶

Return a list of all subscribed mailboxes.

See also

list_mailboxes()

Return type:: ListTree

abstract async list_mailboxes()[source]¶

Return a list of all mailboxes.

See also

list_mailboxes()

Return type:: ListTree

abstract async get_mailbox(name)[source]¶

Return an existing mailbox by name.

Parameters:: name (str) – The name of the mailbox.
Raises:: KeyError – The mailbox did not exist.
Return type:: MailboxDataT_co

abstract async add_mailbox(name)[source]¶

Create a new mailbox, returning its object ID.

See also

create_mailbox()

Parameters:: name (str) – The name of the mailbox.
Raises:: ValueError – The mailbox already exists.
Return type:: ObjectId

abstract async delete_mailbox(name)[source]¶

Delete an existing mailbox.

See also

delete_mailbox()

Parameters:: name (str) – The name of the mailbox.
Raises:: KeyError – The mailbox did not exist.
Return type:: None

abstract async rename_mailbox(before, after)[source]¶

Rename an existing mailbox.

See also

rename_mailbox()

Parameters:

before (str) – The name of the existing mailbox.
after (str) – The name of the destination mailbox.

Raises:

KeyError – The before mailbox does not exist.
ValueError – The after mailbox already exists.

Return type:

None

`pymap.backend.session`¶

class pymap.backend.session.BaseSession(owner)[source]¶

Base implementation of SessionInterface intended for use by most backends.

Parameters:: owner (str) – The logged-in user name.

property owner: str¶: The SASL authorization identity of the logged-in user.

property filter_set: FilterSetInterface[Any] | None¶: Manages the active and inactive filters for the login user.

close()[source]¶

Called at the end of a session, to clean up any resources.

Return type:: None

async cleanup()[source]¶

Called after every operation, success or failure, to allow the backend to clean up resources.

Note

Any exception raised by this method will be silently ignored.

Return type:: None

async list_mailboxes(ref_name, filter_, subscribed=False, selected=None)[source]¶

List the mailboxes owned by the user.

See also

RFC 3501 6.3.8., RFC 3501 6.3.9.

Parameters:

ref_name (str) – Mailbox reference name.
filter – Mailbox name with possible wildcards.
subscribed (bool) – If True, only list the subscribed mailboxes.
selected (SelectedMailbox | None) – If applicable, the currently selected mailbox name.
filter_ (str)

Return type:

tuple[Iterable[tuple[str, str | None, Sequence[bytes]]], SelectedMailbox | None]

async get_mailbox(name, selected=None)[source]¶

Retrieves a MailboxInterface object corresponding to an existing mailbox owned by the user. Raises an exception if the mailbox does not yet exist.

Parameters:

name (str) – The name of the mailbox.
selected (SelectedMailbox | None) – If applicable, the currently selected mailbox name.

Raises:

MailboxNotFound –

Return type:

tuple[MailboxSnapshot, SelectedMailbox | None]

async create_mailbox(name, selected=None)[source]¶

Creates a new mailbox owned by the user.

See also

RFC 3501 6.3.3.

Parameters:

name (str) – The name of the mailbox.
selected (SelectedMailbox | None) – If applicable, the currently selected mailbox name.

Raises:

MailboxConflict –

Return type:

tuple[ObjectId, SelectedMailbox | None]

async delete_mailbox(name, selected=None)[source]¶

Deletes the mailbox owned by the user.

See also

RFC 3501 6.3.4.

Parameters:

name (str) – The name of the mailbox.
selected (SelectedMailbox | None) – If applicable, the currently selected mailbox name.

Raises:

MailboxNotFound –
MailboxHasChildren –

Return type:

SelectedMailbox | None

async rename_mailbox(before_name, after_name, selected=None)[source]¶

Renames the mailbox owned by the user.

See also

RFC 3501 6.3.5.

Parameters:

before_name (str) – The name of the mailbox before the rename.
after_name (str) – The name of the mailbox after the rename.
selected (SelectedMailbox | None) – If applicable, the currently selected mailbox name.

Raises:

MailboxNotFound –
MailboxConflict –

Return type:

SelectedMailbox | None

async subscribe(name, selected=None)[source]¶

Mark the given folder name as subscribed, whether or not the given folder name currently exists.

See also

RFC 3501 6.3.6.

Parameters:

name (str) – The name of the mailbox.
selected (SelectedMailbox | None) – If applicable, the currently selected mailbox name.

Raises:

MailboxNotFound –

Return type:

SelectedMailbox | None

async unsubscribe(name, selected=None)[source]¶

Remove the given folder name from the subscription list, whether or not the given folder name currently exists.

See also

RFC 3501 6.3.6.

Parameters:

name (str) – The name of the mailbox.
selected (SelectedMailbox | None) – If applicable, the currently selected mailbox name.

Raises:

MailboxNotFound –

Return type:

SelectedMailbox | None

async append_messages(name, messages, selected=None)[source]¶

Appends a message to the end of the mailbox.

See also

RFC 3502 6.3.11.

Parameters:

name (str) – The name of the mailbox.
messages (Sequence[AppendMessage]) – The messages to append.
selected (SelectedMailbox | None) – If applicable, the currently selected mailbox name.

Raises:

MailboxNotFound –
AppendFailure –

Return type:

tuple[AppendUid, SelectedMailbox | None]

async select_mailbox(name, readonly=False)[source]¶

Selects an existing mailbox owned by the user. The returned session is then used as the selected argument to other methods to fetch mailbox updates.

See also

RFC 3501 6.3.1., RFC 3501 6.3.2.

Parameters:

name (str) – The name of the mailbox.
readonly (bool) – True if the mailbox is read-only.

Raises:

MailboxNotFound –

Return type:

tuple[MailboxSnapshot, SelectedMailbox]

async check_mailbox(selected, *, wait_on=None, housekeeping=False)[source]¶

Checks for any updates in the mailbox.

If wait_on is given, this method should block until either this event is signalled or the mailbox has detected updates. This method may be called continuously as long as wait_on is not signalled.

If housekeeping is True, perform any house-keeping necessary by the mailbox backend, which may be a slower operation.

Parameters:

selected (SelectedMailbox) – The selected mailbox session.
wait_on (Event | None) – If given, block until this event signals.
housekeeping (bool) – If True, the backend may perform additional housekeeping operations if necessary.

Raises:

MailboxNotFound –

Return type:

SelectedMailbox

async fetch_messages(selected, sequence_set, set_seen)[source]¶

Get a list of loaded message objects corresponding to given sequence set.

Parameters:

selected (SelectedMailbox) – The selected mailbox session.
sequence_set (SequenceSet) – Sequence set of message sequences or UIDs.
set_seen (bool) – True if the messages should get the \Seen flag.

Raises:

MailboxNotFound –

Return type:

tuple[Iterable[tuple[int, MessageT]], SelectedMailbox]

async search_mailbox(selected, keys)[source]¶

Get the messages in the current mailbox that meet all of the given search criteria.

See also

RFC 3501 7.2.5.

Parameters:

selected (SelectedMailbox) – The selected mailbox session.
keys (frozenset[SearchKey]) – Search keys specifying the message criteria.

Raises:

MailboxNotFound –

Return type:

tuple[Iterable[tuple[int, MessageT]], SelectedMailbox]

async expunge_mailbox(selected, uid_set=None)[source]¶

All messages that are marked as deleted are immediately expunged from the mailbox.

See also

RFC 3501 6.4.3. RFC 4315 2.1

Parameters:

selected (SelectedMailbox) – The selected mailbox session.
uid_set (SequenceSet | None) – Only the messages in the given UID set should be expunged.

Raises: