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

Kod źródłowy: Lib/mailbox.py


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

Zobacz także

Modul email

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

Mailbox объекты

class mailbox.Mailbox

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

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

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

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

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

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

Ostrzeżenie

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

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

add(message)

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

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

Zmienione w wersji 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()

Вернуть итератор по всем ключам

keys()

То же, что и iterkeys(), за исключением того, что возвращается list, а не iterator

itervalues()
__iter__()

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

Informacja

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

values()

То же, что itervalues(), за исключением того, что возвращается list, а не iterator

iteritems()

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

items()

То же, что и iteritems(), за исключением того, что возвращается list пар, а не iterator пар.

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

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

get_message(key)

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

get_bytes(key)

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

Dodane w wersji 3.2.

get_string(key)

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

get_file(key)

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

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

Informacja

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

__contains__(key)

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

__len__()

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

clear()

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

pop(key, default=None)

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

popitem()

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

update(arg)

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

Informacja

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

flush()

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

lock()

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

unlock()

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

close()

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

Maildir объекты

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

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

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

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

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

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

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

colon

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

import mailbox
mailbox.Maildir.colon = '!'

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

Zmienione w wersji 3.13: Maildir теперь игнорирует файлы с точкой в ​​начале.

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

list_folders()

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

get_folder(folder)

Возвращает экземпляр Maildir, представляющий папку с именем folder. Исключение NoSuchMailboxError возникает, если папка не существует.

add_folder(folder)

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

remove_folder(folder)

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

clean()

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

get_flags(key)

Возвращает в виде строки флаги, установленные в сообщении, соответствующем key. Это то же самое, что и get_message(key).get_flags(), но гораздо быстрее, поскольку файл сообщения не открывается. Используйте этот метод при переборе ключей, чтобы определить, какие сообщения интересно получить.

Если у вас есть объект MaildirMessage, используйте вместо него его метод get_flags(), поскольку изменения, внесенные set_flags(), Методы add_flag() и remove_flag() не отображаются здесь до тех пор, пока не будет вызван метод почтового ящика __setitem__().

Dodane w wersji 3.13.

set_flags(key, flags)

В сообщении, соответствующем key, установите флаги, указанные flags, и отключите все остальные. Вызов some_mailbox.set_flags(key, flags) аналогичен:

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

но быстрее, потому что файл сообщения не открывается.

Если у вас есть объект MaildirMessage, используйте вместо него его метод set_flags(), поскольку изменения, сделанные с помощью этого метода почтового ящика, не будут видны методу объекта сообщения, get_flags().

Dodane w wersji 3.13.

add_flag(key, flag)

В сообщении, соответствующем key, установите флаги, указанные flag, не меняя другие флаги. Чтобы добавить более одного флага одновременно, flag может быть строкой, состоящей из более чем одного символа.

Рекомендации по использованию этого метода по сравнению с методом add_flag() объекта сообщения аналогичны таковым для set_flags(); посмотри обсуждение там.

Dodane w wersji 3.13.

remove_flag(key, flag)

В сообщении, соответствующем key, снимите флаги, указанные flag, не меняя другие флаги. Чтобы удалить более одного флага одновременно, flag может быть строкой, состоящей из более чем одного символа.

Рекомендации по использованию этого метода по сравнению с методом remove_flag() объекта сообщения аналогичны тем, которые используются для set_flags(); посмотри обсуждение там.

Dodane w wersji 3.13.

get_info(key)

Возвращает строку, содержащую информацию о сообщении, соответствующем key. Это то же самое, что и get_message(key).get_info(), но гораздо быстрее, поскольку файл сообщения не открывается. Используйте этот метод при переборе ключей, чтобы определить, какие сообщения интересно получить.

Если у вас есть объект MaildirMessage, используйте вместо него его метод get_info(), поскольку изменения, внесенные методом set_info() сообщения, не отражаются здесь до тех пор, пока почтовый ящик не будет Вызывается метод __setitem__().

Dodane w wersji 3.13.

set_info(key, info)

Установите для информации сообщения, соответствующего key, значение info. Вызов some_mailbox.set_info(key, flags) аналогичен:

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

но быстрее, потому что файл сообщения не открывается.

Если у вас есть объект MaildirMessage, используйте вместо него его метод set_info(), поскольку изменения, сделанные с помощью этого метода почтового ящика, не будут видны методу объекта сообщения, get_info().

Dodane w wersji 3.13.

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

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

Ostrzeżenie

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

flush()

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

lock()
unlock()

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

close()

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

get_file(key)

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

Zobacz także

Справочная страница maildir от Courier

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

Using maildir format

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

mbox объекты

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

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

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

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

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

get_bytes(key, from_=False)

Примечание: Этот метод имеет дополнительный параметр (from_) по сравнению с другими классами. Первая строка записи файла mbox — это строка Unix „From”. Если from_ — False, первая строка файла отбрасывается.

get_file(key, from_=False)

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

Примечание: Этот метод имеет дополнительный параметр (from_) по сравнению с другими классами. Первая строка записи файла mbox — это строка Unix „From”. Если from_ — False, первая строка файла отбрасывается.

get_string(key, from_=False)

Примечание: Этот метод имеет дополнительный параметр (from_) по сравнению с другими классами. Первая строка записи файла mbox — это строка Unix „From”. Если from_ — False, первая строка файла отбрасывается.

lock()
unlock()

Используются три механизма блокировки — точечная блокировка и, если доступно, системные вызовы flock() и lockf().

Zobacz także

mbox man page from tin

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

Configuring Netscape Mail on Unix: Why The Content-Length Format is Bad

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

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

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

MH объекты

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

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

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

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

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

Zmienione w wersji 3.13: Поддерживаемые папки, не содержащие файла .mh_sequences.

list_folders()

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

get_folder(folder)

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

add_folder(folder)

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

remove_folder(folder)

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

get_sequences()

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

set_sequences(sequences)

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

pack()

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

Informacja

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

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

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

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

lock()
unlock()

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

get_file(key)

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

flush()

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

close()

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

Zobacz także

nmh — система обработки сообщений

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

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

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

Babyl объекты

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

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

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

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

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

get_labels()

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

Informacja

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

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

get_file(key)

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

lock()
unlock()

Используются три механизма блокировки — точечная блокировка и, если доступно, системные вызовы flock() и lockf().

Zobacz także

Format of Version 5 Babyl Files

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

Reading Mail with Rmail

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

MMDF объекты

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

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

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

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

get_bytes(key, from_=False)

Примечание: Этот метод имеет дополнительный параметр (from_) по сравнению с другими классами. Первая строка записи файла mbox — это строка Unix „From”. Если from_ — False, первая строка файла отбрасывается.

get_file(key, from_=False)

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

Примечание: Этот метод имеет дополнительный параметр (from_) по сравнению с другими классами. Первая строка записи файла mbox — это строка Unix „From”. Если from_ — False, первая строка файла отбрасывается.

lock()
unlock()

Используются три механизма блокировки — точечная блокировка и, если доступно, системные вызовы flock() и lockf().

Zobacz także

mmdf man page from tin

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

MMDF

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

Message объекты

class mailbox.Message(message=None)

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

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

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

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

MaildirMessage объекты

class mailbox.MaildirMessage(message=None)

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

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

Flag

Znaczenie

Wytłumaczenie

D

Чернетка

Під композицією

F

Ditandai

Позначено як важливе

P

Пройшов

Переслано, повторно надіслано або відхилено

R

Відповів

Відповів

S

Бачив

Прочитайте

T

У кошик

Позначено для подальшого видалення

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

get_subdir()

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

Informacja

Сообщение обычно перемещается из new в cur после того, как был осуществлен доступ к его почтовому ящику, независимо от того, было ли сообщение прочитано. Сообщение msg было прочитано, если S' в msg.get_flags() имеет значение True.

set_subdir(subdir)

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

get_flags()

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

set_flags(flags)

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

add_flag(flag)

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

remove_flag(flag)

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

get_date()

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

set_date(date)

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

get_info()

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

set_info(info)

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

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

Kondisi yang dihasilkan

стан mboxMessage або MMDFMessage

підкаталог „cur”.

Penanda O

Penanda F

Penanda F

Penanda R

Penanda A

Penanda S

Penanda R

Penanda T

Penanda D

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

Kondisi yang dihasilkan

MHMessage стан

підкаталог „cur”.

„невидима” послідовність

підкаталог „cur” і прапор S

немає „невидимої” послідовності

Penanda F

„позначена” послідовність

Penanda R

послідовність „відповів”.

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

Kondisi yang dihasilkan

BabylMessage стан

підкаталог „cur”.

ярлик „невидимий”.

підкаталог „cur” і прапор S

немає мітки „невидиме”.

Penanda P

мітка „переслано” або „повторно надіслано”.

Penanda R

мітка „відповів”.

Penanda T

ярлик „видалено”.

mboxMessage объекты

class mailbox.mboxMessage(message=None)

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

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

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

Flag

Znaczenie

Wytłumaczenie

R

Прочитайте

Прочитайте

O

Lama Old

Раніше виявлено MUA

D

Видалено

Позначено для подальшого видалення

F

Ditandai

Позначено як важливе

A

Dijawab Answered

Відповів

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

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

get_from()

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

set_from(from_, time_=None)

Установите для строки «От» значение from_, которое должно быть указано без начального «От» или завершающего символа новой строки. Для удобства можно указать time_, которое будет отформатировано соответствующим образом и добавлено к from_. Если указано time_, это должен быть экземпляр time.struct_time, кортеж, подходящий для передачи в time.strftime(), или True (для использования time .gmtime()).

get_flags()

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

set_flags(flags)

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

add_flag(flag)

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

remove_flag(flag)

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

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

Kondisi yang dihasilkan

MaildirMessage стан

Penanda R

Penanda S

Penanda O

підкаталог „cur”.

Penanda D

Penanda T

Penanda F

Penanda F

Penanda A

Penanda R

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

Kondisi yang dihasilkan

MHMessage стан

Penanda R dan Penanda O

немає „невидимої” послідовності

Penanda O

„невидима” послідовність

Penanda F

„позначена” послідовність

Penanda A

послідовність „відповів”.

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

Kondisi yang dihasilkan

BabylMessage стан

Penanda R dan Penanda O

немає мітки „невидиме”.

Penanda O

ярлик „невидимий”.

Penanda D

ярлик „видалено”.

Penanda A

мітка „відповів”.

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

Kondisi yang dihasilkan

MMDFMessage стан

Penanda R

Penanda R

Penanda O

Penanda O

Penanda D

Penanda D

Penanda F

Penanda F

Penanda A

Penanda A

MHMessage объекты

class mailbox.MHMessage(message=None)

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

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

Послідовність

Wytłumaczenie

невидимий

Не прочитано, але раніше виявлено MUA

dibalas

Відповів

позначено

Позначено як важливе

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

get_sequences()

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

set_sequences(sequences)

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

add_sequence(sequence)

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

remove_sequence(sequence)

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

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

Kondisi yang dihasilkan

MaildirMessage стан

„невидима” послідовність

tanpa penanda S

послідовність „відповів”.

Penanda R

„позначена” послідовність

Penanda F

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

Kondisi yang dihasilkan

стан mboxMessage або MMDFMessage

„невидима” послідовність

tanpa penanda R

послідовність „відповів”.

Penanda A

„позначена” послідовність

Penanda F

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

Kondisi yang dihasilkan

BabylMessage стан

„невидима” послідовність

ярлик „невидимий”.

послідовність „відповів”.

мітка „відповів”.

BabylMessage объекты

class mailbox.BabylMessage(message=None)

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

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

Мітка

Wytłumaczenie

невидимий

Не прочитано, але раніше виявлено MUA

dihapus

Позначено для подальшого видалення

подано

Скопійовано в інший файл або поштову скриньку

dijawab

Відповів

пересилається

Переслано

diubah

Змінено користувачем

dikirim ulang

Dikirim Ulang

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

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

get_labels()

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

set_labels(labels)

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

add_label(label)

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

remove_label(label)

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

get_visible()

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

set_visible(visible)

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

update_visible()

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

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

Kondisi yang dihasilkan

MaildirMessage стан

ярлик „невидимий”.

tanpa penanda S

ярлик „видалено”.

Penanda T

мітка „відповів”.

Penanda R

мітка „переслано”.

Penanda P

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

Kondisi yang dihasilkan

стан mboxMessage або MMDFMessage

ярлик „невидимий”.

tanpa penanda R

ярлик „видалено”.

Penanda D

мітка „відповів”.

Penanda A

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

Kondisi yang dihasilkan

MHMessage стан

ярлик „невидимий”.

„невидима” послідовність

мітка „відповів”.

послідовність „відповів”.

MMDFMessage объекты

class mailbox.MMDFMessage(message=None)

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

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

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

Flag

Znaczenie

Wytłumaczenie

R

Прочитайте

Прочитайте

O

Lama Old

Раніше виявлено MUA

D

Видалено

Позначено для подальшого видалення

F

Ditandai

Позначено як важливе

A

Dijawab Answered

Відповів

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

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

get_from()

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

set_from(from_, time_=None)

Установите для строки «От» значение from_, которое должно быть указано без начального «От» или завершающего символа новой строки. Для удобства можно указать time_, которое будет отформатировано соответствующим образом и добавлено к from_. Если указано time_, это должен быть экземпляр time.struct_time, кортеж, подходящий для передачи в time.strftime(), или True (для использования time .gmtime()).

get_flags()

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

set_flags(flags)

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

add_flag(flag)

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

remove_flag(flag)

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

Когда экземпляр MMDFMessage создается на основе экземпляра MaildirMessage, строка «От» генерируется на основе даты доставки экземпляра MaildirMessage, и происходят следующие преобразования:

Kondisi yang dihasilkan

MaildirMessage стан

Penanda R

Penanda S

Penanda O

підкаталог „cur”.

Penanda D

Penanda T

Penanda F

Penanda F

Penanda A

Penanda R

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

Kondisi yang dihasilkan

MHMessage стан

Penanda R dan Penanda O

немає „невидимої” послідовності

Penanda O

„невидима” послідовність

Penanda F

„позначена” послідовність

Penanda A

послідовність „відповів”.

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

Kondisi yang dihasilkan

BabylMessage стан

Penanda R dan Penanda O

немає мітки „невидиме”.

Penanda O

ярлик „невидимий”.

Penanda D

ярлик „видалено”.

Penanda A

мітка „відповів”.

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

Kondisi yang dihasilkan

mboxMessage стан

Penanda R

Penanda R

Penanda O

Penanda O

Penanda D

Penanda D

Penanda F

Penanda F

Penanda A

Penanda A

Wyjątki

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

exception mailbox.Error

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

exception mailbox.NoSuchMailboxError

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

exception mailbox.NotEmptyError

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

exception mailbox.ExternalClashError

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

exception mailbox.FormatError

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

Przykłady

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

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