pymap.interfaces¶
pymap.interfaces.backend¶
- class pymap.interfaces.backend.BackendInterface(*args, **kwargs)[source]¶
Defines the abstract base class that is expected for backends that register themselves on the
pymap.backendentry point.- abstract classmethod add_subparser(name, subparsers)[source]¶
Add a command-line argument sub-parser that will be used to choose this backend. For example:
parser = subparsers.add_parser('foo', help='foo backend') parser.add_argument(...)
- Parameters:
name (str) – The name to use for the subparser.
subparsers (Any) – The special action object as returned by
add_subparsers().
- Returns:
The new sub-parser object.
- Return type:
- abstract async classmethod init(args, **overrides)[source]¶
Initialize the backend and return an instance.
- Parameters:
- Return type:
- abstract async start(stack)[source]¶
Start the backend.
- Parameters:
stack (AsyncExitStack) – An exit stack that should be used for cleanup.
- Return type:
None
- abstract property login: LoginInterface¶
Login interface that handles authentication credentials.
- abstract property config: IMAPConfig¶
The IMAP config in use by the backend.
- abstract property status: HealthStatus¶
The health status for the backend.
- class pymap.interfaces.backend.ServiceInterface(backend, config)[source]¶
Defines the abstract base class that is expected for services that register themselves on the
pymap.serviceentry point.- Parameters:
backend (BackendInterface)
config (IMAPConfig)
- abstract classmethod add_arguments(parser)[source]¶
Add the arguments or argument group used to configure the service. For example:
group = parser.add_argument_group('foo service arguments') group.add_argument(...)
- Parameters:
parser (ArgumentParser) – The argument parser.
- Return type:
None
- abstract async start(stack)[source]¶
Start the service.
- Parameters:
stack (AsyncExitStack) – An exit stack that should be used for cleanup.
- Return type:
None
pymap.interfaces.message¶
- class pymap.interfaces.message.MessageT¶
Type variable with an upper bound of
MessageInterface.alias of TypeVar(‘MessageT’, bound=
MessageInterface)
- class pymap.interfaces.message.MessageT_co¶
Covariant type variable with an upper bound of
MessageInterface.alias of TypeVar(‘MessageT_co’, bound=
MessageInterface, covariant=True)
- pymap.interfaces.message.FlagsKey¶
Type alias for the value used as a key in set comparisons detecting flag updates.
- class pymap.interfaces.message.CachedMessage(*args, **kwargs)[source]¶
Cached message metadata used to track state changes. Used to produce untagged FETCH responses when a message’s flags have changed, or when a FETCH command requests metadata of an expunged message before its untagged EXPUNGE response has been sent.
This is intended to be compatible with
MessageInterface, and should be implemented by the same classes in most cases.- abstract property flags_key: tuple[int, frozenset[Flag]]¶
Hashable value that represents the current flags of this message, used for detecting mailbox updates.
- abstract get_flags(session_flags)[source]¶
Get the full set of permanent and session flags for the message.
- Parameters:
session_flags (SessionFlags) – The current session flags.
- Return type:
- class pymap.interfaces.message.MessageInterface(*args, **kwargs)[source]¶
Message data such as UID, permanent flags, and when the message was added to the system.
- abstract property email_id: ObjectId¶
The message’s email object ID, which can identify its content.
See also
- abstract property thread_id: ObjectId¶
The message’s thread object ID, which groups messages together.
See also
- abstract get_flags(session_flags)[source]¶
Get the full set of permanent and session flags for the message.
- Parameters:
session_flags (SessionFlags) – The current session flags.
- Return type:
- abstract async load_content(requirement)[source]¶
Loads the content of the message.
- Parameters:
requirement (FetchRequirement) – The data required from the message content.
- Return type:
- class pymap.interfaces.message.LoadedMessageInterface(*args, **kwargs)[source]¶
The loaded message content, which may include the header, the body, both, or neither, depending on the requirements.
It is assumed that this object contains the entire content in-memory. As such, when multiple
MessageInterfaceobjects are being processed, only oneLoadedMessageInterfaceshould be in scope at a time.- abstract property requirement: FetchRequirement¶
The
FetchRequirementused to load the message content.
- abstract get_headers(section)[source]¶
Get the headers from the message part.
The
sectionargument indexes a nested sub-part of the message. For example,[2, 3]would get the 2nd sub-part of the message and then index it for its 3rd sub-part.
- abstract get_message_headers(section=None, subset=None, inverse=False)[source]¶
Get the headers from the message or a
message/rfc822sub-part of the message..The
sectionargument can index a nested sub-part of the message. For example,[2, 3]would get the 2nd sub-part of the message and then index it for its 3rd sub-part.
- abstract get_message_text(section=None)[source]¶
Get the text of the message part, not including headers.
The
sectionargument can index a nested sub-part of the message. For example,[2, 3]would get the 2nd sub-part of the message and then index it for its 3rd sub-part.
- abstract get_body(section=None, binary=False)[source]¶
Get the full body of the message part, including headers.
The
sectionargument can index a nested sub-part of the message. For example,[2, 3]would get the 2nd sub-part of the message and then index it for its 3rd sub-part.
- abstract get_envelope_structure()[source]¶
Build and return the envelope structure.
See also
- Return type:
pymap.interfaces.mailbox¶
- class pymap.interfaces.mailbox.MailboxInterface(*args, **kwargs)[source]¶
Describes a mailbox as it exists in an IMAP backend, whether or not it is currently selected.
- abstract property mailbox_id: ObjectId¶
The mailbox object ID.
This value must have no relationship to the mailbox name, e.g. a renamed mailbox should have the same ID but a deleted/re-created mailbox of the same name must have a different ID.
See also
pymap.interfaces.session¶
- class pymap.interfaces.session.SessionInterface(*args, **kwargs)[source]¶
Corresponds to a single, authenticated IMAP session.
- abstract property filter_set: FilterSetInterface[Any] | None¶
Manages the active and inactive filters for the login user.
- abstract close()[source]¶
Called at the end of a session, to clean up any resources.
- Return type:
None
- abstract 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
- abstract async list_mailboxes(ref_name, filter_, subscribed=False, selected=None)[source]¶
List the mailboxes owned by the user.
See also
- 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]
- abstract async get_mailbox(name, selected=None)[source]¶
Retrieves a
MailboxInterfaceobject 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:
- Return type:
tuple[MailboxInterface, SelectedMailbox | None]
- abstract async create_mailbox(name, selected=None)[source]¶
Creates a new mailbox owned by the user.
See also
- Parameters:
name (str) – The name of the mailbox.
selected (SelectedMailbox | None) – If applicable, the currently selected mailbox name.
- Raises:
- Return type:
tuple[ObjectId, SelectedMailbox | None]
- abstract async delete_mailbox(name, selected=None)[source]¶
Deletes the mailbox owned by the user.
See also
- Parameters:
name (str) – The name of the mailbox.
selected (SelectedMailbox | None) – If applicable, the currently selected mailbox name.
- Raises:
- Return type:
SelectedMailbox | None
- abstract async rename_mailbox(before_name, after_name, selected=None)[source]¶
Renames the mailbox owned by the user.
See also
- 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:
- Return type:
SelectedMailbox | None
- abstract async subscribe(name, selected=None)[source]¶
Mark the given folder name as subscribed, whether or not the given folder name currently exists.
See also
- Parameters:
name (str) – The name of the mailbox.
selected (SelectedMailbox | None) – If applicable, the currently selected mailbox name.
- Raises:
- Return type:
SelectedMailbox | None
- abstract 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
- Parameters:
name (str) – The name of the mailbox.
selected (SelectedMailbox | None) – If applicable, the currently selected mailbox name.
- Raises:
- Return type:
SelectedMailbox | None
- abstract async append_messages(name, messages, selected=None)[source]¶
Appends a message to the end of the mailbox.
See also
- 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:
- Return type:
tuple[AppendUid, SelectedMailbox | None]
- abstract async select_mailbox(name, readonly=False)[source]¶
Selects an existing mailbox owned by the user. The returned session is then used as the
selectedargument to other methods to fetch mailbox updates.See also
- Parameters:
- Raises:
- Return type:
- abstract async check_mailbox(selected, *, wait_on=None, housekeeping=False)[source]¶
Checks for any updates in the mailbox.
If
wait_onis 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 aswait_onis not signalled.If
housekeepingis True, perform any house-keeping necessary by the mailbox backend, which may be a slower operation.See also
- 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:
- Return type:
- abstract 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
\Seenflag.
- Raises:
- Return type:
tuple[Iterable[tuple[int, MessageInterface]], SelectedMailbox]
- abstract async search_mailbox(selected, keys)[source]¶
Get the messages in the current mailbox that meet all of the given search criteria.
See also
- Parameters:
selected (SelectedMailbox) – The selected mailbox session.
keys (frozenset[SearchKey]) – Search keys specifying the message criteria.
- Raises:
- Return type:
tuple[Iterable[tuple[int, MessageInterface]], SelectedMailbox]
- abstract async expunge_mailbox(selected, uid_set=None)[source]¶
All messages that are marked as deleted are immediately expunged from the mailbox.
See also
- Parameters:
selected (SelectedMailbox) – The selected mailbox session.
uid_set (SequenceSet | None) – Only the messages in the given UID set should be expunged.
- Raises:
- Return type:
- abstract async copy_messages(selected, sequence_set, mailbox)[source]¶
Copy a set of messages into the given mailbox.
See also
- Parameters:
selected (SelectedMailbox) – The selected mailbox session.
sequence_set (SequenceSet) – Sequence set of message sequences or UIDs.
mailbox (str) – Name of the mailbox to copy messages into.
- Raises:
- Return type:
tuple[CopyUid | None, SelectedMailbox]
- abstract async move_messages(selected, sequence_set, mailbox)[source]¶
Move a set of messages into the given mailbox, removing them from the selected mailbox.
See also
- Parameters:
selected (SelectedMailbox) – The selected mailbox session.
sequence_set (SequenceSet) – Sequence set of message sequences or UIDs.
mailbox (str) – Name of the mailbox to copy messages into.
- Raises:
- Return type:
tuple[CopyUid | None, SelectedMailbox]
- abstract async update_flags(selected, sequence_set, flag_set, mode=FlagOp.REPLACE)[source]¶
Update the flags for the given set of messages.
See also
- Parameters:
selected (SelectedMailbox) – The selected mailbox session.
sequence_set (SequenceSet) – Sequence set of message sequences or UIDs.
mode (FlagOp) – Update mode for the flag set.
- Raises:
- Return type:
tuple[Iterable[tuple[int, MessageInterface]], SelectedMailbox]
pymap.interfaces.login¶
- class pymap.interfaces.login.LoginInterface(*args, **kwargs)[source]¶
Defines the authentication operations for backends.
- abstract property tokens: TokensInterface¶
Handles creation and authentication of bearer tokens.
- abstract async authenticate(credentials)[source]¶
Authenticate the credentials.
- Parameters:
credentials (ServerCredentials) – Authentication credentials supplied by the user.
- Raises:
- Return type:
- abstract async authorize(authenticated, authzid)[source]¶
The authenticated identity must be authorized to assume the identity of authzid, returning its user identity if successful.
- Parameters:
authenticated (IdentityInterface) – The identity that successfully authorized.
authzid (str) – The identity name to be authorized.
- Raises:
- Return type:
- class pymap.interfaces.login.IdentityInterface(*args, **kwargs)[source]¶
Defines the operations available to a user identity. This user identity may or may not “exist” yet in the backend.
- abstract async new_token(*, expiration=None)[source]¶
Returns a bearer token that may be used in future authentication attempts.
Since tokens should use their own private key, backends may return
Noneif it does not support tokens or the user does not have a private key.
- abstract async get()[source]¶
Return the metadata associated with the user identity.
- Raises:
- Return type:
- abstract async set(metadata)[source]¶
Assign new metadata to the user identity.
- Parameters:
metadata (UserMetadata) – New metadata, such as password.
- Returns:
The
entity_tagof the updated metadata, if applicable.- Raises:
- Return type:
int | None
pymap.interfaces.filter¶
- class pymap.interfaces.filter.FilterValueT¶
Type variable for the filter value representation.
alias of TypeVar(‘FilterValueT’)
- class pymap.interfaces.filter.FilterInterface(*args, **kwargs)[source]¶
Protocol defining the interface for message filters. Filters may choose the mailbox or discard the message or modify its contents or metadata. The filter may also trigger external functionality, such as sending a vacation auto-response or a copy of the message to an SMTP endpoint.
- abstract async apply(sender, recipient, mailbox, append_msg)[source]¶
Run the filter and return the mailbox where it should be appended, or None to discard, and the message to be appended, which is usually the same as
append_msg.- Parameters:
sender (str) – The envelope sender of the message.
recipient (str) – The envelope recipient of the message.
mailbox (str) – The intended mailbox to append the message.
append_msg (AppendMessage) – The message to be appended.
- Raises:
- Return type:
tuple[str | None, AppendMessage]
- class pymap.interfaces.filter.FilterCompilerInterface(*args, **kwargs)[source]¶
Protocol for classes which can compile a filter value into an implementation.
- abstract property value_type: type[FilterValueT]¶
The filter value type.
- abstract property filter_type: type[FilterInterface]¶
The filter implementation type.
- abstract async compile(value)[source]¶
Compile the filter value and return the resulting implementation.
- Parameters:
value (FilterValueT) – The filter value:
- Return type:
- class pymap.interfaces.filter.FilterSetInterface(*args, **kwargs)[source]¶
Protocol defining the interface for accessing and managing the set of message filters currently active and available. This interface intentionally resembles that of a ManageSieve server.
See also
- abstract property compiler: FilterCompilerInterface[FilterValueT]¶
Compiles filter values into an implementation.
- abstract async put(name, value)[source]¶
Add or update the named filter value.
- Parameters:
name (str) – The filter name.
value (FilterValueT) – The filter value.
- Return type:
None
- abstract async delete(name)[source]¶
Delete the named filter. If the named filter is active,
ValueErroris raised.
- abstract async rename(before_name, after_name)[source]¶
Rename the filter, maintaining its active status. An exception is raised if
before_namedoes not exist orafter_namealready exists.
- abstract async get(name)[source]¶
Return the named filter value.
- abstract async get_active()[source]¶
Return the active filter value, if any.
- Return type:
FilterValueT | None