pymap.selected

class pymap.selected.SelectedSet[source]

Maintains a weak set of SelectedMailbox objects that exist for a mailbox, across all sessions. This is useful for assigning the \Recent flag, as well as notifying other sessions about updates.

add(selected, *, replace=None)[source]

Add a new selected mailbox object to the set, which may then be returned by any_selected().

Parameters:

  • selected (SelectedMailbox) – The new selected mailbox object.

  • replace (SelectedMailbox | None) – An existing selected mailbox object that should be removed from the weak set.

Return type:

None

property any_selected: SelectedMailbox | None

A single, random object in the set of selected mailbox objects. Selected mailbox object’s marked readonly will not be chosen.

class pymap.selected.SynchronizedMessages[source]

Manages the message data that has been synchronized with the client.

property exists: int

The total number of messages in the mailbox.

property max_uid: int

The highest message UID value of the mailbox.

get(uid)[source]

Return the given cached message.

Parameters:

uid (int) – The message UID.

Return type:

CachedMessage | None

get_uids(seq_set)[source]

Return the message sequence numbers and their UIDs for the given sequence set.

Parameters:

seq_set (SequenceSet) – The message sequence set.

Return type:

Sequence[tuple[int, int]]

get_all(seq_set)[source]

Return the cached messages, and their sequence numbers, for the given sequence set.

Parameters:

seq_set (SequenceSet) – The message sequence set.

Return type:

Sequence[tuple[int, CachedMessage]]

class pymap.selected.SelectedMailbox(mailbox_id, readonly, permanent_flags, session_flags, selected_set=None, lookup=None, **kwargs)[source]

Manages the updates to the current selected mailbox from other concurrent sessions.

The current state of the selected mailbox will be written to this object by the backend implementation during each operation. Then, when the operation completes, call fork() to make a fresh copy of the object and any untagged responses that should be added to the response.

Parameters:

  • mailbox_id (ObjectId) – The globally unique identifier of the selected mailbox.

  • readonly (bool) – Indicates the mailbox is selected as read-only.

  • permanent_flags (PermanentFlags) – The defined permanent flags for the mailbox.

  • session_flags (SessionFlags) – Session-only flags for the mailbox.

  • selected_set (SelectedSet | None) – The self object and subsequent forked copies will be kept in in this set.

  • lookup (Any)

  • kwargs (Any)

property mailbox_id: ObjectId

The selected mailbox object ID.

See also

mailbox_id

property lookup: Any

The lookup value, if any, needed by backends that cannot lookup mailboxes by mailbox_id. A typical lookup value might be the name of the mailbox.

property mod_sequence: Any

The highest modification sequence of the mailbox.

property hide_expunged: bool

If True, no untagged EXPUNGE responses will be generated, and message sequence numbers will not be adjusted, until the next fork().

add_updates(messages, expunged)[source]

Update the messages in the selected mailboxes. The messages should include non-expunged messages in the mailbox that should be checked for updates. The expunged argument is the set of UIDs that have been expunged from the mailbox.

In an optimized implementation, messages only includes new messages or messages with metadata updates. This minimizes the comparison needed to determine what untagged responses are necessary. The mod_sequence attribute may be used to support this optimization.

If a backend implementation lacks the ability to determine the subset of messages that have been updated, it should instead use set_messages().

Parameters:
Return type:

None

set_messages(messages)[source]

This is the non-optimized alternative to add_updates() for backend implementations that cannot detect their own updates and must instead compare the entire state of the mailbox.

The messages list should contain the entire set of messages in the mailbox, ordered by UID. Any UID that previously existed and is not included in messages will be expunged.

Parameters:

messages (Sequence[CachedMessage]) – The entire set of cached message objects.

Return type:

None

property readonly: bool

Indicates the mailbox is selected as read-only.

property messages: SynchronizedMessages

The messages in the mailbox, as synchronized with the client.

property permanent_flags: PermanentFlags

The defined permanent flags for the mailbox.

property session_flags: SessionFlags

Session-only flags for the mailbox.

set_deleted()[source]

Marks the selected mailbox as having been deleted.

Return type:

None

silence(seq_set, flag_set, flag_op)[source]

Runs the flags update against the cached flags, to prevent untagged FETCH responses unless other updates have occurred.

For example, if a session adds \Deleted and calls this method, the FETCH response will be silenced. But if another added \Seen at the same time, the FETCH response will be sent.

Parameters:

  • seq_set (SequenceSet) – The sequence set of messages.

  • flag_set (Set[Flag]) – The set of flags for the update operation.

  • flag_op (FlagOp) – The mode to change the flags.

Return type:

None

fork(command)[source]

Compares the state of the current object to that of the last fork, returning the untagged responses that reflect any changes. A new copy of the object is also returned, ready for the next command.

Parameters:

command (Command) – The command that was finished.

Return type:

tuple[SelectedMailbox, Iterable[UntaggedResponse]]