mailbox.md
1> **Источник:** https://python-all.ru/3.16/library/mailbox.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `mailbox` – Управление почтовыми ящиками в различных форматах89**Исходный код:** [Lib/mailbox.py](https://python-all.ru/src/main/Lib/mailbox.py)1011---1213Этот модуль определяет два класса: [`Mailbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox) и [`Message`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Message) для доступа к почтовым ящикам на диске и управления ими, а также для работы с содержащимися в них сообщениями. `Mailbox` предоставляет словареподобное отображение ключей на сообщения. `Message` расширяет класс [`Message`](https://python-all.ru/3.16/library/email.compat32-message.html#email.message.Message) из модуля [`email.message`](https://python-all.ru/3.16/library/email.message.html#module-email.message), добавляя формат-специфичное состояние и поведение. Поддерживаемые форматы почтовых ящиков: Maildir, mbox, MH, Babyl и MMDF.1415> **См. также**16>17> **Модуль [`email`](https://python-all.ru/3.16/library/email.html#module-email)**18>19> Представление сообщений и управление ими.2021## `Mailbox` объекты2223#### `class mailbox.Mailbox`2425Почтовый ящик, который можно просматривать и изменять.2627Класс `Mailbox` определяет интерфейс и не предназначен для создания экземпляров. Вместо этого следует наследовать формат-специфичные подклассы от `Mailbox`, а код должен создавать экземпляры конкретного подкласса.2829Интерфейс `Mailbox` напоминает словарь: небольшие ключи соответствуют сообщениям. Ключи выдаются экземпляром `Mailbox`, с которым они будут использоваться, и имеют смысл только для этого экземпляра `Mailbox`. Ключ продолжает идентифицировать сообщение, даже если соответствующее сообщение изменяется, например, заменяется другим сообщением.3031Сообщения можно добавлять в экземпляр `Mailbox` с помощью метода [`add()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox.add) (подобного set) и удалять с помощью инструкции `del` или методов [`remove()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox.remove) и [`discard()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox.discard) (также подобных set).3233Семантика интерфейса `Mailbox` отличается от семантики словаря в некоторых важных аспектах. При каждом запросе сообщения на основе текущего состояния почтового ящика создаётся новое представление (обычно экземпляр [`Message`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Message)). Аналогично, при добавлении сообщения в экземпляр `Mailbox` содержимое переданного представления сообщения копируется. Ни в одном из случаев экземпляр `Mailbox` не сохраняет ссылку на представление сообщения.3435По умолчанию `Mailbox` [итератор](https://python-all.ru/3.16/glossary.html#term-iterator) выполняет итерацию по представлениям сообщений, а не по ключам, как это делает итератор [`dictionary`](https://python-all.ru/3.16/library/stdtypes.html#dict) по умолчанию. Более того, изменение почтового ящика во время итерации безопасно и имеет чётко определённое поведение. Сообщения, добавленные в почтовый ящик после создания итератора, не будут видны итератору. Сообщения, удалённые из почтового ящика до того, как итератор их вернёт, будут молча пропущены, хотя использование ключа от итератора может привести к исключению [`KeyError`](https://python-all.ru/3.16/library/exceptions.html#KeyError), если соответствующее сообщение впоследствии будет удалено.3637> **Предупреждение**38>39> Будьте очень осторожны при изменении почтовых ящиков, которые могут одновременно изменяться другим процессом. Самый безопасный формат почтового ящика для таких задач – [`Maildir`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Maildir); старайтесь избегать использования однофайловых форматов, таких как [`mbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.mbox), для одновременной записи. Если вы изменяете почтовый ящик, вы *должны* заблокировать его, вызвав методы [`lock()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox.lock) и [`unlock()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox.unlock) *перед* чтением любых сообщений в файле или внесением любых изменений (добавлением или удалением сообщения). Неблокировка почтового ящика чревата потерей сообщений или повреждением всего почтового ящика.4041Класс `Mailbox` поддерживает оператор [`with`](https://python-all.ru/3.16/reference/compound_stmts.html#with). При использовании в качестве контекстного менеджера `Mailbox` вызывает [`lock()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox.lock) при входе в контекст, возвращает объект почтового ящика в качестве контекстного объекта, а при выходе из контекста вызывает [`close()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox.close), тем самым снимая блокировку.4243Изменено в версии 3.15: Добавлена поддержка оператора [`with`](https://python-all.ru/3.16/reference/compound_stmts.html#with).4445Экземпляры `Mailbox` имеют следующие методы:4647#### `add(message)`4849Добавляет *сообщение* в почтовый ящик и возвращает ключ, который был ему присвоен.5051Параметр *message* может быть экземпляром [`Message`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Message), экземпляром [`email.message.Message`](https://python-all.ru/3.16/library/email.compat32-message.html#email.message.Message), строкой, байтовой строкой или файлоподобным объектом (который должен быть открыт в двоичном режиме). Если *message* является экземпляром соответствующего формат-специфичного подкласса `Message` (например, если это экземпляр [`mboxMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.mboxMessage), а это экземпляр [`mbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.mbox)), используется его формат-специфичная информация. В противном случае используются разумные значения по умолчанию для формат-специфичной информации.5253Изменено в версии 3.2: Добавлена поддержка двоичного ввода.5455#### `remove(key)`5657#### `__delitem__(key)`5859#### `discard(key)`6061Удаляет сообщение, соответствующее *ключу*, из почтового ящика.6263Если такого сообщения не существует, возникает исключение [`KeyError`](https://python-all.ru/3.16/library/exceptions.html#KeyError), если метод был вызван как `remove()` или `__delitem__()`, но исключение не возникает, если метод был вызван как `discard()`. Поведение `discard()` может быть предпочтительнее, если базовый формат почтового ящика поддерживает одновременное изменение другими процессами.6465#### `__setitem__(key, message)`6667Заменяет сообщение, соответствующее *ключу*, на *сообщение*. Возникает исключение [`KeyError`](https://python-all.ru/3.16/library/exceptions.html#KeyError), если *ключу* ещё не соответствует ни одно сообщение.6869Как и в случае с [`add()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox.add), параметр *message* может быть экземпляром [`Message`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Message), экземпляром [`email.message.Message`](https://python-all.ru/3.16/library/email.compat32-message.html#email.message.Message), строкой, байтовой строкой или файлоподобным объектом (который должен быть открыт в двоичном режиме). Если *message* является экземпляром соответствующего формат-специфичного подкласса `Message` (например, если это экземпляр [`mboxMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.mboxMessage), а это экземпляр [`mbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.mbox)), используется его формат-специфичная информация. В противном случае формат-специфичная информация сообщения, которое в данный момент соответствует *ключу*, остаётся неизменной.7071#### `iterkeys()`7273Возвращает [итератор](https://python-all.ru/3.16/glossary.html#term-iterator) по всем ключам7475#### `keys()`7677То же, что и [`iterkeys()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox.iterkeys), за исключением того, что возвращается [`list`](https://python-all.ru/3.16/library/stdtypes.html#list) вместо [итератора](https://python-all.ru/3.16/glossary.html#term-iterator)7879#### `itervalues()`8081#### `__iter__()`8283Возвращает [итератор](https://python-all.ru/3.16/glossary.html#term-iterator) по представлениям всех сообщений. Сообщения представлены в виде экземпляров соответствующего формат-специфичного подкласса [`Message`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Message), если только при инициализации экземпляра `Mailbox` не была указана пользовательская фабрика сообщений.8485> **Примечание**86>87> Поведение `__iter__()` отличается от поведения словарей, которые перебирают ключи.8889#### `values()`9091То же, что и [`itervalues()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox.itervalues), за исключением того, что возвращается [`list`](https://python-all.ru/3.16/library/stdtypes.html#list) вместо [итератора](https://python-all.ru/3.16/glossary.html#term-iterator)9293#### `iteritems()`9495Возвращает [итератор](https://python-all.ru/3.16/glossary.html#term-iterator) по парам (*ключ*, *сообщение*), где *ключ* – это ключ, а *сообщение* – представление сообщения. Сообщения представлены в виде экземпляров соответствующего подкласса [`Message`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Message), если только при инициализации экземпляра `Mailbox` не была указана пользовательская фабрика сообщений.9697#### `items()`9899То же, что и [`iteritems()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox.iteritems), за исключением того, что возвращается [`list`](https://python-all.ru/3.16/library/stdtypes.html#list) пар вместо [итератора](https://python-all.ru/3.16/glossary.html#term-iterator) пар.100101#### `get(key, default=None)`102103#### `__getitem__(key)`104105Возвращает представление сообщения, соответствующего *ключу*. Если такого сообщения нет, *default* возвращается, если метод был вызван как `get()`, и вызывается исключение [`KeyError`](https://python-all.ru/3.16/library/exceptions.html#KeyError), если метод был вызван как `__getitem__()`. Сообщение представляется в виде экземпляра соответствующего подкласса [`Message`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Message), если только при инициализации экземпляра `Mailbox` не была указана пользовательская фабрика сообщений.106107#### `get_message(key)`108109Возвращает представление сообщения, соответствующего *ключу*, в виде экземпляра соответствующего подкласса [`Message`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Message), или вызывает исключение [`KeyError`](https://python-all.ru/3.16/library/exceptions.html#KeyError), если такого сообщения нет.110111#### `get_bytes(key)`112113Возвращает байтовое представление сообщения, соответствующего *ключу*, или вызывает исключение [`KeyError`](https://python-all.ru/3.16/library/exceptions.html#KeyError), если такого сообщения нет.114115Добавлено в версии 3.2.116117#### `get_string(key)`118119Возвращает строковое представление сообщения, соответствующего *ключу*, или вызывает исключение [`KeyError`](https://python-all.ru/3.16/library/exceptions.html#KeyError), если такого сообщения нет. Сообщение обрабатывается через [`email.message.Message`](https://python-all.ru/3.16/library/email.compat32-message.html#email.message.Message) для преобразования в 7-битное чистое представление.120121#### `get_file(key)`122123Возвращает [файлоподобное](https://python-all.ru/3.16/glossary.html#term-file-like-object) представление сообщения, соответствующего *ключу*, или вызывает исключение [`KeyError`](https://python-all.ru/3.16/library/exceptions.html#KeyError), если такого сообщения нет. Файлоподобный объект ведёт себя так, как если бы он был открыт в двоичном режиме. Этот файл следует закрыть, когда он больше не нужен.124125Изменено в версии 3.2: Объект файла теперь действительно является [двоичным файлом](https://python-all.ru/3.16/glossary.html#term-binary-file); ранее он ошибочно возвращался в текстовом режиме. Кроме того, [файлоподобный объект](https://python-all.ru/3.16/glossary.html#term-file-like-object) теперь поддерживает протокол [менеджера контекста](https://python-all.ru/3.16/glossary.html#term-context-manager): можно использовать оператор [`with`](https://python-all.ru/3.16/reference/compound_stmts.html#with) для автоматического закрытия.126127> **Примечание**128>129> В отличие от других представлений сообщений, [файлоподобные](https://python-all.ru/3.16/glossary.html#term-file-like-object) представления не обязательно независимы от экземпляра `Mailbox`, который их создал, или от базового почтового ящика. Более подробная документация предоставляется каждым подклассом.130131#### `__contains__(key)`132133Возвращает `True`, если *ключ* соответствует сообщению, и `False` в противном случае.134135#### `__len__()`136137Возвращает количество сообщений в почтовом ящике.138139#### `clear()`140141Удаляет все сообщения из почтового ящика.142143#### `pop(key, default=None)`144145Возвращает представление сообщения, соответствующего *ключу*, и удаляет сообщение. Если такого сообщения нет, возвращает *default*. Сообщение представляется в виде экземпляра соответствующего подкласса [`Message`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Message), если только при инициализации экземпляра `Mailbox` не была указана пользовательская фабрика сообщений.146147#### `popitem()`148149Возвращает произвольную пару (*ключ*, *сообщение*), где *ключ* – это ключ, а *сообщение* – представление сообщения, и удаляет соответствующее сообщение. Если почтовый ящик пуст, вызывает исключение [`KeyError`](https://python-all.ru/3.16/library/exceptions.html#KeyError). Сообщение представляется в виде экземпляра соответствующего подкласса [`Message`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Message), если только при инициализации экземпляра `Mailbox` не была указана пользовательская фабрика сообщений.150151#### `update(arg)`152153Параметр *arg* должен быть отображением *ключ* → *сообщение* или итерируемым объектом из пар (*ключ*, *сообщение*). Обновляет почтовый ящик так, что для каждой заданной пары *ключ* и *сообщение* сообщение, соответствующее *ключу*, устанавливается в *сообщение* как если бы с помощью [`__setitem__()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox.__setitem__). Как и в случае с `__setitem__()`, каждый *ключ* уже должен соответствовать сообщению в почтовом ящике, иначе будет вызвано исключение [`KeyError`](https://python-all.ru/3.16/library/exceptions.html#KeyError), поэтому в общем случае неправильно, чтобы *arg* был экземпляром `Mailbox`.154155> **Примечание**156>157> В отличие от словарей, именованные аргументы не поддерживаются.158159#### `flush()`160161Записывает все ожидающие изменения в файловую систему. Для некоторых подклассов `Mailbox` изменения всегда записываются сразу, и `flush()` ничего не делает, но всё же стоит выработать привычку вызывать этот метод.162163#### `lock()`164165Устанавливает исключительную рекомендательную блокировку на почтовый ящик, чтобы другие процессы знали, что его не следует изменять. Если блокировка недоступна, возбуждается исключение [`ExternalClashError`](https://python-all.ru/3.16/library/mailbox.html#mailbox.ExternalClashError). Конкретные механизмы блокировки зависят от формата почтового ящика. Перед любыми изменениями содержимого следует *всегда* блокировать почтовый ящик.166167#### `unlock()`168169Освобождает блокировку почтового ящика, если она установлена.170171#### `close()`172173Сбрасывает почтовый ящик, при необходимости снимает блокировку и закрывает все открытые файлы. Для некоторых подклассов `Mailbox` этот метод ничего не делает.174175### `Maildir` объекты176177#### `class mailbox.Maildir(dirname, factory=None, create=True)`178179Подкласс [`Mailbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox) для почтовых ящиков в формате Maildir. Параметр *factory* – это вызываемый объект, который принимает файлоподобное представление сообщения (ведущее себя как открытое в бинарном режиме) и возвращает пользовательское представление. Если *factory* равно `None`, в качестве представления сообщения по умолчанию используется [`MaildirMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage). Если *create* равно `True`, почтовый ящик создаётся, если он не существует.180181Если *create* равно `True` и путь *dirname* существует, он будет рассматриваться как существующий maildir без попытки проверки структуры его каталогов.182183По историческим причинам *dirname* назван так, а не *path*.184185Maildir – это почтовый формат на основе каталогов, разработанный для агента передачи почты qmail и ныне широко поддерживаемый другими программами. Сообщения в почтовом ящике Maildir хранятся в отдельных файлах в общей структуре каталогов. Такая архитектура позволяет нескольким независимым программам получать доступ и изменять почтовые ящики Maildir без повреждения данных, поэтому файловая блокировка не требуется.186187Почтовые ящики Maildir содержат три подкаталога: `tmp`, `new` и `cur`. Сообщения создаются в подкаталоге `tmp`, а затем перемещаются в подкаталог `new` для завершения доставки. После этого почтовый клиент может переместить сообщение в подкаталог `cur` и сохранить информацию о состоянии сообщения в специальном разделе «info», добавляемом к его имени файла.188189Также поддерживаются папки в стиле, введённом агентом передачи почты Courier. Любой подкаталог основного почтового ящика считается папкой, если первым символом в его имени является `'.'`. Имена папок представляются как `Maildir` без ведущего `'.'`. Каждая папка сама является почтовым ящиком Maildir, но не должна содержать другие папки. Вместо этого логическая вложенность указывается с помощью `'.'` для разделения уровней, например, «Archived.2005.07».190191#### `colon`192193Спецификация Maildir требует использования двоеточия (`':'`) в некоторых именах файлов сообщений. Однако некоторые операционные системы не допускают этот символ в именах файлов. Если вы хотите использовать формат, подобный Maildir, в такой операционной системе, следует указать другой символ для замены. Восклицательный знак (`'!'`) – популярный выбор. Например:194195```python196import mailbox197mailbox.Maildir.colon = '!'198```199200Атрибут `colon` также может быть установлен для каждого экземпляра отдельно.201202Изменено в версии 3.13: `Maildir` теперь игнорирует файлы, начинающиеся с точки.203204Экземпляры `Maildir` имеют все методы [`Mailbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox), а также следующие:205206#### `list_folders()`207208Возвращает список имён всех папок.209210#### `get_folder(folder)`211212Возвращает экземпляр `Maildir`, представляющий папку с именем *folder*. Если папка не существует, возбуждается исключение [`NoSuchMailboxError`](https://python-all.ru/3.16/library/mailbox.html#mailbox.NoSuchMailboxError).213214#### `add_folder(folder)`215216Создаёт папку с именем *folder* и возвращает экземпляр `Maildir`, представляющий её.217218#### `remove_folder(folder)`219220Удаляет папку с именем *folder*. Если папка содержит сообщения, будет возбуждено исключение [`NotEmptyError`](https://python-all.ru/3.16/library/mailbox.html#mailbox.NotEmptyError), и папка не будет удалена.221222#### `clean()`223224Удаляет временные файлы из почтового ящика, к которым не было обращений за последние 36 часов. Спецификация Maildir утверждает, что программы чтения почты должны делать это время от времени.225226#### `get_flags(key)`227228Возвращает в виде строки флаги, установленные для сообщения, соответствующего *key*. Это то же самое, что и `get_message(key).get_flags()`, но гораздо быстрее, поскольку не открывает файл сообщения. Используйте этот метод при переборе ключей, чтобы определить, какие сообщения стоит получить.229230Если у вас есть объект [`MaildirMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage), используйте его метод [`get_flags()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage.get_flags), поскольку изменения, внесенные методами [`set_flags()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage.set_flags), [`add_flag()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage.add_flag) и [`remove_flag()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage.remove_flag) сообщения, не отражаются здесь до вызова метода [`__setitem__()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Maildir.__setitem__) почтового ящика.231232Добавлено в версии 3.13.233234#### `set_flags(key, flags)`235236Для сообщения, соответствующего *key*, установить флаги, указанные в *flags*, и сбросить все остальные. Вызов `some_mailbox.set_flags(key, flags)` аналогичен237238```python239one_message = some_mailbox.get_message(key)240one_message.set_flags(flags)241some_mailbox[key] = one_message242```243244но быстрее, поскольку не открывает файл сообщения.245246Если у вас есть объект [`MaildirMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage), используйте его метод [`set_flags()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage.set_flags), поскольку изменения, внесенные этим методом почтового ящика, не будут видны методу объекта сообщения, [`get_flags()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage.get_flags).247248Добавлено в версии 3.13.249250#### `add_flag(key, flag)`251252Для сообщения, соответствующего *key*, установить флаги, указанные в *flag*, не изменяя другие флаги. Чтобы добавить более одного флага за раз, *flag* может быть строкой из более чем одного символа.253254Соображения по использованию этого метода по сравнению с методом [`add_flag()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage.add_flag) объекта сообщения аналогичны таковым для [`set_flags()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Maildir.set_flags); см. обсуждение там.255256Добавлено в версии 3.13.257258#### `remove_flag(key, flag)`259260Для сообщения, соответствующего *key*, сбросить флаги, указанные в *flag*, не изменяя другие флаги. Чтобы удалить более одного флага за раз, *flag* может быть строкой из более чем одного символа.261262Соображения по использованию этого метода по сравнению с методом [`remove_flag()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage.remove_flag) объекта сообщения аналогичны таковым для [`set_flags()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Maildir.set_flags); см. обсуждение там.263264Добавлено в версии 3.13.265266#### `get_info(key)`267268Возвращает строку, содержащую информацию для сообщения, соответствующего *key*. Это то же самое, что и `get_message(key).get_info()`, но гораздо быстрее, поскольку не открывает файл сообщения. Используйте этот метод при переборе ключей, чтобы определить, какие сообщения стоит получить.269270Если у вас есть объект [`MaildirMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage), используйте его метод [`get_info()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage.get_info), поскольку изменения, внесенные методом [`set_info()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage.set_info) сообщения, не отражаются здесь до вызова метода [`__setitem__()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Maildir.__setitem__) почтового ящика.271272Добавлено в версии 3.13.273274#### `set_info(key, info)`275276Устанавливает информацию сообщения, соответствующего *key*, в *info*. Вызов `some_mailbox.set_info(key, flags)` аналогичен277278```python279one_message = some_mailbox.get_message(key)280one_message.set_info(info)281some_mailbox[key] = one_message282```283284но быстрее, поскольку не открывает файл сообщения.285286Если у вас есть объект [`MaildirMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage), используйте его метод [`set_info()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage.set_info), поскольку изменения, внесенные этим методом почтового ящика, не будут видны методу объекта сообщения, [`get_info()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage.get_info).287288Добавлено в версии 3.13.289290Некоторые методы [`Mailbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox), реализованные в `Maildir`, заслуживают особых замечаний:291292#### `add(message)`293294#### `__setitem__(key, message)`295296#### `update(arg)`297298> **Предупреждение**299>300> Эти методы генерируют уникальные имена файлов на основе идентификатора текущего процесса. При использовании нескольких потоков возможны незамеченные конфликты имен, которые могут привести к повреждению почтового ящика, если потоки не скоординированы, чтобы избежать одновременного использования этих методов для управления одним и тем же почтовым ящиком.301302#### `flush()`303304Все изменения в почтовых ящиках Maildir применяются немедленно, поэтому этот метод ничего не делает.305306#### `lock()`307308#### `unlock()`309310Почтовые ящики Maildir не поддерживают (и не требуют) блокировку, поэтому эти методы ничего не делают.311312#### `close()`313314Экземпляры `Maildir` не держат открытых файлов, а нижележащие почтовые ящики не поддерживают блокировку, поэтому этот метод ничего не делает.315316#### `get_file(key)`317318В зависимости от платформы может быть невозможно изменить или удалить нижележащее сообщение, пока возвращенный файл остается открытым.319320> **См. также**321>322> **[man-страница maildir из Courier](https://python-all.ru/3.16/library/mailbox.html)**323>324> Спецификация формата. Описывает общее расширение для поддержки папок.325>326> **[Использование формата maildir](https://python-all.ru/3.16/library/mailbox.html)**327>328> Заметки о Maildir от его создателя. Включают обновлённую схему создания имён и детали семантики «info».329330### `mbox` объекты331332#### `class mailbox.mbox(path, factory=None, create=True)`333334Подкласс [`Mailbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox) для почтовых ящиков в формате mbox. Параметр *factory* – это вызываемый объект, который принимает файлоподобное представление сообщения (ведущее себя как открытое в бинарном режиме) и возвращает пользовательское представление. Если *factory* равен `None`, в качестве представления сообщения по умолчанию используется [`mboxMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.mboxMessage). Если *create* равен `True`, почтовый ящик создаётся, если он не существует.335336Формат mbox – это классический формат хранения почты в системах Unix. Все сообщения в почтовом ящике mbox хранятся в одном файле, при этом начало каждого сообщения обозначается строкой, первые пять символов которой – «From ».337338Существует несколько вариаций формата mbox, призванных устранить недостатки оригинала. В целях совместимости `mbox` реализует оригинальный формат, который иногда называют *mboxo*. Это означает, что заголовок *Content-Length*, если он присутствует, игнорируется, а все вхождения «From » в начале строки в теле сообщения преобразуются в «\>From » при сохранении сообщения, хотя при чтении сообщения вхождения «\>From » обратно не преобразуются.339340Некоторые методы [`Mailbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox), реализованные в `mbox`, заслуживают особых замечаний:341342#### `get_bytes(key, from_=False)`343344Примечание: Этот метод имеет дополнительный параметр (*from\_*) по сравнению с другими классами. Первая строка записи в файле mbox – это строка Unix «From ». Если *from\_* равно False, первая строка файла опускается.345346#### `get_file(key, from_=False)`347348Использование файла после вызова [`flush()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox.flush) или [`close()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox.close) для экземпляра `mbox` может привести к непредсказуемым результатам или возбудить исключение.349350Примечание: Этот метод имеет дополнительный параметр (*from\_*) по сравнению с другими классами. Первая строка записи в файле mbox – это строка Unix «From ». Если *from\_* равно False, первая строка файла опускается.351352#### `get_string(key, from_=False)`353354Примечание: Этот метод имеет дополнительный параметр (*from\_*) по сравнению с другими классами. Первая строка записи в файле mbox – это строка Unix «From ». Если *from\_* равно False, первая строка файла опускается.355356#### `lock()`357358#### `unlock()`359360Используются три механизма блокировки: точечная блокировка (dot locking) и, если доступны, системные вызовы `flock()` и `lockf()`.361362> **См. также**363>364> **[Страница man mbox из tin](https://python-all.ru/3.16/library/mailbox.html)**365>366> Спецификация формата с подробностями о блокировке.367>368> **[Настройка Netscape Mail в Unix: почему формат Content-Length плох](https://python-all.ru/3.16/library/mailbox.html)**369>370> Аргумент в пользу использования оригинального формата mbox, а не его вариации.371>372> **[«mbox» – это семейство нескольких взаимно несовместимых форматов почтовых ящиков](https://python-all.ru/3.16/library/mailbox.html)**373>374> История вариаций mbox.375376### `MH` объекты377378#### `class mailbox.MH(path, factory=None, create=True)`379380Подкласс [`Mailbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox) для почтовых ящиков в формате MH. Параметр *factory* – это вызываемый объект, который принимает файлоподобное представление сообщения (ведущее себя как открытое в бинарном режиме) и возвращает пользовательское представление. Если *factory* равен `None`, в качестве представления сообщения по умолчанию используется [`MHMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MHMessage). Если *create* равен `True`, почтовый ящик создаётся, если он не существует.381382MH – это формат почтовых ящиков на основе каталогов, разработанный для MH Message Handling System, почтового клиента. Каждое сообщение в почтовом ящике MH находится в собственном файле. Почтовый ящик MH может содержать другие почтовые ящики MH (называемые *папками*) помимо сообщений. Папки могут быть вложены неограниченно. Почтовые ящики MH также поддерживают *последовательности* – именованные списки, используемые для логической группировки сообщений без их перемещения в подпапки. Последовательности определяются в файле с именем `.mh_sequences` в каждой папке.383384Класс `MH` управляет почтовыми ящиками MH, но не пытается эмулировать все поведения **mh**. В частности, он не изменяет и не зависит от файлов `context` и `.mh_profile`, которые используются программой **mh** для хранения своего состояния и конфигурации.385386Экземпляры `MH` имеют все методы [`Mailbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox), а также следующие:387388Изменено в версии 3.13: Добавлена поддержка папок, не содержащих файла `.mh_sequences`.389390#### `list_folders()`391392Возвращает список имён всех папок.393394#### `get_folder(folder)`395396Возвращает экземпляр `MH`, представляющий папку с именем *folder*. Исключение [`NoSuchMailboxError`](https://python-all.ru/3.16/library/mailbox.html#mailbox.NoSuchMailboxError) возникает, если папка не существует.397398#### `add_folder(folder)`399400Создаёт папку с именем *folder* и возвращает экземпляр `MH` представляющий её.401402#### `remove_folder(folder)`403404Удаляет папку с именем *folder*. Если папка содержит сообщения, будет возбуждено исключение [`NotEmptyError`](https://python-all.ru/3.16/library/mailbox.html#mailbox.NotEmptyError), и папка не будет удалена.405406#### `get_sequences()`407408Возвращает словарь, где имена последовательностей сопоставлены со списками ключей. Если последовательностей нет, возвращается пустой словарь.409410#### `set_sequences(sequences)`411412Переопределяет последовательности, существующие в почтовом ящике, на основе *sequences*, словаря, где имена сопоставлены со списками ключей, аналогично возвращаемому [`get_sequences()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MH.get_sequences).413414#### `pack()`415416Переименовывает сообщения в почтовом ящике по мере необходимости для устранения пропусков в нумерации. Записи в списке последовательностей обновляются соответствующим образом.417418> **Примечание**419>420> Ранее выданные ключи становятся недействительными в результате этой операции и не должны использоваться в дальнейшем.421422Некоторые методы [`Mailbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox), реализованные в `MH`, заслуживают особых замечаний:423424#### `remove(key)`425426#### `__delitem__(key)`427428#### `discard(key)`429430Эти методы немедленно удаляют сообщение. Соглашение MH помечать сообщение на удаление добавлением запятой к его имени не используется.431432#### `lock()`433434#### `unlock()`435436Используются три механизма блокировки: точечная блокировка и, если доступны, системные вызовы `flock()` и `lockf()`. Для почтовых ящиков MH блокировка почтового ящика означает блокировку файла `.mh_sequences` и, только на время любых операций, затрагивающих их, блокировку отдельных файлов сообщений.437438#### `get_file(key)`439440В зависимости от платформы может быть невозможно удалить базовое сообщение, пока возвращённый файл остаётся открытым.441442#### `flush()`443444Все изменения в почтовых ящиках MH применяются немедленно, поэтому этот метод ничего не делает.445446#### `close()`447448Экземпляры `MH` не держат открытых файлов, поэтому этот метод эквивалентен [`unlock()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MH.unlock).449450> **См. также**451>452> **[nmh – система обработки сообщений](https://python-all.ru/3.16/library/mailbox.html)**453>454> Домашняя страница **nmh**, обновлённой версии исходного **mh**.455>456> **[MH и nmh: электронная почта для пользователей и программистов](https://python-all.ru/3.16/library/mailbox.html)**457>458> Книга, лицензированная под GPL, о **mh** и **nmh**, с некоторой информацией о формате почтового ящика.459460### `Babyl` объекты461462#### `class mailbox.Babyl(path, factory=None, create=True)`463464Подкласс [`Mailbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox) для почтовых ящиков в формате Babyl. Параметр *factory* – это вызываемый объект, который принимает файлоподобное представление сообщения (ведущее себя как открытое в бинарном режиме) и возвращает пользовательское представление. Если *factory* равно `None`, в качестве представления сообщения по умолчанию используется [`BabylMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.BabylMessage). Если *create* равно `True`, почтовый ящик создаётся, если он не существует.465466Babyl – это однофайловый формат почтового ящика, используемый почтовым клиентом Rmail, входящим в состав Emacs. Начало сообщения обозначается строкой, содержащей два символа: Control-Подчёркивание (`'\037'`) и Control-L (`'\014'`). Конец сообщения обозначается началом следующего сообщения или, в случае последнего сообщения, строкой, содержащей символ Control-Подчёркивание (`'\037'`).467468Сообщения в почтовом ящике Babyl имеют два набора заголовков: исходные заголовки и так называемые видимые заголовки. Видимые заголовки обычно являются подмножеством исходных заголовков, которые были переформатированы или сокращены для большей привлекательности. Каждое сообщение в почтовом ящике Babyl также имеет сопутствующий список *меток* (коротких строк, которые записывают дополнительную информацию о сообщении), а список всех определённых пользователем меток, найденных в почтовом ящике, хранится в разделе параметров Babyl.469470Экземпляры `Babyl` имеют все методы [`Mailbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox), а также следующие:471472#### `get_labels()`473474Возвращает список имён всех определённых пользователем меток, используемых в почтовом ящике.475476> **Примечание**477>478> Фактические сообщения проверяются для определения того, какие метки существуют в почтовом ящике, вместо обращения к списку меток в разделе параметров Babyl, но раздел Babyl обновляется при каждом изменении почтового ящика.479480Некоторые методы [`Mailbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox), реализованные в `Babyl`, заслуживают особых замечаний:481482#### `get_file(key)`483484В почтовых ящиках Babyl заголовки сообщения не хранятся непрерывно с телом сообщения. Чтобы создать файлоподобное представление, заголовки и тело копируются вместе в экземпляр [`io.BytesIO`](https://python-all.ru/3.16/library/io.html#io.BytesIO), API которого идентичен API файла. В результате файлоподобный объект полностью независим от нижележащего почтового ящика, но не экономит память по сравнению со строковым представлением.485486#### `lock()`487488#### `unlock()`489490Используются три механизма блокировки: точечная блокировка (dot locking) и, если доступны, системные вызовы `flock()` и `lockf()`.491492> **См. также**493>494> **[Формат файлов Babyl версии 5](https://python-all.ru/3.16/library/mailbox.html)**495>496> Спецификация формата Babyl.497>498> **[Чтение почты с помощью Rmail](https://python-all.ru/3.16/library/mailbox.html)**499>500> Руководство по Rmail, содержащее некоторую информацию о семантике Babyl.501502### `MMDF` объекты503504#### `class mailbox.MMDF(path, factory=None, create=True)`505506Подкласс [`Mailbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox) для почтовых ящиков в формате MMDF. Параметр *factory* – это вызываемый объект, который принимает файлоподобное представление сообщения (ведущее себя так, как если бы оно было открыто в двоичном режиме) и возвращает пользовательское представление. Если *factory* равно `None`, в качестве представления сообщения по умолчанию используется [`MMDFMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MMDFMessage). Если *create* равно `True`, почтовый ящик создаётся, если он не существует.507508MMDF – это однофайловый формат почтового ящика, разработанный для Multichannel Memorandum Distribution Facility, агента передачи почты. Каждое сообщение имеет ту же форму, что и сообщение mbox, но обрамляется строками, содержащими четыре символа Control-A (`'\001'`). Как и в формате mbox, начало каждого сообщения обозначается строкой, первые пять символов которой – «From », но дополнительные вхождения «From » не преобразуются в «\>From » при сохранении сообщений, поскольку дополнительные строки-разделители сообщений предотвращают ошибочный приём таких вхождений за начала последующих сообщений.509510Некоторые методы [`Mailbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox), реализованные в `MMDF`, заслуживают особых замечаний:511512#### `get_bytes(key, from_=False)`513514Примечание: Этот метод имеет дополнительный параметр (*from\_*) по сравнению с другими классами. Первая строка записи в файле mbox – это строка Unix «From ». Если *from\_* равно False, первая строка файла опускается.515516#### `get_file(key, from_=False)`517518Использование файла после вызова [`flush()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox.flush) или [`close()`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox.close) для экземпляра `MMDF` может привести к непредсказуемым результатам или возбудить исключение.519520Примечание: Этот метод имеет дополнительный параметр (*from\_*) по сравнению с другими классами. Первая строка записи в файле mbox – это строка Unix «From ». Если *from\_* равно False, первая строка файла опускается.521522#### `lock()`523524#### `unlock()`525526Используются три механизма блокировки: точечная блокировка (dot locking) и, если доступны, системные вызовы `flock()` и `lockf()`.527528> **См. также**529>530> **[страница руководства mmdf из tin](https://python-all.ru/3.16/library/mailbox.html)**531>532> Спецификация формата MMDF из документации tin, программы для чтения новостей.533>534> **[MMDF](https://python-all.ru/3.16/library/mailbox.html)**535>536> Статья в Википедии, описывающая Multichannel Memorandum Distribution Facility.537538## `Message` объекты539540#### `class mailbox.Message(message=None)`541542Подкласс [`email.message`](https://python-all.ru/3.16/library/email.message.html#module-email.message) модуля [`Message`](https://python-all.ru/3.16/library/email.compat32-message.html#email.message.Message). Подклассы `mailbox.Message` добавляют состояние и поведение, специфичные для формата почтового ящика.543544Если *message* опущен, новый экземпляр создаётся в состоянии по умолчанию, пустом. Если *message* является экземпляром [`email.message.Message`](https://python-all.ru/3.16/library/email.compat32-message.html#email.message.Message), его содержимое копируется; кроме того, любая формат-специфичная информация преобразуется по мере возможности, если *message* является экземпляром `Message`. Если *message* является строкой, строкой байтов или файлом, он должен содержать сообщение, соответствующее [**RFC 5322**](https://python-all.ru/3.16/library/mailbox.html), которое читается и разбирается. Файлы должны открываться в двоичном режиме, но файлы в текстовом режиме принимаются для обратной совместимости.545546Формат-специфичные состояния и поведение, предоставляемые подклассами, различаются, но в целом поддерживаются только те свойства, которые не привязаны к конкретному почтовому ящику (хотя, предположительно, эти свойства специфичны для конкретного формата почтового ящика). Например, смещения в файлах для однофайловых форматов почтовых ящиков и имена файлов для форматов на основе каталогов не сохраняются, так как они применимы только к исходному почтовому ящику. Но такие состояния, как было ли сообщение прочитано пользователем или помечено как важное, сохраняются, поскольку они относятся к самому сообщению.547548Нет требования, чтобы экземпляры `Message` использовались для представления сообщений, полученных с помощью экземпляров [`Mailbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox). В некоторых ситуациях время и память, необходимые для создания представлений `Message`, могут оказаться неприемлемыми. Для таких случаев экземпляры `Mailbox` также предлагают строковые и файлоподобные представления, а пользовательская фабрика сообщений может быть указана при инициализации экземпляра `Mailbox`.549550### `MaildirMessage` объекты551552#### `class mailbox.MaildirMessage(message=None)`553554Сообщение с поведением, специфичным для Maildir. Параметр *message* имеет то же значение, что и в конструкторе [`Message`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Message).555556Обычно почтовый клиент перемещает все сообщения из подкаталога `new` в подкаталог `cur` после того, как пользователь впервые открывает и закрывает почтовый ящик, отмечая, что сообщения старые, независимо от того, были ли они фактически прочитаны. Каждое сообщение в `cur` имеет раздел «info», добавленный к его имени файла для хранения информации о его состоянии. (Некоторые почтовые программы могут также добавлять раздел «info» к сообщениям в `new`.) Раздел «info» может принимать одну из двух форм: он может содержать «2,» с последующим списком стандартизированных флагов (например, «2,FR») или может содержать «1,» с последующей так называемой экспериментальной информацией. Стандартные флаги для сообщений Maildir следующие:557558| Флаг | Значение | Пояснение |559| --- | --- | --- |560| D | Черновик | В процессе составления |561| F | Помечено | Помечено как важное |562| P | Передан | Переслано, отправлено повторно или возвращено |563| R | Отвечено | Получен ответ |564| S | Просмотрено | Прочитано |565| T | Удалено | Помечено для последующего удаления |566567Экземпляры `MaildirMessage` предоставляют следующие методы:568569#### `get_subdir()`570571Возвращает «new» (если сообщение должно храниться в подкаталоге `new` или «cur» (если сообщение должно храниться в подкаталоге `cur`).572573> **Примечание**574>575> Сообщение обычно перемещается из `new` в `cur` после того, как к почтовому ящику был произведён доступ, независимо от того, было ли сообщение прочитано. Сообщение `msg` было прочитано, если `"S" in msg.get_flags()` равно `True`.576577#### `set_subdir(subdir)`578579Устанавливает подкаталог, в котором должно храниться сообщение. Параметр *subdir* должен быть либо «new», либо «cur».580581#### `get_flags()`582583Возвращает строку, указывающую текущие установленные флаги. Если сообщение соответствует стандартному формату Maildir, результатом является конкатенация в алфавитном порядке нуля или одного вхождения каждого из `'D'`, `'F'`, `'P'`, `'R'`, `'S'` и `'T'`. Возвращается пустая строка, если флаги не установлены или если «info» содержит экспериментальную семантику.584585#### `set_flags(flags)`586587Устанавливает флаги, указанные *flags*, и сбрасывает все остальные.588589#### `add_flag(flag)`590591Устанавливает флаг(и), указанные *flag*, не изменяя остальные флаги. Чтобы добавить более одного флага за раз, *flag* может быть строкой из более чем одного символа. Текущий «info» перезаписывается, независимо от того, содержит ли он экспериментальную информацию вместо флагов.592593#### `remove_flag(flag)`594595Сбрасывает флаг(и), указанные в *flag*, не изменяя остальные флаги. Чтобы сбросить несколько флагов одновременно, *flag* может быть строкой из нескольких символов. Если «info» содержит экспериментальную информацию, а не флаги, текущее «info» не изменяется.596597#### `get_date()`598599Возвращает дату доставки сообщения в виде числа с плавающей запятой, представляющего количество секунд с начала эпохи.600601#### `set_date(date)`602603Устанавливает дату доставки сообщения в *date*, число с плавающей запятой, представляющее количество секунд с начала эпохи.604605#### `get_info()`606607Возвращает строку, содержащую «info» для сообщения. Это полезно для доступа к экспериментальному «info» и его изменения (т.е. не являющегося списком флагов).608609#### `set_info(info)`610611Устанавливает «info» в *info*, которое должно быть строкой.612613Когда экземпляр `MaildirMessage` создаётся на основе экземпляра [`mboxMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.mboxMessage) или [`MMDFMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MMDFMessage), заголовки *Status* и *X-Status* опускаются и происходят следующие преобразования:614615| Результирующее состояние | [`mboxMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.mboxMessage) или [`MMDFMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MMDFMessage) состояние |616| --- | --- |617| Подкаталог «cur» | Флаг O |618| Флаг F | Флаг F |619| Флаг R | Флаг A |620| Флаг S | Флаг R |621| Флаг T | Флаг D |622623Когда экземпляр `MaildirMessage` создаётся на основе экземпляра [`MHMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MHMessage), происходят следующие преобразования:624625| Результирующее состояние | Состояние [`MHMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MHMessage) |626| --- | --- |627| Подкаталог «cur» | последовательность «unseen» |628| подкаталог «cur» и флаг S | нет последовательности «unseen» |629| Флаг F | последовательность «flagged» |630| Флаг R | последовательность «replied» |631632Когда экземпляр `MaildirMessage` создаётся на основе экземпляра [`BabylMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.BabylMessage), происходят следующие преобразования:633634| Результирующее состояние | Состояние [`BabylMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.BabylMessage) |635| --- | --- |636| Подкаталог «cur» | метка «unseen» |637| подкаталог «cur» и флаг S | нет метки «unseen» |638| Флаг P | метка «forwarded» или «resent» |639| Флаг R | метка «отвечено» |640| Флаг T | метка «удалено» |641642### `mboxMessage` объекты643644#### `class mailbox.mboxMessage(message=None)`645646Сообщение с поведением, специфичным для mbox. Параметр *message* имеет тот же смысл, что и в конструкторе [`Message`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Message).647648Сообщения в почтовом ящике mbox хранятся вместе в одном файле. Адрес отправителя в конверте и время доставки обычно хранятся в строке, начинающейся с «From », которая используется для обозначения начала сообщения, хотя точный формат этих данных сильно различается в разных реализациях mbox. Флаги, указывающие состояние сообщения, например, было ли оно прочитано или помечено как важное, обычно хранятся в заголовках *Status* и *X-Status*.649650Обычные флаги для сообщений mbox:651652| Флаг | Значение | Пояснение |653| --- | --- | --- |654| R | Прочитано | Прочитано |655| O | Старое | Ранее обнаружено почтовым клиентом |656| D | Удалено | Помечено для последующего удаления |657| F | Помечено | Помечено как важное |658| A | Отвечено | Получен ответ |659660Флаги «R» и «O» хранятся в заголовке *Status*, а флаги «D», «F» и «A» – в заголовке *X-Status*. Флаги и заголовки обычно располагаются в указанном порядке.661662Экземпляры `mboxMessage` предоставляют следующие методы:663664#### `get_from()`665666Возвращает строку, представляющую строку «From », которая отмечает начало сообщения в почтовом ящике mbox. Начальное «From » и завершающий символ новой строки не включаются.667668#### `set_from(from_, time_=None)`669670Устанавливает строку «From » равной *from\_*, которая должна быть указана без начального «From » и завершающего символа новой строки. Для удобства можно указать *time\_*; она будет соответствующим образом отформатирована и добавлена к *from\_*. Если *time\_* указан, он должен быть экземпляром [`time.struct_time`](https://python-all.ru/3.16/library/time.html#time.struct_time), кортежем, подходящим для передачи в [`time.strftime()`](https://python-all.ru/3.16/library/time.html#time.strftime), или `True` (чтобы использовать [`time.gmtime()`](https://python-all.ru/3.16/library/time.html#time.gmtime)).671672#### `get_flags()`673674Возвращает строку, указывающую установленные флаги. Если сообщение соответствует стандартному формату, результатом является конкатенация в следующем порядке нуля или одного вхождения каждого из `'R'`, `'O'`, `'D'`, `'F'` и `'A'`.675676#### `set_flags(flags)`677678Устанавливает флаги, указанные в *flags*, и снимает все остальные. Параметр *flags* должен быть конкатенацией в произвольном порядке нуля или более вхождений каждого из `'R'`, `'O'`, `'D'`, `'F'` и `'A'`.679680#### `add_flag(flag)`681682Устанавливает флаг(и), указанные в *flag*, не изменяя другие флаги. Чтобы добавить более одного флага за раз, *flag* может быть строкой из более чем одного символа.683684#### `remove_flag(flag)`685686Снимает флаг(и), указанные в *flag*, не изменяя другие флаги. Чтобы удалить более одного флага за раз, *flag* может быть строкой из более чем одного символа.687688Когда экземпляр `mboxMessage` создаётся на основе экземпляра [`MaildirMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage), строка «From» генерируется на основе даты доставки экземпляра `MaildirMessage`, и происходят следующие преобразования:689690| Результирующее состояние | Состояние [`MaildirMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage) |691| --- | --- |692| Флаг R | Флаг S |693| Флаг O | Подкаталог «cur» |694| Флаг D | Флаг T |695| Флаг F | Флаг F |696| Флаг A | Флаг R |697698Когда экземпляр `mboxMessage` создаётся на основе экземпляра [`MHMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MHMessage), происходят следующие преобразования:699700| Результирующее состояние | Состояние [`MHMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MHMessage) |701| --- | --- |702| Флаг R и флаг O | нет последовательности «unseen» |703| Флаг O | последовательность «unseen» |704| Флаг F | последовательность «flagged» |705| Флаг A | последовательность «replied» |706707Когда экземпляр `mboxMessage` создаётся на основе экземпляра [`BabylMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.BabylMessage), происходят следующие преобразования:708709| Результирующее состояние | Состояние [`BabylMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.BabylMessage) |710| --- | --- |711| Флаг R и флаг O | нет метки «unseen» |712| Флаг O | метка «unseen» |713| Флаг D | метка «удалено» |714| Флаг A | метка «отвечено» |715716Когда экземпляр `mboxMessage` создаётся на основе экземпляра [`MMDFMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MMDFMessage), строка «From » копируется, и все флаги напрямую соответствуют:717718| Результирующее состояние | Состояние [`MMDFMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MMDFMessage) |719| --- | --- |720| Флаг R | Флаг R |721| Флаг O | Флаг O |722| Флаг D | Флаг D |723| Флаг F | Флаг F |724| Флаг A | Флаг A |725726### `MHMessage` объекты727728#### `class mailbox.MHMessage(message=None)`729730Сообщение с поведением, характерным для MH. Параметр *message* имеет то же значение, что и в конструкторе [`Message`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Message).731732Сообщения MH не поддерживают метки и флаги в традиционном понимании, но поддерживают последовательности – логические группировки произвольных сообщений. Некоторые почтовые программы (хотя не стандартные **mh** и **nmh**) используют последовательности примерно так же, как флаги используются в других форматах:733734| Последовательность | Пояснение |735| --- | --- |736| unseen | Не прочитано, но ранее обнаружено почтовым клиентом (MUA) |737| отвечено | Получен ответ |738| помечено | Помечено как важное |739740Экземпляры `MHMessage` предоставляют следующие методы:741742#### `get_sequences()`743744Возвращает список имен последовательностей, которые включают это сообщение.745746#### `set_sequences(sequences)`747748Устанавливает список последовательностей, которые включают это сообщение.749750#### `add_sequence(sequence)`751752Добавляет *sequence* в список последовательностей, которые включают это сообщение.753754#### `remove_sequence(sequence)`755756Удаляет *sequence* из списка последовательностей, которые включают это сообщение.757758Когда экземпляр `MHMessage` создаётся на основе экземпляра [`MaildirMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage), происходят следующие преобразования:759760| Результирующее состояние | Состояние [`MaildirMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage) |761| --- | --- |762| последовательность «unseen» | нет флага S |763| последовательность «replied» | Флаг R |764| последовательность «flagged» | Флаг F |765766Когда экземпляр `MHMessage` создается на основе экземпляра [`mboxMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.mboxMessage) или [`MMDFMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MMDFMessage), заголовки *Status* и *X-Status* опускаются и происходят следующие преобразования:767768| Результирующее состояние | [`mboxMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.mboxMessage) или [`MMDFMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MMDFMessage) состояние |769| --- | --- |770| последовательность «unseen» | нет флага R |771| последовательность «replied» | Флаг A |772| последовательность «flagged» | Флаг F |773774Когда экземпляр `MHMessage` создаётся на основе экземпляра [`BabylMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.BabylMessage), происходят следующие преобразования:775776| Результирующее состояние | Состояние [`BabylMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.BabylMessage) |777| --- | --- |778| последовательность «unseen» | метка «unseen» |779| последовательность «replied» | метка «отвечено» |780781### `BabylMessage` объекты782783#### `class mailbox.BabylMessage(message=None)`784785Сообщение с поведением, специфичным для Babyl. Параметр *message* имеет то же значение, что и в конструкторе [`Message`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Message).786787Некоторые метки сообщений, называемые *attributes*, по соглашению имеют специальное значение. Атрибуты следующие:788789| Метка | Пояснение |790| --- | --- |791| unseen | Не прочитано, но ранее обнаружено почтовым клиентом (MUA) |792| deleted | Помечено для последующего удаления |793| filed | Скопировано в другой файл или почтовый ящик |794| answered | Получен ответ |795| forwarded | Переслано |796| edited | Изменено пользователем |797| resent | Отправлено повторно |798799По умолчанию Rmail отображает только видимые заголовки. Однако класс `BabylMessage` использует исходные заголовки, поскольку они более полны. При желании к видимым заголовкам можно обратиться явно.800801Экземпляры `BabylMessage` предоставляют следующие методы:802803#### `get_labels()`804805Возвращает список меток сообщения.806807#### `set_labels(labels)`808809Устанавливает список меток сообщения равным *labels*.810811#### `add_label(label)`812813Добавляет метку *label* в список меток сообщения.814815#### `remove_label(label)`816817Удаляет метку *label* из списка меток сообщения.818819#### `get_visible()`820821Возвращает экземпляр [`Message`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Message), заголовки которого – это видимые заголовки сообщения, а тело пусто.822823#### `set_visible(visible)`824825Устанавливает видимые заголовки сообщения такими же, как заголовки из *message*. Параметр *visible* должен быть экземпляром [`Message`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Message), экземпляром [`email.message.Message`](https://python-all.ru/3.16/library/email.compat32-message.html#email.message.Message), строкой или файлоподобным объектом (который должен быть открыт в текстовом режиме).826827#### `update_visible()`828829Когда исходные заголовки экземпляра `BabylMessage` изменяются, видимые заголовки автоматически не изменяются для соответствия. Этот метод обновляет видимые заголовки следующим образом: каждый видимый заголовок с соответствующим исходным заголовком устанавливается в значение исходного заголовка, каждый видимый заголовок без соответствующего исходного заголовка удаляется, а любые из *Date*, *From*, *Reply-To*, *To*, *CC* и *Subject*, которые присутствуют в исходных заголовках, но отсутствуют в видимых заголовках, добавляются к видимым заголовкам.830831Когда экземпляр `BabylMessage` создаётся на основе экземпляра [`MaildirMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage), происходят следующие преобразования:832833| Результирующее состояние | Состояние [`MaildirMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage) |834| --- | --- |835| метка «unseen» | нет флага S |836| метка «удалено» | Флаг T |837| метка «отвечено» | Флаг R |838| Метка «forwarded» | Флаг P |839840Когда экземпляр `BabylMessage` создаётся на основе экземпляра [`mboxMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.mboxMessage) или [`MMDFMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MMDFMessage), заголовки *Status* и *X-Status* опускаются и происходят следующие преобразования:841842| Результирующее состояние | [`mboxMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.mboxMessage) или [`MMDFMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MMDFMessage) состояние |843| --- | --- |844| метка «unseen» | нет флага R |845| метка «удалено» | Флаг D |846| метка «отвечено» | Флаг A |847848Когда экземпляр `BabylMessage` создаётся на основе экземпляра [`MHMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MHMessage), происходят следующие преобразования:849850| Результирующее состояние | Состояние [`MHMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MHMessage) |851| --- | --- |852| метка «unseen» | последовательность «unseen» |853| метка «отвечено» | последовательность «replied» |854855### `MMDFMessage` объекты856857#### `class mailbox.MMDFMessage(message=None)`858859Сообщение с поведением, специфичным для MMDF. Параметр *message* имеет то же значение, что и в конструкторе [`Message`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Message).860861Как и сообщения в почтовом ящике mbox, сообщения MMDF хранятся с адресом отправителя и датой доставки в начальной строке, начинающейся с «From ». Аналогично, флаги, указывающие на состояние сообщения, обычно хранятся в заголовках *Status* и *X-Status*.862863Стандартные флаги для сообщений MMDF совпадают с флагами сообщений mbox и перечислены ниже:864865| Флаг | Значение | Пояснение |866| --- | --- | --- |867| R | Прочитано | Прочитано |868| O | Старое | Ранее обнаружено почтовым клиентом |869| D | Удалено | Помечено для последующего удаления |870| F | Помечено | Помечено как важное |871| A | Отвечено | Получен ответ |872873Флаги «R» и «O» хранятся в заголовке *Status*, а флаги «D», «F» и «A» – в заголовке *X-Status*. Флаги и заголовки обычно располагаются в указанном порядке.874875Экземпляры `MMDFMessage` предоставляют следующие методы, идентичные методам, предоставляемым [`mboxMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.mboxMessage):876877#### `get_from()`878879Возвращает строку, представляющую строку «From », которая отмечает начало сообщения в почтовом ящике mbox. Начальное «From » и завершающий символ новой строки не включаются.880881#### `set_from(from_, time_=None)`882883Устанавливает строку «From » равной *from\_*, которая должна быть указана без начального «From » и завершающего символа новой строки. Для удобства можно указать *time\_*; она будет соответствующим образом отформатирована и добавлена к *from\_*. Если *time\_* указан, он должен быть экземпляром [`time.struct_time`](https://python-all.ru/3.16/library/time.html#time.struct_time), кортежем, подходящим для передачи в [`time.strftime()`](https://python-all.ru/3.16/library/time.html#time.strftime), или `True` (чтобы использовать [`time.gmtime()`](https://python-all.ru/3.16/library/time.html#time.gmtime)).884885#### `get_flags()`886887Возвращает строку, указывающую установленные флаги. Если сообщение соответствует стандартному формату, результатом является конкатенация в следующем порядке нуля или одного вхождения каждого из `'R'`, `'O'`, `'D'`, `'F'` и `'A'`.888889#### `set_flags(flags)`890891Устанавливает флаги, указанные в *flags*, и снимает все остальные. Параметр *flags* должен быть конкатенацией в произвольном порядке нуля или более вхождений каждого из `'R'`, `'O'`, `'D'`, `'F'` и `'A'`.892893#### `add_flag(flag)`894895Устанавливает флаг(и), указанные в *flag*, не изменяя другие флаги. Чтобы добавить более одного флага за раз, *flag* может быть строкой из более чем одного символа.896897#### `remove_flag(flag)`898899Снимает флаг(и), указанные в *flag*, не изменяя другие флаги. Чтобы удалить более одного флага за раз, *flag* может быть строкой из более чем одного символа.900901Когда экземпляр `MMDFMessage` создаётся на основе экземпляра [`MaildirMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage), строка «From» генерируется на основе даты доставки экземпляра `MaildirMessage`, и происходят следующие преобразования:902903| Результирующее состояние | Состояние [`MaildirMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MaildirMessage) |904| --- | --- |905| Флаг R | Флаг S |906| Флаг O | Подкаталог «cur» |907| Флаг D | Флаг T |908| Флаг F | Флаг F |909| Флаг A | Флаг R |910911Когда экземпляр `MMDFMessage` создаётся на основе экземпляра [`MHMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MHMessage), происходят следующие преобразования:912913| Результирующее состояние | Состояние [`MHMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MHMessage) |914| --- | --- |915| Флаг R и флаг O | нет последовательности «unseen» |916| Флаг O | последовательность «unseen» |917| Флаг F | последовательность «flagged» |918| Флаг A | последовательность «replied» |919920Когда экземпляр `MMDFMessage` создаётся на основе экземпляра [`BabylMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.BabylMessage), происходят следующие преобразования:921922| Результирующее состояние | Состояние [`BabylMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.BabylMessage) |923| --- | --- |924| Флаг R и флаг O | нет метки «unseen» |925| Флаг O | метка «unseen» |926| Флаг D | метка «удалено» |927| Флаг A | метка «отвечено» |928929Когда экземпляр `MMDFMessage` создаётся на основе экземпляра [`mboxMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.mboxMessage), строка «From» копируется, и все флаги напрямую соответствуют:930931| Результирующее состояние | Состояние [`mboxMessage`](https://python-all.ru/3.16/library/mailbox.html#mailbox.mboxMessage) |932| --- | --- |933| Флаг R | Флаг R |934| Флаг O | Флаг O |935| Флаг D | Флаг D |936| Флаг F | Флаг F |937| Флаг A | Флаг A |938939## Исключения940941В модуле `mailbox` определены следующие классы исключений:942943#### `exception mailbox.Error`944945Базовый класс для всех остальных исключений модуля.946947#### `exception mailbox.NoSuchMailboxError`948949Вызывается, когда ожидается почтовый ящик, но он не найден, например, при создании экземпляра подкласса [`Mailbox`](https://python-all.ru/3.16/library/mailbox.html#mailbox.Mailbox) с несуществующим путём (и с параметром *create*, установленным в `False`) или при открытии несуществующей папки.950951#### `exception mailbox.NotEmptyError`952953Вызывается, когда почтовый ящик не пуст, но ожидается пустым, например, при удалении папки, содержащей сообщения.954955#### `exception mailbox.ExternalClashError`956957Вызывается, когда некое условие, связанное с почтовым ящиком и не зависящее от программы, не позволяет ей продолжить работу, например, при неудачной попытке получить блокировку, которую уже удерживает другая программа, или когда уникальное имя файла уже существует.958959#### `exception mailbox.FormatError`960961Вызывается, когда данные в файле не могут быть разобраны, например, когда экземпляр [`MH`](https://python-all.ru/3.16/library/mailbox.html#mailbox.MH) пытается прочитать повреждённый файл `.mh_sequences`.962963## Примеры964965Простой пример вывода тем всех сообщений в почтовом ящике, которые кажутся интересными:966967```python968import mailbox969for message in mailbox.mbox('~/mbox'):970 subject = message['subject'] # Может быть None.971 if subject and 'python' in subject.lower():972 print(subject)973```974975Чтобы скопировать все письма из почтового ящика Babyl в почтовый ящик MH, преобразуя всю форматно-специфичную информацию, которую можно преобразовать:976977```python978import mailbox979destination = mailbox.MH('~/Mail')980destination.lock()981for message in mailbox.Babyl('~/RMAIL'):982 destination.add(mailbox.MHMessage(message))983destination.flush()984destination.unlock()985```986987Этот пример сортирует письма из нескольких списков рассылки по разным почтовым ящикам, стараясь избежать повреждения писем из-за одновременного изменения другими программами, потери писем из-за прерывания программы или преждевременного завершения из-за повреждённых сообщений в почтовом ящике:988989```python990import mailbox991import email.errors992993list_names = ('python-list', 'python-dev', 'python-bugs')994995boxes = {name: mailbox.mbox('~/email/%s' % name) for name in list_names}996inbox = mailbox.Maildir('~/Maildir', factory=None)997998for key in inbox.iterkeys():999 try:1000 message = inbox[key]1001 except email.errors.MessageParseError:1002 continue # Сообщение повреждено. Просто оставьте его.10031004 for name in list_names:1005 list_id = message['list-id']1006 if list_id and name in list_id:1007 # Получить почтовый ящик для использования.1008 box = boxes[name]10091010 # Записать копию на диск перед удалением оригинала.1011 # Если произошёл сбой, возможно дублирование сообщения, но1012 # это лучше, чем полная потеря сообщения.1013 box.lock()1014 box.add(message)1015 box.flush()1016 box.unlock()10171018 # Удалить исходное сообщение1019 inbox.lock()1020 inbox.discard(key)1021 inbox.flush()1022 inbox.unlock()1023 break # Целевой получатель найден, поиск прекращён.10241025for box in boxes.itervalues():1026 box.close()1027```1028