# `mailbox` — Manipulate mailboxes in various formats

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

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

Дивись також

Модуль `email`

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

## `Mailbox` objects

class mailbox.Mailbox

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

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

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

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

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

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

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

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

  `Mailbox` instances have the following methods:

  add(message)

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

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

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

  remove(key)
  __delitem__(key)
  discard(key)

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

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

  __setitem__(key, message)

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

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

  iterkeys()

    Return an iterator over all keys

  keys()

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

  itervalues()
  __iter__()

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

    Примітка

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

  values()

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

  iteritems()

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

  items()

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

  get(key, default=None)
  __getitem__(key)

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

  get_message(key)

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

  get_bytes(key)

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

    Added in version 3.2.

  get_string(key)

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

  get_file(key)

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

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

    Примітка

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

  __contains__(key)

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

  __len__()

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

  clear()

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

  pop(key, default=None)

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

  popitem()

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

  update(arg)

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

    Примітка

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

  flush()

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

  lock()

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

  unlock()

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

  close()

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

### `Maildir` objects

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

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

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

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

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

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

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

  colon

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

        import mailbox
        mailbox.Maildir.colon = '!'

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

  Змінено в версії 3.13: `Maildir` now ignores files with a leading dot.

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

  list_folders()

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

  get_folder(folder)

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

  add_folder(folder)

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

  remove_folder(folder)

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

  clean()

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

  get_flags(key)

    Return as a string the flags that are set on the message corresponding to key. This is the same as `get_message(key).get_flags()` but much faster, because it does not open the message file. Use this method when iterating over the keys to determine which messages are interesting to get.

    If you do have a `MaildirMessage` object, use its `get_flags()` method instead, because changes made by the message’s `set_flags()`, `add_flag()` and `remove_flag()` methods are not reflected here until the mailbox’s `__setitem__()` method is called.

    Added in version 3.13.

  set_flags(key, flags)

    On the message corresponding to key, set the flags specified by flags and unset all others. Calling `some_mailbox.set_flags(key, flags)` is similar to

        one_message = some_mailbox.get_message(key)
        one_message.set_flags(flags)
        some_mailbox[key] = one_message

    but faster, because it does not open the message file.

    If you do have a `MaildirMessage` object, use its `set_flags()` method instead, because changes made with this mailbox method will not be visible to the message object’s method, `get_flags()`.

    Added in version 3.13.

  add_flag(key, flag)

    On the message corresponding to key, set the flags specified by flag without changing other flags. To add more than one flag at a time, flag may be a string of more than one character.

    Considerations for using this method versus the message object’s `add_flag()` method are similar to those for `set_flags()`; see the discussion there.

    Added in version 3.13.

  remove_flag(key, flag)

    On the message corresponding to key, unset the flags specified by flag without changing other flags. To remove more than one flag at a time, flag may be a string of more than one character.

    Considerations for using this method versus the message object’s `remove_flag()` method are similar to those for `set_flags()`; see the discussion there.

    Added in version 3.13.

  get_info(key)

    Return a string containing the info for the message corresponding to key. This is the same as `get_message(key).get_info()` but much faster, because it does not open the message file. Use this method when iterating over the keys to determine which messages are interesting to get.

    If you do have a `MaildirMessage` object, use its `get_info()` method instead, because changes made by the message’s `set_info()` method are not reflected here until the mailbox’s `__setitem__()` method is called.

    Added in version 3.13.

  set_info(key, info)

    Set the info of the message corresponding to key to info. Calling `some_mailbox.set_info(key, flags)` is similar to

        one_message = some_mailbox.get_message(key)
        one_message.set_info(info)
        some_mailbox[key] = one_message

    but faster, because it does not open the message file.

    If you do have a `MaildirMessage` object, use its `set_info()` method instead, because changes made with this mailbox method will not be visible to the message object’s method, `get_info()`.

    Added in version 3.13.

  Some `Mailbox` methods implemented by `Maildir` deserve special remarks:

  add(message)
  __setitem__(key, message)
  update(arg)

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

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

  flush()

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

  lock()
  unlock()

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

  close()

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

  get_file(key)

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

Дивись також

maildir man page from Courier

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

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

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

### `mbox` objects

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

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

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

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

  Some `Mailbox` methods implemented by `mbox` deserve special remarks:

  get_file(key)

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

  lock()
  unlock()

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

Дивись також

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

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

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

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

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

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

### `MH` objects

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

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

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

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

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

  Змінено в версії 3.13: Supported folders that don’t contain a `.mh_sequences` file.

  list_folders()

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

  get_folder(folder)

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

  add_folder(folder)

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

  remove_folder(folder)

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

  get_sequences()

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

  set_sequences(sequences)

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

  pack()

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

    Примітка

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

  Some `Mailbox` methods implemented by `MH` deserve special remarks:

  remove(key)
  __delitem__(key)
  discard(key)

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

  lock()
  unlock()

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

  get_file(key)

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

  flush()

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

  close()

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

Дивись також

nmh - Message Handling System

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

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

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

### `Babyl` objects

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

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

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

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

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

  get_labels()

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

    Примітка

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

  Some `Mailbox` methods implemented by `Babyl` deserve special remarks:

  get_file(key)

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

  lock()
  unlock()

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

Дивись також

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

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

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

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

### `MMDF` objects

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

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

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

  Some `Mailbox` methods implemented by `MMDF` deserve special remarks:

  get_file(key)

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

  lock()
  unlock()

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

Дивись також

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

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

MMDF

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

## `Message` objects

class mailbox.Message(message=None)

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

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

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

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

### `MaildirMessage` objects

class mailbox.MaildirMessage(message=None)

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

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

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

  `MaildirMessage` instances offer the following methods:

  get_subdir()

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

    Примітка

    A message is typically moved from `new` to `cur` after its mailbox has been accessed, whether or not the message has been read. A message `msg` has been read if `"S" in msg.get_flags()` is `True`.

  set_subdir(subdir)

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

  get_flags()

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

  set_flags(flags)

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

  add_flag(flag)

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

  remove_flag(flag)

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

  get_date()

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

  set_date(date)

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

  get_info()

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

  set_info(info)

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

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

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

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

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

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

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

### `mboxMessage` objects

class mailbox.mboxMessage(message=None)

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

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

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

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

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

  `mboxMessage` instances offer the following methods:

  get_from()

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

  set_from(from_, time_=None)

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

  get_flags()

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

  set_flags(flags)

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

  add_flag(flag)

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

  remove_flag(flag)

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

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

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

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

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

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

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

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

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

### `MHMessage` objects

class mailbox.MHMessage(message=None)

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

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

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

  `MHMessage` instances offer the following methods:

  get_sequences()

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

  set_sequences(sequences)

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

  add_sequence(sequence)

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

  remove_sequence(sequence)

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

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

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

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

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

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

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

### `BabylMessage` objects

class mailbox.BabylMessage(message=None)

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

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

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

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

  `BabylMessage` instances offer the following methods:

  get_labels()

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

  set_labels(labels)

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

  add_label(label)

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

  remove_label(label)

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

  get_visible()

    Return a `Message` instance whose headers are the message’s visible headers and whose body is empty.

  set_visible(visible)

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

  update_visible()

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

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

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

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

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

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

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

### `MMDFMessage` objects

class mailbox.MMDFMessage(message=None)

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

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

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

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

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

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

  get_from()

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

  set_from(from_, time_=None)

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

  get_flags()

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

  set_flags(flags)

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

  add_flag(flag)

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

  remove_flag(flag)

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

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

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

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

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

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

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

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

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

## Винятки

The following exception classes are defined in the `mailbox` module:

exception mailbox.Error

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

exception mailbox.NoSuchMailboxError

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

exception mailbox.NotEmptyError

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

exception mailbox.ExternalClashError

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

exception mailbox.FormatError

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

## Приклади

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

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

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

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

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

    import mailbox
    import email.errors

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

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

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

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

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

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

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