pymap.backend.maildir

class pymap.backend.maildir.MaildirBackend(login, config)

Defines an on-disk backend that uses Maildir for mailbox storage and MailboxFormat/Maildir for metadata storage.

Parameters:

• login (Login)

• config (Config)

property login: Login

Login interface that handles authentication credentials.

property config: Config

The IMAP config in use by the backend.

property status: HealthStatus

The health status for the backend.

classmethod add_subparser(name, subparsers)

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:

ArgumentParser

async classmethod init(args, **overrides)

Initialize the backend and return an instance.

Parameters:

• args (Namespace) – The command-line arguments.

• overrides (Any) – Override keyword arguments to the config constructor.

Return type:

tuple[MaildirBackend, Config]

async start(stack)

Start the backend.

Parameters:

stack (AsyncExitStack) – An exit stack that should be used for cleanup.

Return type:

None

class pymap.backend.maildir.Config(args, *, base_dir, layout, colon, **extra)

The config implementation for the maildir backend.

Parameters:

• args (Namespace) – The command-line arguments.

• base_dir (str) – The base directory for all relative mailbox paths.

• layout (str) – The Maildir directory layout.

• colon (str | None) – The info delimiter in mail filename.

• hash_interface – The hash algorithm to use for passwords.

• extra (Any)

property backend_capability: BackendCapability

Allows backends to declare support for IMAP extensions and other capabilities.

property base_dir: str

The base directory for all relative paths.

property layout: str

The Maildir directory layout name.

See also

MaildirLayout

property colon: str | None

The info delimiter in mail filename.

See also

Note on colon in mailbox.Maildir.

classmethod parse_args(args)

Given command-line arguments, return a dictionary of keywords that should be passed in to the IMAPConfig (or sub-class) constructor. Sub-classes should override this method as needed.

Parameters:

args (Namespace) – The arguments parsed from the command-line.

Return type:

Mapping[str, Any]

pymap.backend.maildir.flags

class pymap.backend.maildir.flags.MaildirFlags(path)

Maintains a set of IMAP keywords (non-standard flags) that are available for use on messages. This uses a custom file format to define keywords, which might look like this:

0 $Junk
1 $NonJunk

The lower-case letter codes that correspond to each keyword start with 'a' for 0, 'b' for 1, etc. and up to 26 are supported.

Parameters:

• keywords – The list of keywords available for use on messages.

• path (str)

See also

IMAP Keywords

property permanent_flags: frozenset[Flag]

Return the set of all permanent flags, system and keyword.

property system_flags: frozenset[Flag]

Return the set of defined IMAP system flags.

property keywords: frozenset[Flag]

Return the set of available IMAP keywords.

to_maildir(flags)

Return the string of letter codes that are used to map to defined IMAP flags and keywords.

Parameters:

flags (Iterable[bytes | Flag]) – The flags and keywords to map.

Return type:

str

from_maildir(codes)

Return the set of IMAP flags that correspond to the letter codes.

Parameters:

codes (str) – The letter codes to map.

Return type:

frozenset[Flag]

pymap.backend.maildir.layout

class pymap.backend.maildir.layout.MaildirLayout(*args, **kwargs)

Manages the folder layout of a Maildir inbox.

See also

Directory Structure

classmethod get(path, layout, maildir_type)

Parameters:

• path (str) – The root path of the inbox.

• layout (str) – The layout name, e.g. '++' or 'fs'.

• maildir_type (type[_MaildirT]) – The Maildir sub-class.

Raises:

ValueError – The layout name was not recognized.

Return type:

MaildirLayout[_MaildirT]

abstract property path: str

The root path of the inbox.

abstract get_path(name, delimiter)

Return the path of the sub-folder.

Parameters:

• name (str) – The nested parts of the folder name, not including inbox.

• delimiter (str) – The nested sub-folder delimiter string.

Return type:

str

abstract list_folders(delimiter, top='INBOX')

Return all folders, starting with top and traversing through the sub-folder heirarchy.

Parameters:

• delimiter (str) – The nested sub-folder delimiter string.

• top (str) – The top of the folder heirarchy to list.

Raises:

FileNotFoundError – The folder did not exist.

Return type:

Sequence[str]

abstract get_folder(name, delimiter)

Return the existing sub-folder.

Parameters:

• name (str) – The delimited sub-folder name, not including inbox.

• delimiter (str) – The nested sub-folder delimiter string.

Raises:

FileNotFoundError – The folder did not exist.

Return type:

_MaildirT

abstract add_folder(name, delimiter)

Add a new sub-folder.

Parameters:

• name (str) – The delimited sub-folder name, not including inbox.

• delimiter (str) – The nested sub-folder delimiter string.

Raises:

• FileExistsError – The folder already exists.

• FileNotFoundError – A parent folder did not exist.

Return type:

None

abstract remove_folder(name, delimiter)

Remove the existing sub-folder.

Parameters:

• name (str) – The delimited sub-folder name, not including inbox.

• delimiter (str) – The nested sub-folder delimiter string.

Raises:

• FileNotFoundError – The folder did not exist.

• OSError – With ENOTEMPTY, the folder has sub-folders.

Return type:

None

abstract rename_folder(source_name, dest_name, delimiter)

Rename the existing sub-folder to the destination.

Parameters:

• source_name (str) – The delimited source sub-folder name.

• dest_name (str) – The delimited destination sub-folder name.

• delimiter (str) – The nested sub-folder delimiter string.

Raises:

• FileNotFoundError – The source folder did not exist.

• FileExistsError – The destination folder already exists.

Return type:

None

class pymap.backend.maildir.layout.DefaultLayout(path, maildir_type)

The default Maildir++ layout, which uses sub-folder names starting with and using . as a delimiter for nesting , e.g.:

.Trash/
.Important.To-Do/
.Important.Misc/

Parameters:

• path (str) – The root path of the inbox.

• maildir_type (type[_MaildirT]) – The Maildir class override.

class pymap.backend.maildir.layout.FilesystemLayout(path, maildir_type)

The fs layout, which uses nested sub-directories on the filesystem, e.g.:

Trash/
Important/To-Do/
Important/Misc/

Parameters:

• path (str) – The root path of the inbox.

• maildir_type (type[_MaildirT]) – The Maildir class override.

pymap.backend.maildir.subscriptions

class pymap.backend.maildir.subscriptions.Subscriptions(path)

Maintains the set of folders currently subscribed to.

Parameters:

path (str) – The directory of the file.

property subscribed: Sequence[str]

The folders currently subscribed to.

add(folder)

Add a new folder to the subscriptions.

Parameters:

folder (str)

Return type:

None

remove(folder)

Remove a folder from the subscriptions.

Parameters:

folder (str)

Return type:

None

set(folder, subscribed)

Set the subscribed status of a folder.

Parameters:

• folder (str)

• subscribed (bool)

Return type:

None

pymap.backend.maildir.uidlist

class pymap.backend.maildir.uidlist.Record(uid, fields, filename)

Defines a single record read from the UID list file.

Parameters:

• uid (int) – The message UID of the record.

• fields (Mapping[str, str]) – The metadata fields of the record.

• filename (str) – The filename of the record.

property key: str

The Maildir key value.

class pymap.backend.maildir.uidlist.UidList(path, uid_validity, next_uid, global_uid=None)

Maintains the file with UID mapping to maildir files.

Parameters:

• path (str) – The directory of the file.

• uid_validity (int) – The UID validity value.

• next_uid (int) – The next assignable message UID value.

• global_uid (bytes | None) – The 128-bit global mailbox UID.

FILE_NAME: ClassVar[str] = 'dovecot-uidlist'

The UID list file name, stored in the mailbox directory.

LOCK_FILE: ClassVar[str] = 'dovecot-uidlist.lock'

The UID list lock file, stored adjacent to the UID list file.

property records: Iterable[Record]

The records contained in the UID list file.

get(uid)

Get a single record by its UID.

Parameters:

uid (int) – The message UID.

Raises:

KeyError – The UID does not exist.

Return type:

Record

get_all(uids)

Get records by a set of UIDs.

Parameters:

uids (Iterable[int]) – The message UIDs.

Return type:

Mapping[int, Record]

set(rec)

Add or update the record in the UID list file.

Parameters:

rec (Record)

Return type:

None

remove(uid)

Remove the record from the UID list file.

Raises:

KeyError – The UID does not exist.

Parameters:

uid (int)

Return type:

None

pymap.backend.maildir.mailbox

class pymap.backend.maildir.mailbox.Maildir(dirname, factory=None, create=True)

claim_new()

Checks for messages in the new subdirectory, moving them to cur and returning their keys.

Return type:

Iterable[str]

move_message(key, dest, dest_subdir)

Moves the message to another maildir.

Parameters:

• key (str)

• dest (Maildir)

• dest_subdir (str)

Return type:

str

get_message_metadata(key)

Like get_message() but the message contents are not read from disk.

Parameters:

key (str)

Return type:

MaildirMessage

update_metadata(key, msg)

Uses os.rename() to atomically update the message filename based on get_info().

Parameters:

• key (str)

• msg (MaildirMessage)

Return type:

None

class pymap.backend.maildir.mailbox.Message(uid, internal_date, permanent_flags, *, expunged=False, email_id=None, thread_id=None, recent=False, maildir=None, key=None)

Parameters:

• uid (int)

• internal_date (datetime)

• permanent_flags (Iterable[Flag])

• expunged (bool)

• email_id (ObjectId | None)

• thread_id (ObjectId | None)

• recent (bool)

• maildir (Maildir | None)

• key (str | None)

async load_content(requirement)

Loads the content of the message.

Parameters:

requirement (FetchRequirement) – The data required from the message content.

Return type:

LoadedMessage

class pymap.backend.maildir.mailbox.MailboxData(mailbox_id, maildir, path)

Parameters:

• mailbox_id (ObjectId)

• maildir (Maildir)

• path (str)

property mailbox_id: ObjectId

The mailbox object ID.

See also

mailbox_id

property readonly: bool

Whether the mailbox is read-only or read-write.

property uid_validity: int

The mailbox UID validity value.

property permanent_flags: frozenset[Flag]

The permanent flags allowed in the mailbox.

property selected_set: SelectedSet

The set of selected mailbox sessions currently active.

async update_selected(selected, *, wait_on=None)

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

async append(append_msg, *, recent=False)

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:

Message

async copy(uid, destination, *, recent=False)

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

Parameters:

• uid (int) – The UID of the message to copy.

• destination (MailboxData) – The destination mailbox.

• recent (bool) – True if the message should be marked recent.

Return type:

int | None

async move(uid, destination, *, recent=False)

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

Parameters:

• uid (int) – The UID of the message to move.

• destination (MailboxData) – The destination mailbox.

• recent (bool) – True if the message should be marked recent.

Return type:

int | None

async get(uid, cached_msg)

Return the message with the given UID.

Parameters:

• uid (int) – The message UID.

• cached_msg (CachedMessage) – The last known cached message.

Return type:

Message

async update(uid, cached_msg, flag_set, mode)

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:

Message

async delete(uids)

Delete messages with the given UIDs.

Parameters:

uids (Iterable[int]) – The message UIDs.

Return type:

None

async claim_recent(selected)

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

async cleanup()

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

async snapshot()

Returns a snapshot of the current state of the mailbox.

Return type:

MailboxSnapshot

class pymap.backend.maildir.mailbox.MailboxSet(maildir, layout)

Parameters:

• maildir (Maildir)

• layout (MaildirLayout[Any])

property delimiter: str

The delimiter used in mailbox names to indicate hierarchy.

async set_subscribed(name, subscribed)

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

async list_subscribed()

Return a list of all subscribed mailboxes.

See also

list_mailboxes()

Return type:

ListTree

async list_mailboxes()

Return a list of all mailboxes.

See also

list_mailboxes()

Return type:

ListTree

async get_mailbox(name)

Return an existing mailbox by name.

Parameters:

name (str) – The name of the mailbox.

Raises:

KeyError – The mailbox did not exist.

Return type:

MailboxData

async add_mailbox(name)

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

async delete_mailbox(name)

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

async rename_mailbox(before, after)

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.maildir.users

class pymap.backend.maildir.users.UserRecord(name, password='', uid='', gid='', comment='', home_dir='', shell='')

Encapsulates a single user line in the passwd file.

See also

passwd(5)

Parameters:

• name (str)

• password (str)

• uid (str)

• gid (str)

• comment (str)

• home_dir (str)

• shell (str)

class pymap.backend.maildir.users.PasswordRecord(name, password, last_change_date='', min_password_age='', max_password_age='', password_warning_period='', password_inactivity_period='', account_expiration_date='', reserved='')

Encapsulates a single user line in the shadow file.

See also

shadow(5)

Parameters:

• name (str)

• password (str)

• last_change_date (str)

• min_password_age (str)

• max_password_age (str)

• password_warning_period (str)

• password_inactivity_period (str)

• account_expiration_date (str)

• reserved (str)

class pymap.backend.maildir.users.GroupRecord(name, password='', gid='', users_list='')

Encapsulates a single group line in the group file.

See also

group(5)

Parameters:

• name (str)

• password (str)

• gid (str)

• users_list (str)

class pymap.backend.maildir.users.UsersFile(path)

Reads and writes a file using the passwd file format. The home directory field in the user record will be the path (absolute or relative to the base directory) to the user’s maildir.

Parameters:

path (str)

FILE_NAME: ClassVar[str] = 'pymap-etc-passwd'

The users file name.

class pymap.backend.maildir.users.PasswordsFile(path)

Reads and writes a file using the passwd file format. Similar to the /etc/shadow file on a Linux system, this file contains the password representation and may have stricter file permissions.

Parameters:

path (str)

FILE_NAME: ClassVar[str] = 'pymap-etc-shadow'

The passwords file name.

class pymap.backend.maildir.users.GroupsFile(path)

Reads and writes a file using the group file format. The name field in each record is the role name, and the users list are the users that have been assigned that role.

Parameters:

path (str)

FILE_NAME: ClassVar[str] = 'pymap-etc-group'

The roles file name.

class pymap.backend.maildir.users.TokensFile(path)

Reads and writes a file using the group file format. The name field in each record is the token identifier, the password field is the private key, and the users list contains the user or users it is valid for.

Parameters:

path (str)

FILE_NAME: ClassVar[str] = 'pymap-tokens'

The roles file name.