mailbox — Работа с почтовыми ящиками в различных форматах

Исходный код: Lib/mailbox.py

Этот модуль определяет два класса, Mailbox и Message, для доступа к почтовым ящикам на диске, работы с ними и содержащимися в них сообщениями. Mailbox предоставляет отображение ключей в сообщения, подобное словарю. Message расширяет класс email.message модуля Message, добавляя состояние и поведение, специфичные для формата. Поддерживаются форматы почтовых ящиков Maildir, mbox, MH, Babyl и MMDF.

См. также

Module email: Представление сообщений и работа с ними.

`Mailbox` объекты

class mailbox.Mailbox

Почтовый ящик, содержимое которого можно просматривать и изменять.

Класс Mailbox определяет интерфейс и не предназначен для создания экземпляров. Вместо этого подклассы для конкретных форматов должны наследоваться от Mailbox, а ваш код должен создавать экземпляр определённого подкласса.

Интерфейс Mailbox подобен словарю: небольшие ключи соответствуют сообщениям. Ключи выдаются экземпляром Mailbox, с которым они будут использоваться, и имеют смысл только для этого экземпляра Mailbox. Ключ продолжает идентифицировать сообщение, даже если соответствующее сообщение изменено, например заменено другим сообщением.

Сообщения можно добавлять в экземпляр Mailbox с помощью метода, подобного методу множества, add(), а удалять — с помощью оператора del или методов, подобных методам множества: remove() и discard().

Семантика интерфейса Mailbox отличается от семантики словаря в нескольких важных аспектах. Каждый раз при запросе сообщения на основе текущего состояния почтового ящика создаётся новое представление (обычно экземпляр Message). Аналогичным образом при добавлении сообщения в экземпляр Mailbox копируется содержимое предоставленного представления сообщения. В обоих случаях экземпляр Mailbox не сохраняет ссылку на представление сообщения.

Итератор Mailbox по умолчанию перебирает представления сообщений, а не ключи, в отличие от итератора dictionary по умолчанию. Кроме того, изменение почтового ящика во время итерации безопасно и имеет чётко определённое поведение. Сообщения, добавленные в почтовый ящик после создания итератора, не будут им обнаружены. Сообщения, удалённые из почтового ящика до того, как итератор их выдаст, будут молча пропущены, однако использование ключа из итератора может привести к исключению KeyError, если соответствующее сообщение впоследствии будет удалено.

Предупреждение

Будьте крайне осторожны при изменении почтовых ящиков, которые могут одновременно изменяться другим процессом. Для таких задач безопаснее всего использовать формат почтового ящика Maildir; старайтесь избегать одновременной записи в файлы форматов с одним файлом, например mbox. Если вы изменяете почтовый ящик, необходимо заблокировать его с помощью методов lock() и unlock() до чтения сообщений из файла или внесения изменений путём добавления либо удаления сообщений. Если не заблокировать почтовый ящик, можно потерять сообщения или повредить весь почтовый ящик.

Экземпляры Mailbox имеют следующие методы:

add(message)

Добавляет message в почтовый ящик и возвращает назначенный ему ключ.

Параметр message может быть экземпляром Message, экземпляром email.message.Message, строкой, байтовой строкой или файловоподобным объектом (который должен быть открыт в двоичном режиме). Если message является экземпляром соответствующего подкласса Message для определённого формата (например, если это экземпляр mboxMessage, а данный объект — экземпляр mbox), используются сведения, специфичные для этого формата. В противном случае применяются подходящие значения по умолчанию для сведений о формате.

Изменено в версии 3.2: Добавлена поддержка двоичных данных на входе.

remove(key)

__delitem__(key)

discard(key)

Удаляет из почтового ящика сообщение, соответствующее key.

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

__setitem__(key, message)

Заменяет сообщение, соответствующее key, на message. Если ключу key ещё не соответствует сообщение, возбуждается исключение KeyError.

Как и в случае с add(), параметр message может быть экземпляром Message, экземпляром email.message.Message, строкой, байтовой строкой или файловоподобным объектом (который должен быть открыт в двоичном режиме). Если message является экземпляром соответствующего подкласса Message для определённого формата (например, если это экземпляр mboxMessage, а данный объект — экземпляр mbox), используются сведения, специфичные для этого формата. В противном случае сведения о формате сообщения, которое сейчас соответствует key, остаются без изменений.

iterkeys(): Возвращает итератор по всем ключам.

keys(): То же, что и iterkeys(), но вместо итератора возвращается list.

itervalues()
__iter__(): Возвращает итератор по представлениям всех сообщений. Сообщения представлены экземплярами соответствующего подкласса Message для определённого формата, если при инициализации экземпляра Mailbox не была задана пользовательская фабрика сообщений.

Примечание

Поведение __iter__() отличается от поведения словарей, которые перебирают ключи.

values(): То же, что и itervalues(), но вместо итератора возвращается list.

iteritems(): Возвращает итератор по парам (key, message), где key — ключ, а message — представление сообщения. Сообщения представлены экземплярами соответствующего подкласса Message для определённого формата, если при инициализации экземпляра Mailbox не была задана пользовательская фабрика сообщений.

items(): То же, что и iteritems(), но вместо итератора по парам возвращается list пар.

get(key, default=None)
__getitem__(key): Возвращает представление сообщения, соответствующего key. Если такого сообщения нет, возвращается default, если метод был вызван как get(), а если метод был вызван как __getitem__(), возбуждается исключение KeyError. Сообщение представлено экземпляром соответствующего подкласса Message для определённого формата, если при инициализации экземпляра Mailbox не была задана пользовательская фабрика сообщений.

get_message(key): Возвращает представление сообщения, соответствующего key, в виде экземпляра соответствующего подкласса Message для определённого формата или возбуждает исключение KeyError, если такого сообщения нет.

get_bytes(key): Возвращает байтовое представление сообщения, соответствующего key, или возбуждает исключение KeyError, если такого сообщения нет.

Добавлено в версии 3.2.

get_string(key): Возвращает строковое представление сообщения, соответствующего key, или возбуждает исключение KeyError, если такого сообщения нет. Сообщение обрабатывается с помощью email.message.Message, чтобы преобразовать его в представление, состоящее только из 7-битных символов.

get_file(key): Возвращает файлоподобное представление сообщения, соответствующего key, или возбуждает исключение KeyError, если такого сообщения нет. Файлоподобный объект ведёт себя так, как если бы он был открыт в двоичном режиме. Этот файл следует закрыть, когда он больше не нужен.

Изменено в версии 3.2: Файловый объект теперь действительно является двоичным файлом; ранее он ошибочно возвращался в текстовом режиме. Кроме того, файлоподобный объект теперь поддерживает протокол менеджера контекста: можно использовать оператор with, чтобы автоматически закрыть его.

Примечание

В отличие от других представлений сообщений, файлоподобные представления не обязательно независимы от экземпляра Mailbox, который их создал, или от самого почтового ящика. Более подробная документация приведена для каждого подкласса.

__contains__(key): Возвращает True, если key соответствует сообщению, и False в противном случае.

__len__(): Возвращает количество сообщений в почтовом ящике.

clear(): Удаляет все сообщения из почтового ящика.

pop(key, default=None): Возвращает представление сообщения, соответствующего key, и удаляет это сообщение. Если такого сообщения нет, возвращается default. Сообщение представлено экземпляром соответствующего подкласса Message для определённого формата, если при инициализации экземпляра Mailbox не была задана пользовательская фабрика сообщений.

popitem(): Возвращает произвольную пару (key, message), где key — ключ, а message — представление сообщения, и удаляет соответствующее сообщение. Если почтовый ящик пуст, возбуждается исключение KeyError. Сообщение представлено экземпляром соответствующего подкласса Message для определённого формата, если при инициализации экземпляра Mailbox не была задана пользовательская фабрика сообщений.

update(arg): Параметр arg должен быть отображением «key — message» или итерируемым объектом из пар (key, message). Обновляет почтовый ящик так, чтобы для каждой заданной пары key и message сообщение, соответствующее key, было установлено в message, как если бы использовался метод __setitem__(). Как и в случае с __setitem__(), каждому key уже должно соответствовать сообщение в почтовом ящике, иначе будет возбуждено исключение KeyError. Поэтому в общем случае Mailbox не может быть экземпляром.

Примечание

В отличие от словарей, именованные аргументы не поддерживаются.

flush(): Записывает все ожидающие изменения в файловую систему. В некоторых подклассах Mailbox изменения записываются немедленно, и flush() ничего не делает, однако всё равно следует выработать привычку вызывать этот метод.

lock(): Получает эксклюзивную рекомендательную блокировку почтового ящика, чтобы другие процессы знали, что его не следует изменять. Если блокировка недоступна, возбуждается исключение ExternalClashError. Используемые механизмы блокировки зависят от формата почтового ящика. Перед любым изменением его содержимого следует обязательно заблокировать почтовый ящик.

unlock(): Снимает блокировку почтового ящика, если она установлена.

close(): Сбрасывает изменения почтового ящика, при необходимости снимает блокировку и закрывает все открытые файлы. Для некоторых подклассов Mailbox этот метод ничего не делает.

`Maildir` объекты

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», добавляемом к имени файла.

Также поддерживаются папки в стиле, введённом почтовым агентом передачи сообщений Courier. Любой подкаталог основного почтового ящика считается папкой, если '.' является первым символом в его имени. Имена папок представлены как Maildir без начального '.'. Каждая папка сама по себе является почтовым ящиком Maildir, но не должна содержать другие папки. Вместо этого логическая вложенность обозначается с помощью '.', разделяющего уровни, например «Archived.2005.07».

colon

Спецификация Maildir требует использовать двоеточие (':') в некоторых именах файлов сообщений. Однако некоторые операционные системы не допускают этот символ в именах файлов. Если вы хотите использовать формат, подобный Maildir, в такой операционной системе, следует указать другой символ для этой цели. Часто выбирают восклицательный знак ('!'). Например:

import mailbox
mailbox.Maildir.colon = '!'

Атрибут colon также можно задать отдельно для каждого экземпляра.

Экземпляры Maildir имеют все методы Mailbox, а также следующие методы:

list_folders(): Возвращает список имён всех папок.

get_folder(folder): Возвращает экземпляр Maildir, представляющий папку с именем folder. Если папка не существует, возбуждается исключение NoSuchMailboxError.

add_folder(folder): Создаёт папку с именем folder и возвращает представляющий её экземпляр Maildir.

remove_folder(folder): Удаляет папку с именем folder. Если папка содержит сообщения, возбуждается исключение NotEmptyError, и папка не удаляется.

clean(): Удаляет из почтового ящика временные файлы, к которым не обращались в течение последних 36 часов. Согласно спецификации Maildir, программы для чтения почты должны время от времени выполнять эту операцию.

Некоторые методы Mailbox, реализованные в Maildir, заслуживают особого упоминания:

add(message)
__setitem__(key, message)
update(arg): Предупреждение

Эти методы создают уникальные имена файлов на основе идентификатора текущего процесса. При использовании нескольких потоков могут возникнуть незамеченные конфликты имён, которые приведут к повреждению почтового ящика, если потоки не согласованы так, чтобы избежать одновременного использования этих методов для изменения одного и того же почтового ящика.

flush(): Все изменения в почтовых ящиках Maildir применяются немедленно, поэтому этот метод ничего не делает.

lock()
unlock(): Почтовые ящики Maildir не поддерживают блокировку (и не требуют её), поэтому эти методы ничего не делают.

close(): Экземпляры Maildir не держат открытых файлов, а используемые почтовые ящики не поддерживают блокировку, поэтому этот метод ничего не делает.

get_file(key): В зависимости от платформы хоста может оказаться невозможным изменить или удалить исходное сообщение, пока возвращённый файл остаётся открытым.

См. также

Справочная страница Maildir от Courier: Спецификация формата. Описывает распространённое расширение для поддержки папок.
Использование формата Maildir: Заметки о Maildir, написанные его создателем. Включают обновлённую схему создания имён и подробности о семантике «info».

`mbox` объекты

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

Подкласс Mailbox для почтовых ящиков в формате mbox. Параметр factory — вызываемый объект, который принимает файловоподобное представление сообщения (ведущее себя так, как если бы оно было открыто в двоичном режиме) и возвращает пользовательское представление. Если factory равен None, в качестве представления сообщения по умолчанию используется mboxMessage. Если create равен True, почтовый ящик создаётся, если он не существует.

Формат mbox — классический формат хранения почты в системах Unix. Все сообщения в почтовом ящике mbox хранятся в одном файле; начало каждого сообщения обозначается строкой, первые пять символов которой — «From ».

Существует несколько вариантов формата mbox, призванных устранить предполагаемые недостатки исходного формата. Для обеспечения совместимости mbox реализует исходный формат, который иногда называют mboxo. Это означает, что заголовок Content-Length, если он присутствует, игнорируется, а все вхождения «From » в начале строки в теле сообщения при сохранении сообщения преобразуются в «>From ». При чтении сообщения вхождения «>From » обратно в «From » не преобразуются.

Некоторые методы Mailbox, реализованные в mbox, заслуживают особого упоминания:

get_file(key): Использование файла после вызова flush() или close() для экземпляра mbox может привести к непредсказуемым результатам или возбуждению исключения.

lock()
unlock(): Используются три механизма блокировки: блокировка с помощью точечного файла и системные вызовы flock() и lockf(), если они доступны.

См. также

Справочная страница mbox от tin: Спецификация формата с подробными сведениями о блокировке.
Настройка Netscape Mail в Unix: почему формат Content-Length плох: Аргументы в пользу использования исходного формата mbox, а не его варианта.
«mbox» — это семейство нескольких несовместимых форматов почтовых ящиков: История вариантов mbox.

`MH` объекты

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

Подкласс Mailbox для почтовых ящиков в формате MH. Параметр factory — вызываемый объект, который принимает представление сообщения в виде файла (ведущее себя так, как если бы файл был открыт в двоичном режиме) и возвращает пользовательское представление. Если factory равен None, в качестве представления сообщения по умолчанию используется MHMessage. Если create равен True, почтовый ящик создаётся, если он не существует.

MH — это формат почтового ящика на основе каталогов, созданный для MH Message Handling System, пользовательского почтового агента. Каждое сообщение в почтовом ящике MH хранится в отдельном файле. Помимо сообщений, почтовый ящик MH может содержать другие почтовые ящики MH (называемые папками). Папки можно вкладывать друг в друга без ограничений. Почтовые ящики MH также поддерживают последовательности — именованные списки, используемые для логической группировки сообщений без их перемещения во вложенные папки. Последовательности определяются в файле с именем .mh_sequences в каждой папке.

Класс MH управляет почтовыми ящиками MH, но не пытается эмулировать все особенности поведения mh. В частности, он не изменяет файлы context или .mh_profile, используемые mh для хранения состояния и конфигурации, и на него не влияют изменения этих файлов.

Экземпляры MH имеют все методы Mailbox, а также следующие методы:

list_folders(): Возвращает список имён всех папок.

get_folder(folder): Возвращает экземпляр MH, представляющий папку с именем folder. Если папка не существует, возникает исключение NoSuchMailboxError.

add_folder(folder): Создаёт папку с именем folder и возвращает представляющий её экземпляр MH.

remove_folder(folder): Удаляет папку с именем folder. Если папка содержит сообщения, возникает исключение NotEmptyError, и папка не удаляется.

get_sequences(): Возвращает словарь, в котором именам последовательностей соответствуют списки ключей. Если последовательностей нет, возвращается пустой словарь.

set_sequences(sequences): Переопределяет последовательности в почтовом ящике на основе sequences — словаря, в котором именам соответствуют списки ключей, аналогичного возвращаемому методом get_sequences().

pack(): При необходимости переименовывает сообщения в почтовом ящике, чтобы устранить пропуски в нумерации. Записи в списке последовательностей соответствующим образом обновляются.

Примечание

Ключи, выданные ранее, становятся недействительными после этой операции, поэтому их не следует использовать впоследствии.

Некоторые методы Mailbox, реализованные в MH, требуют особых пояснений:

remove(key)
__delitem__(key)
discard(key): Эти методы немедленно удаляют сообщение. Соглашение MH, согласно которому сообщение помечается для удаления путём добавления запятой в начало его имени, не используется.

lock()
unlock(): Используются три механизма блокировки: блокировка с помощью файлов-маркеров и, если доступно, системные вызовы flock() и lockf(). Для почтовых ящиков MH блокировка почтового ящика означает блокировку файла .mh_sequences и блокировку отдельных файлов сообщений только на время операций, затрагивающих их.

get_file(key): В зависимости от платформы хоста удалить исходное сообщение может быть невозможно, пока возвращённый файл остаётся открытым.

flush(): Все изменения в почтовых ящиках MH применяются немедленно, поэтому этот метод ничего не делает.

close(): Экземпляры MH не держат открытых файлов, поэтому этот метод эквивалентен unlock().

См. также

nmh — система обработки сообщений: Домашняя страница nmh — обновлённой версии оригинальной системы mh.
MH и nmh: электронная почта для пользователей и программистов: Книга о mh и nmh, распространяемая по лицензии GPL и содержащая сведения о формате почтового ящика.

`Babyl` объекты

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 также сопровождается списком меток — коротких строк, содержащих дополнительную информацию о сообщении; список всех пользовательских меток, найденных в почтовом ящике, хранится в разделе параметров Babyl.

Экземпляры Babyl имеют все методы Mailbox, а также следующие методы:

get_labels(): Возвращает список имён всех пользовательских меток, используемых в почтовом ящике.

Примечание

Для определения существующих в почтовом ящике меток проверяются сами сообщения, а не список меток в разделе параметров Babyl; при этом раздел Babyl обновляется при каждом изменении почтового ящика.

Некоторые методы Mailbox, реализованные в Babyl, требуют особых пояснений:

get_file(key): В почтовых ящиках Babyl заголовки сообщения хранятся отдельно от его тела. Чтобы создать представление в виде файла, заголовки и тело копируются вместе в экземпляр io.BytesIO, API которого идентичен API файла. В результате объект, подобный файлу, полностью независим от исходного почтового ящика, но не экономит память по сравнению со строковым представлением.

lock()
unlock(): Используются три механизма блокировки: блокировка с помощью файлов-маркеров и, если доступно, системные вызовы flock() и lockf().

См. также

Формат файлов Babyl версии 5: Спецификация формата Babyl.
Чтение почты с помощью Rmail: Руководство по Rmail, содержащее сведения о семантике Babyl.

`MMDF` объекты

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, начало каждого сообщения обозначается строкой, первые пять символов которой — «From », однако дополнительные вхождения «From » при сохранении сообщений не преобразуются в «>From », поскольку дополнительные разделители сообщений предотвращают ошибочное распознавание таких вхождений как начала последующих сообщений.

Некоторые методы Mailbox, реализованные в MMDF, требуют особых пояснений:

get_file(key): Использование файла после вызова flush() или close() для экземпляра MMDF может привести к непредсказуемым результатам или вызвать исключение.

lock()
unlock(): Используются три механизма блокировки: блокировка с помощью файлов-маркеров и, если доступно, системные вызовы flock() и lockf().

См. также

Страница руководства mmdf в tin: Спецификация формата MMDF из документации к tin — программе для чтения новостей.
MMDF: Статья в Википедии о Multichannel Memorandum Distribution Facility.

Объекты `Message`

class mailbox.Message(message=None)

Подкласс класса email.message модуля Message. Подклассы mailbox.Message добавляют состояние и поведение, специфичные для формата почтового ящика.

Если параметр message не указан, новый экземпляр создаётся в состоянии по умолчанию — пустом. Если message — экземпляр email.message.Message, его содержимое копируется; кроме того, если message является экземпляром Message, любая специфичная для формата информация преобразуется настолько, насколько это возможно. Если message — строка, байтовая строка или файл, он должен содержать сообщение, соответствующее RFC 2822, которое будет прочитано и обработано. Файлы следует открывать в двоичном режиме, однако для обратной совместимости допускаются файлы в текстовом режиме.

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

Не требуется использовать экземпляры Message для представления сообщений, полученных с помощью экземпляров Mailbox. В некоторых ситуациях время и память, необходимые для создания представлений Message, могут быть неприемлемы. Для таких случаев экземпляры Mailbox также предоставляют строковое представление и представление в виде файлового объекта, а при инициализации экземпляра Mailbox можно указать пользовательскую фабрику сообщений.

Объекты `MaildirMessage`

class mailbox.MaildirMessage(message=None)

Сообщение с поведением, специфичным для Maildir. Параметр message имеет то же значение, что и в конструкторе Message.

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

Флаг	Значение	Пояснение
D	Черновик	Создаётся
F	Помечено	Отмечено как важное
P	Переслано	Переслано, отправлено повторно или возвращено отправителю
R	Отвечено	На сообщение ответили
S	Просмотрено	Прочитано
T	Удалено	Отмечено для последующего удаления

Экземпляры MaildirMessage предоставляют следующие методы:

get_subdir(): Возвращает «new» (если сообщение следует хранить в подкаталоге new) или «cur» (если сообщение следует хранить в подкаталоге cur).

Примечание

Обычно сообщение перемещается из new в cur после обращения к почтовому ящику, независимо от того, было ли сообщение прочитано. Сообщение msg считается прочитанным, если "S" in 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 может быть строкой из нескольких символов. Текущее значение «info» перезаписывается независимо от того, содержит ли оно экспериментальную информацию, а не флаги.

remove_flag(flag): Снимает флаг или флаги, указанные в flag, не изменяя остальные флаги. Чтобы удалить несколько флагов одновременно, flag может быть строкой из нескольких символов. Если «info» содержит экспериментальную информацию, а не флаги, текущее значение «info» не изменяется.

get_date(): Возвращает дату доставки сообщения в виде числа с плавающей точкой, представляющего количество секунд, прошедших с начала эпохи.

set_date(date): Задаёт дату доставки сообщения значением date — числом с плавающей точкой, представляющим количество секунд, прошедших с начала эпохи.

get_info(): Возвращает строку, содержащую «info» сообщения. Это полезно для доступа к экспериментальной информации в «info» (то есть не к списку флагов) и её изменения.

set_info(info): Задаёт для «info» значение info, которое должно быть строкой.

При создании экземпляра MaildirMessage на основе экземпляра mboxMessage или MMDFMessage заголовки Status и X-Status исключаются, а преобразования выполняются следующим образом:

Итоговое состояние	Состояние `mboxMessage` или `MMDFMessage`
Подкаталог «cur»	Флаг O
Флаг F	Флаг F
Флаг R	Флаг A
Флаг S	Флаг R
Флаг T	Флаг D

При создании экземпляра MaildirMessage на основе экземпляра MHMessage преобразования выполняются следующим образом:

Итоговое состояние	Состояние `MHMessage`
Подкаталог «cur»	Последовательность «unseen»
Подкаталог «cur» и флаг S	Нет последовательности «unseen»
Флаг F	Последовательность «flagged»
Флаг R	Последовательность «replied»

При создании экземпляра MaildirMessage на основе экземпляра BabylMessage преобразования выполняются следующим образом:

Итоговое состояние	Состояние `BabylMessage`
Подкаталог «cur»	Метка «unseen»
Подкаталог «cur» и флаг S	Нет метки «unseen»
Флаг P	Метка «forwarded» или «resent»
Флаг R	Метка «answered»
Флаг T	Метка «deleted»

Объекты `mboxMessage`

class mailbox.mboxMessage(message=None)

Сообщение с поведением, специфичным для mbox. Параметр message имеет то же значение, что и в конструкторе Message.

Сообщения в почтовом ящике mbox хранятся вместе в одном файле. Адрес отправителя из конверта и время доставки обычно записываются в строке, начинающейся с «From », которая обозначает начало сообщения, хотя точный формат этих данных значительно различается в разных реализациях mbox. Флаги, указывающие состояние сообщения, например сведения о том, прочитано ли оно или отмечено как важное, обычно хранятся в заголовках Status и X-Status.

Для сообщений mbox используются следующие общепринятые флаги:

Флаг	Значение	Пояснение
R	Прочитано	Прочитано
O	Старое	Ранее обнаружено почтовым клиентом (MUA)
D	Удалено	Отмечено для последующего удаления
F	Помечено	Отмечено как важное
A	Получен ответ	На сообщение ответили

Флаги «R» и «O» хранятся в заголовке Status, а флаги «D», «F» и «A» — в заголовке X-Status. Флаги и заголовки обычно следуют в указанном порядке.

Экземпляры mboxMessage предоставляют следующие методы:

get_from(): Возвращает строку, представляющую строку «From », которая обозначает начало сообщения в почтовом ящике mbox. Начальная часть «From » и завершающий символ новой строки не включаются.

set_from(from_, time_=None): Задаёт строку «From » равной from_, которую следует указать без начальной части «From » и завершающего символа новой строки. Для удобства можно указать time_: значение будет отформатировано соответствующим образом и добавлено к from_. Если параметр time_ указан, он должен быть экземпляром time.struct_time, кортежем, подходящим для передачи в time.strftime(), или True (для использования 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 может быть строкой из нескольких символов.

При создании экземпляра mboxMessage на основе экземпляра MaildirMessage строка «From » формируется на основе даты доставки экземпляра MaildirMessage, а преобразования выполняются следующим образом:

Итоговое состояние	Состояние `MaildirMessage`
Флаг R	Флаг S
Флаг O	Подкаталог «cur»
Флаг D	Флаг T
Флаг F	Флаг F
Флаг A	Флаг R

При создании экземпляра mboxMessage на основе экземпляра MHMessage преобразования выполняются следующим образом:

Итоговое состояние	Состояние `MHMessage`
Флаг R и флаг O	Нет последовательности «unseen»
Флаг O	Последовательность «unseen»
Флаг F	Последовательность «flagged»
Флаг A	Последовательность «replied»

При создании экземпляра mboxMessage на основе экземпляра BabylMessage преобразования выполняются следующим образом:

Итоговое состояние	Состояние `BabylMessage`
Флаг R и флаг O	Нет метки «unseen»
Флаг O	Метка «unseen»
Флаг F	Метка «flagged»
Флаг A	Метка «replied»

При создании экземпляра mboxMessage на основе экземпляра MMDFMessage строка «From » копируется, а все флаги напрямую соответствуют друг другу:

Итоговое состояние	Состояние `MMDFMessage`
Флаг R	Флаг R
Флаг O	Флаг O
Флаг D	Флаг D
Флаг F	Флаг F
Флаг A	Флаг A

Объекты `MHMessage`

class mailbox.MHMessage(message=None)

Сообщение с поведением, специфичным для MH. Параметр message имеет то же значение, что и в конструкторе Message.

В сообщениях MH не поддерживаются отметки или флаги в традиционном смысле, однако поддерживаются последовательности — логические группы произвольных сообщений. Некоторые программы для чтения почты (но не стандартные mh и nmh) используют последовательности примерно так же, как флаги в других форматах, следующим образом:

Последовательность	Пояснение
unseen	Не прочитано, но ранее обнаружено почтовым клиентом (MUA)
replied	На сообщение ответили
flagged	Отмечено как важное

Экземпляры MHMessage предоставляют следующие методы:

get_sequences(): Возвращает список имён последовательностей, в которые входит это сообщение.

set_sequences(sequences): Задаёт список последовательностей, в которые входит это сообщение.

add_sequence(sequence): Добавляет sequence в список последовательностей, в которые входит это сообщение.

remove_sequence(sequence): Удаляет sequence из списка последовательностей, в которые входит это сообщение.

При создании экземпляра MHMessage на основе экземпляра MaildirMessage преобразования выполняются следующим образом:

Итоговое состояние	Состояние `MaildirMessage`
Последовательность «unseen»	Нет флага S
Последовательность «replied»	Флаг R
Последовательность «flagged»	Флаг F

При создании экземпляра MHMessage на основе экземпляра mboxMessage или MMDFMessage заголовки Status и X-Status исключаются, а преобразования выполняются следующим образом:

Итоговое состояние	Состояние `mboxMessage` или `MMDFMessage`
Последовательность «unseen»	Нет флага R
Последовательность «replied»	Флаг A
Последовательность «flagged»	Флаг F

При создании экземпляра MHMessage на основе экземпляра BabylMessage преобразования выполняются следующим образом:

Итоговое состояние	Состояние `BabylMessage`
Последовательность «unseen»	Метка «unseen»
Последовательность «replied»	Метка «answered»

Объекты `BabylMessage`

class mailbox.BabylMessage(message=None)

Сообщение с поведением, специфичным для Babyl. Параметр message имеет то же значение, что и в конструкторе Message.

Некоторые метки сообщений, называемые атрибутами, по соглашению имеют специальное значение. К таким атрибутам относятся:

Метка	Пояснение
unseen	Не прочитано, но ранее обнаружено почтовым клиентом (MUA)
deleted	Отмечено для последующего удаления
filed	Скопировано в другой файл или почтовый ящик
answered	На сообщение ответили
forwarded	Переслано
edited	Изменено пользователем
resent	Отправлено повторно

По умолчанию Rmail отображает только видимые заголовки. Однако класс BabylMessage использует исходные заголовки, поскольку они содержат больше информации. При необходимости можно получить доступ к видимым заголовкам явно.

Экземпляры BabylMessage предоставляют следующие методы:

get_labels(): Возвращает список меток сообщения.

set_labels(labels): Задаёт список меток сообщения равным labels.

add_label(label): Добавляет label в список меток сообщения.

remove_label(label): Удаляет label из списка меток сообщения.

get_visible(): Возвращает экземпляр Message, заголовками которого являются видимые заголовки сообщения, а тело пусто.

set_visible(visible): Задаёт видимые заголовки сообщения такими же, как заголовки в message. Параметр visible должен быть экземпляром Message или email.message.Message, строкой либо объектом, подобным файлу (который следует открыть в текстовом режиме).

update_visible(): При изменении исходных заголовков экземпляра BabylMessage видимые заголовки не обновляются автоматически. Этот метод обновляет видимые заголовки следующим образом: каждый видимый заголовок, которому соответствует исходный заголовок, получает значение исходного заголовка; каждый видимый заголовок, которому не соответствует исходный заголовок, удаляется; заголовки Date, From, Reply-To, To, CC и Subject, присутствующие в исходных заголовках, но отсутствующие среди видимых, добавляются к видимым заголовкам.

При создании экземпляра BabylMessage на основе экземпляра MaildirMessage преобразования выполняются следующим образом:

Итоговое состояние	Состояние `MaildirMessage`
Метка «unseen»	Нет флага S
Метка «deleted»	Флаг T
Метка «answered»	Флаг R
Метка «forwarded»	Флаг P

При создании экземпляра BabylMessage на основе экземпляра mboxMessage или MMDFMessage заголовки Status и X-Status исключаются, а преобразования выполняются следующим образом:

Итоговое состояние	Состояние `mboxMessage` или `MMDFMessage`
Метка «unseen»	Нет флага R
Метка «deleted»	Флаг D
Метка «answered»	Флаг A

При создании экземпляра BabylMessage на основе экземпляра MHMessage преобразования выполняются следующим образом:

Итоговое состояние	Состояние `MHMessage`
Метка «unseen»	Последовательность «unseen»
Метка «answered»	Последовательность «replied»

`MMDFMessage` объекты

class mailbox.MMDFMessage(message=None)

Сообщение со специфичным для MMDF поведением. Параметр message имеет то же значение, что и в конструкторе Message.

Как и сообщения в почтовом ящике mbox, сообщения MMDF хранятся с адресом отправителя и датой доставки в начальной строке, начинающейся с «From ». Аналогично, флаги, указывающие состояние сообщения, обычно хранятся в заголовках Status и X-Status.

Стандартные флаги сообщений MMDF идентичны флагам сообщений mbox и перечислены ниже:

Флаг	Значение	Пояснение
R	Прочитано	Прочитано
O	Старое	Ранее обнаружено почтовым клиентом
D	Удалено	Помечено для последующего удаления
F	Помечено флагом	Отмечено как важное
A	Отвечено	На сообщение дан ответ

Флаги «R» и «O» хранятся в заголовке Status, а флаги «D», «F» и «A» — в заголовке X-Status. Флаги и заголовки обычно расположены в указанном порядке.

Экземпляры MMDFMessage предоставляют следующие методы, идентичные методам mboxMessage:

get_from(): Возвращает строку, представляющую строку «From », которая обозначает начало сообщения в почтовом ящике mbox. Начальная строка «From » и завершающий символ новой строки не включаются.

set_from(from_, time_=None): Задает строку «From » равной from_, которая должна быть указана без начального «From » и завершающего символа новой строки. Для удобства можно указать time_: он будет отформатирован соответствующим образом и добавлен к from_. Если указан time_, он должен быть экземпляром time.struct_time, кортежем, подходящим для передачи в time.strftime(), или True (для использования 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 может представлять собой строку из нескольких символов.

При создании экземпляра MMDFMessage на основе экземпляра MaildirMessage строка «From » формируется на основе даты доставки экземпляра MaildirMessage, а также выполняются следующие преобразования:

Итоговое состояние	Состояние `MaildirMessage`
Флаг R	Флаг S
Флаг O	Подкаталог «cur»
Флаг D	Флаг T
Флаг F	Флаг F
Флаг A	Флаг R

При создании экземпляра MMDFMessage на основе экземпляра MHMessage выполняются следующие преобразования:

Итоговое состояние	Состояние `MHMessage`
Флаги R и O	Нет последовательности «unseen»
Флаг O	Последовательность «unseen»
Флаг F	Последовательность «flagged»
Флаг A	Последовательность «replied»

При создании экземпляра MMDFMessage на основе экземпляра BabylMessage выполняются следующие преобразования:

Итоговое состояние	Состояние `BabylMessage`
Флаги R и O	Нет метки «unseen»
Флаг O	Метка «unseen»
Флаг D	Метка «deleted»
Флаг A	Метка «answered»

При создании экземпляра MMDFMessage на основе экземпляра mboxMessage строка «From » копируется, а все флаги напрямую соответствуют друг другу:

Итоговое состояние	Состояние `mboxMessage`
Флаг R	Флаг R
Флаг O	Флаг O
Флаг D	Флаг D
Флаг F	Флаг F
Флаг A	Флаг A

Исключения

В модуле mailbox определены следующие классы исключений:

exception mailbox.Error: Базовый класс для всех остальных исключений, специфичных для модуля.

exception mailbox.NoSuchMailboxError: Вызывается, когда ожидаемый почтовый ящик не найден, например при создании экземпляра подкласса Mailbox с путем, который не существует (и параметром create, установленным в False), или при открытии несуществующей папки.

exception mailbox.NotEmptyError: Вызывается, когда почтовый ящик не пуст, хотя ожидается, что он будет пустым, например при удалении папки, содержащей сообщения.

exception mailbox.ExternalClashError: Вызывается, когда обстоятельство, связанное с почтовым ящиком и не зависящее от программы, не позволяет ей продолжить работу, например при невозможности получить блокировку, уже удерживаемую другой программой, или если уникальное имя файла уже существует.

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()

mailbox — Работа с почтовыми ящиками в различных форматах

Mailbox объекты

Maildir объекты

mbox объекты

MH объекты

Babyl объекты

MMDF объекты

Объекты Message

Объекты MaildirMessage

Объекты mboxMessage

Объекты MHMessage

Объекты BabylMessage

MMDFMessage объекты

Исключения

Примеры

`Mailbox` объекты

`Maildir` объекты

`mbox` объекты

`MH` объекты

`Babyl` объекты

`MMDF` объекты

Объекты `Message`

Объекты `MaildirMessage`

Объекты `mboxMessage`

Объекты `MHMessage`

Объекты `BabylMessage`

`MMDFMessage` объекты