mailbox — Керуйте поштовими скриньками в різних форматах

Вихідний код: Lib/mailbox.py

---

This module defines two classes, Mailbox and Message, for accessing and manipulating on-disk mailboxes and the messages they contain. Mailbox offers a dictionary-like mapping from keys to messages. Message extends the email.message module’s Message class with format-specific state and behavior. Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.

Дивись також

Модуль email

Представляти та маніпулювати повідомленнями.

Mailbox objects

class mailbox.Mailbox

Поштова скринька, яку можна перевірити та змінити.

The Mailbox class defines an interface and is not intended to be instantiated. Instead, format-specific subclasses should inherit from Mailbox and your code should instantiate a particular subclass.

The Mailbox interface is dictionary-like, with small keys corresponding to messages. Keys are issued by the Mailbox instance with which they will be used and are only meaningful to that Mailbox instance. A key continues to identify a message even if the corresponding message is modified, such as by replacing it with another message.

Messages may be added to a Mailbox instance using the set-like method add() and removed using a del statement or the set-like methods remove() and discard().

Mailbox interface semantics differ from dictionary semantics in some noteworthy ways. Each time a message is requested, a new representation (typically a Message instance) is generated based upon the current state of the mailbox. Similarly, when a message is added to a Mailbox instance, the provided message representation’s contents are copied. In neither case is a reference to the message representation kept by the Mailbox instance.

The default Mailbox iterator iterates over message representations, not keys as the default dictionary iterator does. Moreover, modification of a mailbox during iteration is safe and well-defined. Messages added to the mailbox after an iterator is created will not be seen by the iterator. Messages removed from the mailbox before the iterator yields them will be silently skipped, though using a key from an iterator may result in a KeyError exception if the corresponding message is subsequently removed.

Попередження

Be very cautious when modifying mailboxes that might be simultaneously changed by some other process. The safest mailbox format to use for such tasks is Maildir; try to avoid using single-file formats such as mbox for concurrent writing. If you’re modifying a mailbox, you must lock it by calling the lock() and unlock() methods before reading any messages in the file or making any changes by adding or deleting a message. Failing to lock the mailbox runs the risk of losing messages or corrupting the entire mailbox.

Mailbox instances have the following methods:

add(message)

Додайте повідомлення до поштової скриньки та поверніть призначений їй ключ.

Параметр message може бути екземпляром Message, екземпляром email.message.Message, рядком, рядком байтів або файлоподібним об’єктом (який має бути відкритий у двійковому режимі) . Якщо message є екземпляром відповідного підкласу Message (наприклад, якщо це екземпляр mboxMessage, а це екземпляр mbox), його специфічний для формату використовується інформація. В іншому випадку використовуються розумні значення за замовчуванням для інформації про певний формат.

Змінено в версії 3.2: Додано підтримку двійкового введення.

remove(key)

__delitem__(key)

discard(key)

Видалити з поштової скриньки повідомлення, що відповідає ключу.

Якщо такого повідомлення немає, виникає виняток KeyError, якщо метод викликано як remove() або __delitem__(), але жодного винятку не виникає, якщо метод викликано як discard(). Поведінка discard() може бути кращою, якщо базовий формат поштової скриньки підтримує одночасну модифікацію іншими процесами.

__setitem__(key, message)

Замініть повідомлення, що відповідає ключу на повідомлення. Викликати виняток KeyError, якщо жодне повідомлення вже не відповідає ключу.

Як і add(), параметр message може бути екземпляром Message, екземпляром email.message.Message, рядком, рядком байтів або файлоподібним об’єктом (який має бути відкритий у двійковому режимі). Якщо message є екземпляром відповідного підкласу Message (наприклад, якщо це екземпляр mboxMessage, а це екземпляр mbox), його специфічний для формату використовується інформація. В іншому випадку інформація про формат повідомлення, яке наразі відповідає ключу, залишається без змін.

iterkeys()

Return an iterator over all keys

keys()

The same as iterkeys(), except that a list is returned rather than an iterator

itervalues()

__iter__()

Return an iterator over representations of all messages. The messages are represented as instances of the appropriate format-specific Message subclass unless a custom message factory was specified when the Mailbox instance was initialized.

Примітка

Поведінка __iter__() відрізняється від поведінки словників, які перебирають ключі.

values()

The same as itervalues(), except that a list is returned rather than an iterator

iteritems()

Return an iterator over (key, message) pairs, where key is a key and message is a message representation. The messages are represented as instances of the appropriate format-specific Message subclass unless a custom message factory was specified when the Mailbox instance was initialized.

items()

The same as iteritems(), except that a list of pairs is returned rather than an iterator of pairs.

get(key, default=None)

__getitem__(key)

Return a representation of the message corresponding to key. If no such message exists, default is returned if the method was called as get() and a KeyError exception is raised if the method was called as __getitem__(). The message is represented as an instance of the appropriate format-specific Message subclass unless a custom message factory was specified when the Mailbox instance was initialized.

get_message(key)

Повернути представлення повідомлення, що відповідає key, як екземпляр відповідного підкласу Message або створити виняток KeyError, якщо таке повідомлення не існує.

get_bytes(key)

Повертає байтове представлення повідомлення, що відповідає key, або викликає виняток KeyError, якщо такого повідомлення не існує.

Added in version 3.2.

get_string(key)

Повернути рядкове представлення повідомлення, що відповідає key, або викликати виняток KeyError, якщо такого повідомлення не існує. Повідомлення обробляється через email.message.Message, щоб перетворити його на 7-бітне чисте представлення.

get_file(key)

Return a file-like representation of the message corresponding to key, or raise a KeyError exception if no such message exists. The file-like object behaves as if open in binary mode. This file should be closed once it is no longer needed.

Змінено в версії 3.2: The file object really is a binary file; previously it was incorrectly returned in text mode. Also, the file-like object now supports the context manager protocol: you can use a with statement to automatically close it.

Примітка

Unlike other representations of messages, file-like representations are not necessarily independent of the Mailbox instance that created them or of the underlying mailbox. More specific documentation is provided by each subclass.

__contains__(key)

Повертає True, якщо ключ відповідає повідомленню, False інакше.

__len__()

Повернути кількість повідомлень у поштовій скриньці.

clear()

Видалити всі повідомлення з поштової скриньки.

pop(key, default=None)

Return a representation of the message corresponding to key and delete the message. If no such message exists, return default. The message is represented as an instance of the appropriate format-specific Message subclass unless a custom message factory was specified when the Mailbox instance was initialized.

popitem()

Return an arbitrary (key, message) pair, where key is a key and message is a message representation, and delete the corresponding message. If the mailbox is empty, raise a KeyError exception. The message is represented as an instance of the appropriate format-specific Message subclass unless a custom message factory was specified when the Mailbox instance was initialized.

update(arg)

Parameter arg should be a key-to-message mapping or an iterable of (key, message) pairs. Updates the mailbox so that, for each given key and message, the message corresponding to key is set to message as if by using __setitem__(). As with __setitem__(), each key must already correspond to a message in the mailbox or else a KeyError exception will be raised, so in general it is incorrect for arg to be a Mailbox instance.

Примітка

На відміну від словників, аргументи ключових слів не підтримуються.

flush()

Write any pending changes to the filesystem. For some Mailbox subclasses, changes are always written immediately and flush() does nothing, but you should still make a habit of calling this method.

lock()

Отримайте ексклюзивне консультаційне блокування поштової скриньки, щоб інші процеси знали, що не потрібно її змінювати. Якщо блокування недоступне, виникає ExternalClashError. Використовувані конкретні механізми блокування залежать від формату поштової скриньки. Ви повинні завжди блокувати поштову скриньку, перш ніж вносити будь-які зміни в її вміст.

unlock()

Зніміть блокування поштової скриньки, якщо є.

close()

Flush the mailbox, unlock it if necessary, and close any open files. For some Mailbox subclasses, this method does nothing.

Maildir objects

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

Підклас Mailbox для поштових скриньок у форматі Maildir. Параметр factory — це викликаючий об’єкт, який приймає файлоподібне представлення повідомлення (яке поводиться так, ніби відкрито в двійковому режимі) і повертає спеціальне представлення. Якщо factory має значення None, MaildirMessage використовується як типове представлення повідомлення. Якщо create має значення True, поштова скринька буде створена, якщо вона не існує.

Якщо create має значення True і шлях dirname існує, він розглядатиметься як існуючий maildir без спроби перевірити розташування його каталогу.

З історичних причин dirname названо так, а не path.

Maildir — це формат поштової скриньки на основі каталогу, винайдений для агента передачі пошти qmail і тепер широко підтримується іншими програмами. Повідомлення в поштовій скриньці Maildir зберігаються в окремих файлах у загальній структурі каталогу. Ця конструкція дозволяє отримувати доступ до поштових скриньок Maildir і змінювати їх кількома непов’язаними програмами без пошкодження даних, тому блокування файлів непотрібне.

Поштові скриньки Maildir містять три підкаталоги, а саме: tmp, new і cur. Повідомлення миттєво створюються в підкаталозі tmp, а потім переміщуються в підкаталог new для завершення доставки. Поштовий агент користувача може згодом перемістити повідомлення до підкаталогу cur і зберегти інформацію про стан повідомлення в спеціальному розділі «info», доданому до імені файлу.

Folders of the style introduced by the Courier mail transfer agent are also supported. Any subdirectory of the main mailbox is considered a folder if '.' is the first character in its name. Folder names are represented by Maildir without the leading '.'. Each folder is itself a Maildir mailbox but should not contain other folders. Instead, a logical nesting is indicated using '.' to delimit levels, e.g., «Archived.2005.07».

colon

Специфікація Maildir вимагає використання двокрапки (':') у певних іменах файлів повідомлень. Однак деякі операційні системи не дозволяють використовувати цей символ у назвах файлів. Якщо ви бажаєте використовувати формат, подібний до Maildir, у такій операційній системі, вам слід указати інший символ для використання замість нього. Знак оклику ('!') є популярним вибором. Наприклад:

import mailbox
mailbox.Maildir.colon = '!'

The colon attribute may also be set on a per-instance basis.

Maildir instances have all of the methods of Mailbox in addition to the following:

list_folders()

Повернути список імен усіх папок.

get_folder(folder)

Return a Maildir instance representing the folder whose name is folder. A NoSuchMailboxError exception is raised if the folder does not exist.

add_folder(folder)

Create a folder whose name is folder and return a Maildir instance representing it.

remove_folder(folder)

Видаліть папку з назвою папка. Якщо папка містить будь-які повідомлення, буде викликано виняток NotEmptyError і папку не буде видалено.

clean()

Видаліть із поштової скриньки тимчасові файли, до яких не було доступу протягом останніх 36 годин. Специфікація Maildir говорить, що програми для читання пошти повинні робити це час від часу.

Some Mailbox methods implemented by Maildir deserve special remarks:

add(message)

__setitem__(key, message)

update(arg)

Попередження

Ці методи генерують унікальні імена файлів на основі ідентифікатора поточного процесу. Під час використання кількох потоків можуть виникнути невиявлені конфлікти імен і спричинити пошкодження поштової скриньки, якщо потоки не координуються, щоб уникнути використання цих методів для одночасного маніпулювання тією самою поштовою скринькою.

flush()

Усі зміни в поштових скриньках Maildir застосовуються негайно, тому цей метод нічого не робить.

lock()

unlock()

Поштові скриньки Maildir не підтримують (або вимагають) блокування, тому ці методи нічого не роблять.

close()

Maildir instances do not keep any open files and the underlying mailboxes do not support locking, so this method does nothing.

get_file(key)

Залежно від хост-платформи може бути неможливо змінити або видалити базове повідомлення, поки повернутий файл залишається відкритим.

Дивись також

maildir man page from Courier

Специфікація формату. Описує загальне розширення для підтримки папок.

Використання формату maildir

Нотатки про Maildir від його винахідника. Включає оновлену схему створення імен і подробиці семантики «info».

mbox objects

class mailbox.mbox(path, factory=None, create=True)

Підклас Mailbox для поштових скриньок у форматі mbox. Параметр factory — це викликаючий об’єкт, який приймає файлоподібне представлення повідомлення (яке поводиться так, ніби відкрито в двійковому режимі) і повертає спеціальне представлення. Якщо factory має значення None, mboxMessage використовується як типове представлення повідомлення. Якщо create має значення True, поштова скринька буде створена, якщо вона не існує.

Формат mbox є класичним форматом для зберігання пошти в системах Unix. Усі повідомлення в поштовій скриньці mbox зберігаються в одному файлі, початок кожного повідомлення позначається рядком, перші п’ять символів якого є «Від».

Several variations of the mbox format exist to address perceived shortcomings in the original. In the interest of compatibility, mbox implements the original format, which is sometimes referred to as mboxo. This means that the Content-Length header, if present, is ignored and that any occurrences of «From « at the beginning of a line in a message body are transformed to «>From « when storing the message, although occurrences of «>From « are not transformed to «From « when reading the message.

Some Mailbox methods implemented by mbox deserve special remarks:

get_file(key)

Using the file after calling flush() or close() on the mbox instance may yield unpredictable results or raise an exception.

lock()

unlock()

Three locking mechanisms are used—dot locking and, if available, the flock() and lockf() system calls.

Дивись також

сторінка довідки mbox з tin

Специфікація формату з деталями щодо блокування.

Налаштування Netscape Mail в Unix: Чому формат довжини вмісту поганий

Аргумент для використання оригінального формату mbox, а не варіації.

«mbox» - це сімейство з кількох взаємно несумісних форматів поштових скриньок

Історія різновидів mbox.

MH objects

class mailbox.MH(path, factory=None, create=True)

Підклас Mailbox для поштових скриньок у форматі MH. Параметр factory — це викликаючий об’єкт, який приймає файлоподібне представлення повідомлення (яке поводиться так, ніби відкрито в двійковому режимі) і повертає спеціальне представлення. Якщо factory має значення None, MHMessage використовується як типове представлення повідомлення. Якщо create має значення True, поштова скринька буде створена, якщо вона не існує.

MH — це формат поштової скриньки на основі каталогу, створений для системи обробки повідомлень MH, агента користувача електронної пошти. Кожне повідомлення в поштовій скриньці MH зберігається в окремому файлі. Крім повідомлень, поштова скринька MH може містити інші поштові скриньки MH (так звані folders). Папки можуть бути вкладеними нескінченно довго. Поштові скриньки MH також підтримують sequences, які є іменованими списками, які використовуються для логічного групування повідомлень без їх переміщення до підпапок. Послідовності визначено у файлі під назвою .mh_sequences у кожній папці.

The MH class manipulates MH mailboxes, but it does not attempt to emulate all of mh’s behaviors. In particular, it does not modify and is not affected by the context or .mh_profile files that are used by mh to store its state and configuration.

MH instances have all of the methods of Mailbox in addition to the following:

list_folders()

Повернути список імен усіх папок.

get_folder(folder)

Return an MH instance representing the folder whose name is folder. A NoSuchMailboxError exception is raised if the folder does not exist.

add_folder(folder)

Create a folder whose name is folder and return an MH instance representing it.

remove_folder(folder)

Видаліть папку з назвою папка. Якщо папка містить будь-які повідомлення, буде викликано виняток NotEmptyError і папку не буде видалено.

get_sequences()

Повертає словник імен послідовностей, зіставлених зі списками ключів. Якщо послідовностей немає, повертається порожній словник.

set_sequences(sequences)

Повторно визначте послідовності, які існують у поштовій скриньці, на основі sequences, словника імен, зіставлених зі списками ключів, як повертає get_sequences().

pack()

Перейменуйте повідомлення в поштовій скриньці за потреби, щоб усунути прогалини в нумерації. Записи в списку послідовностей оновлюються відповідно.

Примітка

Уже видані ключі стають недійсними під час цієї операції та не повинні використовуватися згодом.

Some Mailbox methods implemented by MH deserve special remarks:

remove(key)

__delitem__(key)

discard(key)

Ці методи негайно видаляють повідомлення. Угода MH про позначення повідомлення для видалення шляхом додавання коми перед його назвою не використовується.

lock()

unlock()

Three locking mechanisms are used—dot locking and, if available, the flock() and lockf() system calls. For MH mailboxes, locking the mailbox means locking the .mh_sequences file and, only for the duration of any operations that affect them, locking individual message files.

get_file(key)

Залежно від хост-платформи може бути неможливо видалити базове повідомлення, поки повернутий файл залишається відкритим.

flush()

Усі зміни до поштових скриньок MH негайно застосовуються, тому цей метод нічого не робить.

close()

MH instances do not keep any open files, so this method is equivalent to unlock().

Дивись також

nmh - Message Handling System

Домашня сторінка nmh, оновленої версії оригінальної mh.

MH & nmh: Електронна пошта для користувачів і програмістів

Ліцензована GPL книга про mh і nmh, з деякою інформацією про формат поштової скриньки.

Babyl objects

class mailbox.Babyl(path, factory=None, create=True)

Підклас Mailbox для поштових скриньок у форматі Babyl. Параметр factory — це викликаючий об’єкт, який приймає файлоподібне представлення повідомлення (яке поводиться так, ніби відкрито в двійковому режимі) і повертає спеціальне представлення. Якщо factory має значення None, BabylMessage використовується як типове представлення повідомлення. Якщо create має значення True, поштова скринька буде створена, якщо вона не існує.

Babyl — це однофайловий формат поштової скриньки, який використовується поштовим агентом користувача Rmail, що входить до складу Emacs. Початок повідомлення позначається рядком, що містить два символи Control-Underscore ('\037') і Control-L ('\014'). Кінець повідомлення позначається початком наступного повідомлення або, у випадку останнього повідомлення, рядком, що містить символ Control-Underscore ('\037').

Повідомлення в поштовій скриньці Babyl мають два набори заголовків, оригінальні заголовки та так звані видимі заголовки. Видимі заголовки зазвичай є підмножиною вихідних заголовків, які було переформатовано або скорочено, щоб бути більш привабливими. Кожне повідомлення в поштовій скриньці Babyl також має супровідний список labels або коротких рядків, які записують додаткову інформацію про повідомлення, а список усіх визначених користувачем міток, знайдених у поштовій скриньці, зберігається в розділі параметрів Babyl .

Babyl instances have all of the methods of Mailbox in addition to the following:

get_labels()

Повертає список імен усіх визначених користувачем міток, які використовуються в поштовій скриньці.

Примітка

Фактичні повідомлення перевіряються, щоб визначити, які мітки існують у поштовій скриньці, замість перегляду списку міток у розділі параметрів Babyl, але розділ Babyl оновлюється щоразу, коли поштова скринька змінюється.

Some Mailbox methods implemented by Babyl deserve special remarks:

get_file(key)

У поштових скриньках Babyl заголовки повідомлення не зберігаються поруч із тілом повідомлення. Щоб створити файлоподібне представлення, заголовки та тіло копіюються разом у екземпляр io.BytesIO, який має API, ідентичний API файлу. Як наслідок, файлоподібний об’єкт справді не залежить від базової поштової скриньки, але не економить пам’ять у порівнянні з представленням рядків.

lock()

unlock()

Three locking mechanisms are used—dot locking and, if available, the flock() and lockf() system calls.

Дивись також

Формат файлів Babyl версії 5

Специфікація формату Babyl.

Читання пошти за допомогою Rmail

Посібник Rmail з деякою інформацією про семантику Babyl.

MMDF objects

class mailbox.MMDF(path, factory=None, create=True)

Підклас Mailbox для поштових скриньок у форматі MMDF. Параметр factory — це викликаючий об’єкт, який приймає файлоподібне представлення повідомлення (яке поводиться так, ніби відкрито в двійковому режимі) і повертає спеціальне представлення. Якщо factory має значення None, MMDFMessage використовується як типове представлення повідомлення. Якщо create має значення True, поштова скринька буде створена, якщо вона не існує.

MMDF — це однофайловий формат поштової скриньки, винайдений для Multichannel Memorandum Distribution Facility, агента пересилання пошти. Кожне повідомлення має таку саму форму, що й повідомлення mbox, але в дужках перед і після рядки містять чотири символи Control-A ('\001'). Як і у форматі mbox, початок кожного повідомлення позначається рядком, перші п’ять символів якого є «Від», але додаткові входження «Від» не перетворюються на «>Від» під час зберігання повідомлень, оскільки додаткові рядки-роздільники повідомлень запобігають помилково приймаючи такі випадки за початок наступних повідомлень.

Some Mailbox methods implemented by MMDF deserve special remarks:

get_file(key)

Using the file after calling flush() or close() on the MMDF instance may yield unpredictable results or raise an exception.

lock()

unlock()

Three locking mechanisms are used—dot locking and, if available, the flock() and lockf() system calls.

Дивись також

сторінка довідки mmdf з tin

Специфікація формату MMDF із документації tin, читання новин.

MMDF

Стаття у Вікіпедії, що описує багатоканальний засіб розповсюдження меморандумів.

Message objects

class mailbox.Message(message=None)

A subclass of the email.message module’s Message. Subclasses of mailbox.Message add mailbox-format-specific state and behavior.

If message is omitted, the new instance is created in a default, empty state. If message is an email.message.Message instance, its contents are copied; furthermore, any format-specific information is converted insofar as possible if message is a Message instance. If message is a string, a byte string, or a file, it should contain an RFC 2822-compliant message, which is read and parsed. Files should be open in binary mode, but text mode files are accepted for backward compatibility.

Специфічний для формату стан і поведінка, запропоновані підкласами, відрізняються, але загалом підтримуються лише ті властивості, які не є специфічними для конкретної поштової скриньки (хоча, імовірно, властивості є специфічними для певного формату поштової скриньки). Наприклад, зміщення файлів для однофайлових форматів поштової скриньки та імена файлів для форматів поштової скриньки на основі каталогу не зберігаються, оскільки вони застосовуються лише до оригінальної поштової скриньки. Але інформація про те, чи було повідомлення прочитано користувачем або позначено як важливе, зберігається, оскільки воно стосується самого повідомлення.

There is no requirement that Message instances be used to represent messages retrieved using Mailbox instances. In some situations, the time and memory required to generate Message representations might not be acceptable. For such situations, Mailbox instances also offer string and file-like representations, and a custom message factory may be specified when a Mailbox instance is initialized.

MaildirMessage objects

class mailbox.MaildirMessage(message=None)

Повідомлення зі специфічною поведінкою Maildir. Параметр message має те саме значення, що й у конструкторі Message.

Як правило, програма поштового агента користувача переміщує всі повідомлення з підкаталогу new до підкаталогу cur після того, як користувач вперше відкриває та закриває поштову скриньку, записуючи, що повідомлення є старими незалежно від того чи вони насправді не були прочитані. Кожне повідомлення в cur має розділ «info», доданий до імені файлу для зберігання інформації про його стан. (Деякі програми для читання пошти також можуть додавати розділ «info» до повідомлень у new.) Розділ «info» може мати одну з двох форм: він може містити «2», після якого йде список стандартизованих позначок ( наприклад, «2,FR») або може містити «1», за яким слідує так звана експериментальна інформація. Стандартні позначки для повідомлень Maildir такі:

Прапор	Значення	Пояснення
Д	Чернетка	Під композицією
Ф	Позначено	Позначено як важливе
П	Пройшов	Переслано, повторно надіслано або відхилено
Р	Відповів	Відповів
С	Бачив	Прочитайте
Т	У кошик	Позначено для подальшого видалення

MaildirMessage instances offer the following methods:

get_subdir()

Повертає або «новий» (якщо повідомлення має зберігатися в підкаталозі new), або «cur» (якщо повідомлення має зберігатися в підкаталозі cur).

Примітка

Зазвичай повідомлення переміщується з new до cur після доступу до його поштової скриньки, незалежно від того, прочитано чи ні повідомлення. Повідомлення msg було прочитано, якщо "S" у msg.get_flags() має значення True.

set_subdir(subdir)

Встановіть підкаталог, у якому має зберігатися повідомлення. Параметр subdir повинен мати значення «new» або «cur».

get_flags()

Повертає рядок із зазначенням поточних встановлених прапорів. Якщо повідомлення відповідає стандартному формату Maildir, результатом є конкатенація в алфавітному порядку нуля або одного входження кожного з 'D', 'F', 'P', 'R', 'S' і 'T''. Порожній рядок повертається, якщо не встановлено прапори або якщо «info» містить експериментальну семантику.

set_flags(flags)

Встановіть прапорці, визначені flags, і скасуйте всі інші.

add_flag(flag)

Встановіть прапор(и), визначені flag, не змінюючи інші прапори. Щоб додати більше ніж один прапор одночасно, flag може бути рядком із кількох символів. Поточна «інформація» перезаписується незалежно від того, чи містить вона експериментальну інформацію, а не прапорці.

remove_flag(flag)

Скасувати прапор(и), визначені flag, не змінюючи інші прапори. Щоб видалити кілька прапорців одночасно, flag може бути рядком із кількох символів. Якщо «info» містить експериментальну інформацію, а не прапорці, поточна «info» не змінюється.

get_date()

Повертає дату доставки повідомлення як число з плаваючою комою, яке представляє секунди з епохи.

set_date(date)

Встановіть дату доставки повідомлення на date, число з плаваючою комою, яке представляє секунди з епохи.

get_info()

Повертає рядок, що містить «інформацію» про повідомлення. Це корисно для доступу та модифікації «інформації», яка є експериментальною (тобто не списку позначок).

set_info(info)

Встановіть для «info» значення info, яке має бути рядком.

When a MaildirMessage instance is created based upon an mboxMessage or MMDFMessage instance, the Status and X-Status headers are omitted and the following conversions take place:

Результуючий стан	стан mboxMessage або MMDFMessage
підкаталог «cur».	О прапор
Прапор F	Прапор F
Прапор R	Прапор
S прапор	Прапор R
Т прапор	D прапор

When a MaildirMessage instance is created based upon an MHMessage instance, the following conversions take place:

Результуючий стан	MHMessage стан
підкаталог «cur».	«невидима» послідовність
підкаталог «cur» і прапор S	немає «невидимої» послідовності
Прапор F	«позначена» послідовність
Прапор R	послідовність «відповів».

When a MaildirMessage instance is created based upon a BabylMessage instance, the following conversions take place:

Результуючий стан	BabylMessage стан
підкаталог «cur».	ярлик «невидимий».
підкаталог «cur» і прапор S	немає мітки «невидиме».
P прапор	мітка «переслано» або «повторно надіслано».
Прапор R	мітка «відповів».
Т прапор	ярлик «видалено».

mboxMessage objects

class mailbox.mboxMessage(message=None)

Повідомлення зі специфічною поведінкою mbox. Параметр message має те саме значення, що й у конструкторі Message.

Повідомлення в поштовій скриньці mbox зберігаються разом в одному файлі. Адреса конверта відправника та час доставки зазвичай зберігаються в рядку, що починається на «Від», який використовується для позначення початку повідомлення, хоча існують значні відмінності в точному форматі цих даних серед реалізацій mbox. Прапорці, які вказують на стан повідомлення, наприклад, чи було воно прочитано чи позначено як важливе, зазвичай зберігаються в заголовках Status і X-Status.

Звичайні позначки для повідомлень mbox такі:

Прапор	Значення	Пояснення
Р	Прочитайте	Прочитайте
О	Старий	Раніше виявлено MUA
Д	Видалено	Позначено для подальшого видалення
Ф	Позначено	Позначено як важливе
А	відповів	Відповів

Прапорці «R» і «O» зберігаються в заголовку Status, а прапорці «D», «F» і «A» зберігаються в заголовку X-Status. Прапорці та заголовки зазвичай з’являються у зазначеному порядку.

mboxMessage instances offer the following methods:

get_from()

Повертає рядок, що представляє рядок «Від», який позначає початок повідомлення в поштовій скриньці mbox. Початковий «Від» і кінцевий символ нового рядка виключаються.

set_from(from_, time_=None)

Set the «From « line to from_, which should be specified without a leading «From « or trailing newline. For convenience, time_ may be specified and will be formatted appropriately and appended to from_. If time_ is specified, it should be a time.struct_time instance, a tuple suitable for passing to time.strftime(), or True (to use time.gmtime()).

get_flags()

Повертає рядок із зазначенням поточних встановлених прапорів. Якщо повідомлення відповідає загальноприйнятому формату, результатом є конкатенація в наступному порядку нуля або одного входження кожного з 'R', 'O', 'D', 'F'' і 'A'.

set_flags(flags)

Встановіть прапорці, визначені flags, і скасуйте всі інші. Параметр flags має бути конкатенацією в будь-якому порядку нуля або більше входжень кожного з 'R', 'O', 'D', 'F' і 'A'.

add_flag(flag)

Встановіть прапор(и), визначені flag, не змінюючи інші прапори. Щоб додати більше ніж один прапор одночасно, flag може бути рядком із кількох символів.

remove_flag(flag)

Скасувати прапор(и), визначені flag, не змінюючи інші прапори. Щоб видалити кілька прапорців одночасно, flag може бути рядком із кількох символів.

When an mboxMessage instance is created based upon a MaildirMessage instance, a «From « line is generated based upon the MaildirMessage instance’s delivery date, and the following conversions take place:

Результуючий стан	MaildirMessage стан
Прапор R	S прапор
О прапор	підкаталог «cur».
D прапор	Т прапор
Прапор F	Прапор F
Прапор	Прапор R

When an mboxMessage instance is created based upon an MHMessage instance, the following conversions take place:

Результуючий стан	MHMessage стан
Прапор R і прапор O	немає «невидимої» послідовності
О прапор	«невидима» послідовність
Прапор F	«позначена» послідовність
Прапор	послідовність «відповів».

When an mboxMessage instance is created based upon a BabylMessage instance, the following conversions take place:

Результуючий стан	BabylMessage стан
Прапор R і прапор O	немає мітки «невидиме».
О прапор	ярлик «невидимий».
D прапор	ярлик «видалено».
Прапор	мітка «відповів».

When a mboxMessage instance is created based upon an MMDFMessage instance, the «From « line is copied and all flags directly correspond:

Результуючий стан	MMDFMessage стан
Прапор R	Прапор R
О прапор	О прапор
D прапор	D прапор
Прапор F	Прапор F
Прапор	Прапор

MHMessage objects

class mailbox.MHMessage(message=None)

Повідомлення зі специфічними для MH поведінками. Параметр message має те саме значення, що й у конструкторі Message.

Повідомлення MH не підтримують позначки чи прапорці в традиційному розумінні, але вони підтримують послідовності, які є логічними групами довільних повідомлень. Деякі програми читання пошти (хоча не стандартні mh і nmh) використовують послідовності приблизно так само, як прапорці використовуються з іншими форматами, а саме:

Послідовність	Пояснення
невидимий	Не прочитано, але раніше виявлено MUA
відповів	Відповів
позначено	Позначено як важливе

MHMessage instances offer the following methods:

get_sequences()

Повернути список імен послідовностей, які містять це повідомлення.

set_sequences(sequences)

Встановіть список послідовностей, які включають це повідомлення.

add_sequence(sequence)

Додайте послідовність до списку послідовностей, які містять це повідомлення.

remove_sequence(sequence)

Видаліть послідовність зі списку послідовностей, які містять це повідомлення.

When an MHMessage instance is created based upon a MaildirMessage instance, the following conversions take place:

Результуючий стан	MaildirMessage стан
«невидима» послідовність	немає прапора S
послідовність «відповів».	Прапор R
«позначена» послідовність	Прапор F

When an MHMessage instance is created based upon an mboxMessage or MMDFMessage instance, the Status and X-Status headers are omitted and the following conversions take place:

Результуючий стан	стан mboxMessage або MMDFMessage
«невидима» послідовність	немає прапора R
послідовність «відповів».	Прапор
«позначена» послідовність	Прапор F

When an MHMessage instance is created based upon a BabylMessage instance, the following conversions take place:

Результуючий стан	BabylMessage стан
«невидима» послідовність	ярлик «невидимий».
послідовність «відповів».	мітка «відповів».

BabylMessage objects

class mailbox.BabylMessage(message=None)

Повідомлення з особливостями поведінки Babyl. Параметр message має те саме значення, що й у конструкторі Message.

Певні мітки повідомлень, які називаються attributes, визначені угодою як такі, що мають спеціальні значення. Атрибути такі:

Мітка	Пояснення
невидимий	Не прочитано, але раніше виявлено MUA
видалено	Позначено для подальшого видалення
подано	Скопійовано в інший файл або поштову скриньку
відповів	Відповів
пересилається	Переслано
відредаговано	Змінено користувачем
обурюватися	Обурюватися

By default, Rmail displays only visible headers. The BabylMessage class, though, uses the original headers because they are more complete. Visible headers may be accessed explicitly if desired.

BabylMessage instances offer the following methods:

get_labels()

Повернути список міток у повідомленні.

set_labels(labels)

Установіть список міток у повідомленні на мітки.

add_label(label)

Додайте label до списку міток у повідомленні.

remove_label(label)

Видаліть label зі списку міток у повідомленні.

get_visible()

Повертає екземпляр Message, заголовки якого є видимими заголовками повідомлення, а тіло порожнє.

set_visible(visible)

Налаштуйте видимі заголовки повідомлення такими ж, як заголовки в повідомленні. Параметр visible має бути екземпляром Message, екземпляром email.message.Message, рядком або файлоподібним об’єктом (який має бути відкритий у текстовому режимі).

update_visible()

When a BabylMessage instance’s original headers are modified, the visible headers are not automatically modified to correspond. This method updates the visible headers as follows: each visible header with a corresponding original header is set to the value of the original header, each visible header without a corresponding original header is removed, and any of Date, From, Reply-To, To, CC, and Subject that are present in the original headers but not the visible headers are added to the visible headers.

When a BabylMessage instance is created based upon a MaildirMessage instance, the following conversions take place:

Результуючий стан	MaildirMessage стан
ярлик «невидимий».	немає прапора S
ярлик «видалено».	Т прапор
мітка «відповів».	Прапор R
мітка «переслано».	P прапор

When a BabylMessage instance is created based upon an mboxMessage or MMDFMessage instance, the Status and X-Status headers are omitted and the following conversions take place:

Результуючий стан	стан mboxMessage або MMDFMessage
ярлик «невидимий».	немає прапора R
ярлик «видалено».	D прапор
мітка «відповів».	Прапор

When a BabylMessage instance is created based upon an MHMessage instance, the following conversions take place:

Результуючий стан	MHMessage стан
ярлик «невидимий».	«невидима» послідовність
мітка «відповів».	послідовність «відповів».

MMDFMessage objects

class mailbox.MMDFMessage(message=None)

Повідомлення зі специфічною для MMDF поведінкою. Параметр message має те саме значення, що й у конструкторі Message.

Як і повідомлення в поштовій скриньці mbox, повідомлення MMDF зберігаються з адресою відправника та датою доставки в початковому рядку, що починається з «Від». Подібним чином прапорці, які вказують на стан повідомлення, зазвичай зберігаються в заголовках Status і X-Status.

Звичайні позначки для повідомлень MMDF ідентичні прапорцям для повідомлень mbox і такі:

Прапор	Значення	Пояснення
Р	Прочитайте	Прочитайте
О	Старий	Раніше виявлено MUA
Д	Видалено	Позначено для подальшого видалення
Ф	Позначено	Позначено як важливе
А	відповів	Відповів

Прапорці «R» і «O» зберігаються в заголовку Status, а прапорці «D», «F» і «A» зберігаються в заголовку X-Status. Прапорці та заголовки зазвичай з’являються у зазначеному порядку.

MMDFMessage instances offer the following methods, which are identical to those offered by mboxMessage:

get_from()

Повертає рядок, що представляє рядок «Від», який позначає початок повідомлення в поштовій скриньці mbox. Початковий «Від» і кінцевий символ нового рядка виключаються.

set_from(from_, time_=None)

Set the «From « line to from_, which should be specified without a leading «From « or trailing newline. For convenience, time_ may be specified and will be formatted appropriately and appended to from_. If time_ is specified, it should be a time.struct_time instance, a tuple suitable for passing to time.strftime(), or True (to use time.gmtime()).

get_flags()

Повертає рядок із зазначенням поточних встановлених прапорів. Якщо повідомлення відповідає загальноприйнятому формату, результатом є конкатенація в наступному порядку нуля або одного входження кожного з 'R', 'O', 'D', 'F'' і 'A'.

set_flags(flags)

Встановіть прапорці, визначені flags, і скасуйте всі інші. Параметр flags має бути конкатенацією в будь-якому порядку нуля або більше входжень кожного з 'R', 'O', 'D', 'F' і 'A'.

add_flag(flag)

Встановіть прапор(и), визначені flag, не змінюючи інші прапори. Щоб додати більше ніж один прапор одночасно, flag може бути рядком із кількох символів.

remove_flag(flag)

Скасувати прапор(и), визначені flag, не змінюючи інші прапори. Щоб видалити кілька прапорців одночасно, flag може бути рядком із кількох символів.

When an MMDFMessage instance is created based upon a MaildirMessage instance, a «From « line is generated based upon the MaildirMessage instance’s delivery date, and the following conversions take place:

Результуючий стан	MaildirMessage стан
Прапор R	S прапор
О прапор	підкаталог «cur».
D прапор	Т прапор
Прапор F	Прапор F
Прапор	Прапор R

When an MMDFMessage instance is created based upon an MHMessage instance, the following conversions take place:

Результуючий стан	MHMessage стан
Прапор R і прапор O	немає «невидимої» послідовності
О прапор	«невидима» послідовність
Прапор F	«позначена» послідовність
Прапор	послідовність «відповів».

When an MMDFMessage instance is created based upon a BabylMessage instance, the following conversions take place:

Результуючий стан	BabylMessage стан
Прапор R і прапор O	немає мітки «невидиме».
О прапор	ярлик «невидимий».
D прапор	ярлик «видалено».
Прапор	мітка «відповів».

When an MMDFMessage instance is created based upon an mboxMessage instance, the «From « line is copied and all flags directly correspond:

Результуючий стан	mboxMessage стан
Прапор R	Прапор R
О прапор	О прапор
D прапор	D прапор
Прапор F	Прапор F
Прапор	Прапор

Винятки

The following exception classes are defined in the mailbox module:

exception mailbox.Error

Основний клас для всіх інших винятків, специфічних для модуля.

exception mailbox.NoSuchMailboxError

Викликається, коли поштова скринька очікується, але не знайдена, наприклад, під час створення екземпляра підкласу Mailbox із шляхом, якого не існує (і з параметром create, встановленим на False), або під час відкриття папку, яка не існує.

exception mailbox.NotEmptyError

Викликається, коли поштова скринька не порожня, але очікується, що вона буде порожньою, наприклад, під час видалення папки, яка містить повідомлення.

exception mailbox.ExternalClashError

Raised when some mailbox-related condition beyond the control of the program causes it to be unable to proceed, such as when failing to acquire a lock that another program already holds a lock, or when a uniquely generated file name already exists.

exception mailbox.FormatError

Викликається, коли дані у файлі неможливо проаналізувати, наприклад, коли примірник MH намагається прочитати пошкоджений файл .mh_sequences.

Приклади

Простий приклад друку тем усіх повідомлень у поштовій скриньці, які здаються цікавими:

import mailbox
for message in mailbox.mbox('~/mbox'):
    subject = message['subject']       # Could possibly be None.
    if subject and 'python' in subject.lower():
        print(subject)

Щоб скопіювати всю пошту з поштової скриньки Babyl до поштової скриньки MH, перетворивши всю інформацію про певний формат, яку можна конвертувати:

import mailbox
destination = mailbox.MH('~/Mail')
destination.lock()
for message in mailbox.Babyl('~/RMAIL'):
    destination.add(mailbox.MHMessage(message))
destination.flush()
destination.unlock()

Цей приклад сортує пошту з кількох списків розсилки в різні поштові скриньки, намагаючись уникнути пошкодження пошти через одночасну модифікацію іншими програмами, втрати пошти через переривання програми або передчасне завершення через неправильно сформовані повідомлення в поштовій скриньці:

import mailbox
import email.errors

list_names = ('python-list', 'python-dev', 'python-bugs')

boxes = {name: mailbox.mbox('~/email/%s' % name) for name in list_names}
inbox = mailbox.Maildir('~/Maildir', factory=None)

for key in inbox.iterkeys():
    try:
        message = inbox[key]
    except email.errors.MessageParseError:
        continue                # The message is malformed. Just leave it.

    for name in list_names:
        list_id = message['list-id']
        if list_id and name in list_id:
            # Get mailbox to use
            box = boxes[name]

            # Write copy to disk before removing original.
            # If there's a crash, you might duplicate a message, but
            # that's better than losing a message completely.
            box.lock()
            box.add(message)
            box.flush()
            box.unlock()

            # Remove original message
            inbox.lock()
            inbox.discard(key)
            inbox.flush()
            inbox.unlock()
            break               # Found destination, so stop looking.

for box in boxes.itervalues():
    box.close()