`mailbox` — Манипулирование почтовыми ящиками в различных форматах¶

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

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

См.также

Модуль email: Представление и управление сообщениями.

Объекты `Mailbox`¶

class mailbox.Mailbox¶

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

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

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

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

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

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

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

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

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. Вызвать исключение KeyError, если ни одно сообщение не соответствует key.

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

iterkeys()¶
keys()¶: Возвращает итератор по всем ключам, если вызывается как iterkeys() или возвращает список ключей, если вызывается как keys().

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

Примечание

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

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

get(key, default=None)¶
__getitem__(key)¶: Возвращает представление сообщения, соответствующего key. Если такого сообщения не существует, default является возвращенный, если метод был вызван как get(), и возникает исключение KeyError, если метод был вызван как __getitem__(). Сообщение представлено как сущность соответствующего определенного для формата 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 как будто при помощи __setitem__(). Как с __setitem__(), каждый key должен уже соответствовать сообщению в почтовом ящике, или иначе исключение KeyError будет поднято, так в целом неправильно для arg быть Mailbox сущность.

Примечание

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

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

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

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 и сохранить информацию о состояние сообщения в специальном разделе «информация», добавленном к его имени файла.

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

Примечание

Спецификация 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 man страница для Courier: Спецификация формата. Описывает общее расширение для поддержки папок.
Использование формата maildir: Заметки о Maildir его изобретателя. Включает обновленную схему создания имен и сведения о семантике «info».

`mbox`¶

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

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

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

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

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

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

iterkeys()¶
keys()¶: Три механизма захвата - захват используется — точка и, при наличии, 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, почтового агента пользователя. Каждое сообщение в почтовом ящике MH находится в собственном файле. Почтовый ящик MH может содержать другие почтовые ящики MH (называемые folders) в дополнение к сообщениям. Папки могут быть вложены бесконечно. Почтовые ящики MH также поддерживают sequences, которые именуются списками используемый для логически группирования сообщений без перемещения их в подпапки. Последовательности определяются в файле с именем .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: Электронная почта для пользователей и программистов: Книга с лицензией GPL на mh и nmh с некоторой информацией о формате почтового ящика.

`Babyl`¶

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

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

Babyl - это однофайловый формат почтового ящика, используемый пользовательским агентом почты Rmail, включенным в состав Emacs. Начало сообщения обозначается строкой, содержащей два символа Control-Estrore ('\037') и Control-L ('\014'). Конец сообщения обозначается началом следующего сообщения или, в случае последнего сообщения, строкой, содержащей '\037' Control-Estrore (символ).

Сообщения в почтовом ящике Babyl имеют два набора заголовков, оригинальные заголовки и так называемые видимые заголовки. Видимые заголовки обычно являются подмножеством исходных заголовков, которые были переформатированы или сокращены, чтобы быть более привлекательными. У каждого сообщения в почтовом ящике Babyl также есть сопровождающий список labels или короткие строки, которые делают запись дополнительной информации о сообщении, и список всех определенных пользователями этикеток, найденных в почтовом ящике, сохранен в разделе вариантов 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 представляет собой однофайловый формат почтового ящика, изобретенный для многоканального механизма распределения меморандумов, агента передачи почты. Каждое сообщение находится в той же форме, что и сообщение mbox, но заключено в скобки до и после строк, содержащих четыре символа Control-A ('\001'). Как и в случае с форматом mbox, начало каждого сообщения обозначается строкой, первые пять символов которой - «От», но дополнительные вхождения «От» не преобразуются в «> от» при сохранении сообщений, так как дополнительные строки разделителя сообщений предотвращают принятие таких случаев для начала последующих сообщений.

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

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

lock()¶
unlock()¶: Три механизма захвата - захват используется — точка и, при наличии, flock() и системные вызовы lockf().

См.также

mmdf man страница из tin: Спецификация формата MMDF из документации олова, диктора новостей.
MMDF: Статья в Википедии, описывающая многоканальный механизм распространения меморандумов.

Объекты `Message`¶

class mailbox.Message(message=None)¶

Подкласс Message модуля email.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 добавили «информационный» раздел к его имени файла, чтобы хранить информацию о его состояние. (Некоторые читатели почты могут также добавлять раздел «информация» к сообщениям в new.) раздел «информация» может принимать одну из двух форм: он может содержать «2», за которым следует список стандартизированных флагов (например, «2, FR»), или он может содержать «1», за которым следует так называемая экспериментальная информация. Стандартные флаги для сообщений Maildir:

Флаг	Значение	Объяснение
D	Draft	Под композицией
F	Flagged	Помечено как важное
P	Passed	Переадресовано, повторно отправлено или отклонено
R	Replied	Ответил на
S	Seen	Читать
T	Trashed	Помечено для последующего удаления

MaildirMessage сущности предлагаем следующие методы:

get_subdir()¶: Возвращает либо «новый» (если сообщение должно храниться в подкаталоге 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'. Пустой строка - возвращенный, если никакие флаги не установлены или если «информация» содержит экспериментальную семантику.

set_flags(flags)¶: Установить флаги, заданные flags, и отмените установку всех остальных флагов.

add_flag(flag)¶: Установить флаг (флаги), определенный flag, не изменяя другие флаги. Чтобы добавить более одного флага одновременно, flag может быть строка более одного символ. Текущая «информация» перезаписывается независимо от того, содержит ли она экспериментальную информацию, а не флаги.

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

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

set_date(date)¶: Установить для даты доставки сообщения значение date, число с плавающей запятой, представляющее секунды с момента начала периода.

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

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

Когда MaildirMessage сущность создается на основе mboxMessage или MMDFMessage сущность, заголовки Status и X-Status опускаются, и происходит следующее преобразование

Результирующее состояние	`mboxMessage` or `MMDFMessage` состояние
«cur» подкаталог	O флаг
F флаг	F флаг
R флаг	A флаг
S флаг	R флаг
T флаг	D флаг

При создании MaildirMessage сущность на основе MHMessage сущность происходит следующее преобразование:

Результирующее состояние	`MHMessage` состояние
«cur» подкаталог	«unseen» последовательность
«cur» подкаталог and 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 хранятся вместе в одном файле. Адрес конверта отправителя и время доставки, как правило, хранится в начале линии «От» этого, используемый, чтобы указать на начало сообщения, хотя есть значительная вариация в точном формате этих данных среди mbox внедрений. Флаги, которые указывают состояние сообщения, например, считано или помечено как важное, обычно хранятся в заголовках Status и X-Status.

Обычные флаги для сообщений mbox:

Флаг	Значение	Объяснение
R	Read	Читать
O	Old	Ранее обнаружен MUA
D	Deleted	Помечено для последующего удаления
F	Flagged	Помечено как важное
A	Answered	Ответил на

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

mboxMessage сущности предлагаем следующие методы:

get_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 сущность, строка «От» генерируется на основе даты поставки MaildirMessage сущность, и происходит следующее преобразование

Результирующее состояние	`MaildirMessage` состояние
R флаг	S флаг
O флаг	«cur» подкаталог
D флаг	T флаг
F флаг	F флаг
A флаг	R флаг

При создании mboxMessage сущность на основе MHMessage сущность происходит следующее преобразование:

Результирующее состояние	`MHMessage` состояние
R флаг and O флаг	не «unseen» последовательность
O флаг	«unseen» последовательность
F флаг	«flagged» последовательность
A флаг	«replied» последовательность

При создании mboxMessage сущность на основе BabylMessage сущность происходит следующее преобразование:

Результирующее состояние	`BabylMessage` состояние
R флаг и O флаг	не «unseen» метка
O флаг	«unseen» метка
D флаг	«deleted» метка
A флаг	«answered» метка

Когда Message сущность создается на основе 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» последовательность	no R флаг
«replied» последовательность	A флаг
«flagged» последовательность	F флаг

При создании MHMessage сущность на основе BabylMessage сущность происходит следующее преобразование:

Результирующее состояние	`BabylMessage` состояние
«unseen» последовательность	«unseen» метка
«replied» последовательность	«answered» метка

`BabylMessage`¶

class mailbox.BabylMessage(message=None)¶

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

Некоторые метки сообщений, называемые attributes, определяются соглашением как имеющие особые значения. Ниже перечислены атрибуты

Метка	Объяснение
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 сохраняются с адресом отправителя и датой доставки в начальной строке, начинающейся с «От». Аналогично флаги, которые указывают состояние сообщения, обычно сохраняются в заголовках Status и X-Status.

Обычные флаги для сообщений MMDF идентичны флагам сообщения mbox и являются следующими

Флаг	Значение	Объяснение
R	Read	Читать
O	Old	Ранее обнаружен MUA
D	Deleted	Помечено для последующего удаления
F	Flagged	Помечено как важное
A	Answered	Ответил на

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

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

get_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 сущность, строка «От» генерируется на основе даты поставки 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']       # Возможно, 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                # Сообщение неправильно сформировано. Просто оставить.

    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]

            # Перед удалением оригинала необходимо записать копию на диск. Если происходит
            # сбой, вы можете дублировать сообщение, но это лучше, чем полностью потерять
            # сообщение.
            box.lock()
            box.add(message)
            box.flush()
            box.unlock()

            # Удалить исходное сообщение
            inbox.lock()
            inbox.discard(key)
            inbox.flush()
            inbox.unlock()
            break               # Найдено место назначения, так что перестань искать.

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

`mailbox` — Манипулирование почтовыми ящиками в различных форматах¶

Объекты `Mailbox`¶

`Maildir`¶

`mbox`¶

`MH`¶

`Babyl`¶

`MMDF`¶

Объекты `Message`¶

`MaildirMessage`¶

`mboxMessage`¶

`MHMessage`¶

`BabylMessage`¶

`MMDFMessage`¶

Исключения¶

Примеры¶

Содержание

Предыдущий раздел

Следующий раздел

Эта страница

mailbox — Манипулирование почтовыми ящиками в различных форматах¶

Объекты Mailbox¶

Объекты Message¶

Исключения¶

Примеры¶

`mailbox` — Манипулирование почтовыми ящиками в различных форматах¶

Объекты `Mailbox`¶

Объекты `Message`¶