email — Пакет обработки почты и MIME

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

Пакет email представляет собой библиотеку для управления почтовыми сообщениями. Он не предназначен для отправки почтовых сообщений на SMTP (RFC 2821), NNTP или другие серверы; эти функции выполняют модули, такие как smtplib. Пакет email стремится к максимальной соответствию RFC, поддерживая RFC 5322 и RFC 6532, а также такие RFC, связанные с MIME, как RFC 2045, RFC 2046, RFC 2047, RFC 2183 и RFC 2231.

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

Центральным компонентом пакета является «модель объектов», представляющая почтовые сообщения. Приложение взаимодействует с пакетом главным образом через интерфейс модели объектов, определенный в подмодуле message. Приложение может использовать этот API для получения информации об имейле, создания нового или добавления/удаления подкомпонентов, которые сами используют тот же интерфейс модели объектов. То есть, следуя природе почтовых сообщений и их MIME-подкомпонентов, модель объектов email представляет собой древовидную структуру объектов, все из которых предоставляют API EmailMessage.

Два других основных компонента пакета — это parser и generator. Парсер принимает сериализованную версию почтового сообщения (поток байтов) и преобразует её в дерево объектов EmailMessage. Генератор принимает объект EmailMessage и преобразует его обратно в сериализованный поток байтов. (Парсер и генератор также обрабатывают потоки символов текста, но такое использование не рекомендуется, так как легко получить сообщения, недействительные каким-либо образом.)

Компонент управления — модуль policy. Каждый объект EmailMessage, каждый generator и каждый parser имеет связанный объект policy, который управляет его поведением. Обычно приложение должно указать политику только при создании объекта EmailMessage, либо напрямую создавая новый объект EmailMessage, либо загружая объект из потока с помощью parser. Но политику можно изменить при сериализации сообщения с помощью generator. Это позволяет, например, загрузить общее почтовое сообщение из файла, но сериализовать его с настройками стандартного SMTP при отправке на почтовый сервер.

Пакет email старается скрыть детали различных RFC от приложения. Понятийно приложение должно иметь возможность рассматривать почтовое сообщение как структурированное дерево из текстовых строк Unicode и бинарных вложений, не беспокоясь о том, как они представлены при сериализации. Однако на практике часто необходимо быть осведомленным хотя бы о некоторых правилах, управляющих MIME-сообщениями и их структурой, в частности о названиях и характере MIME «типов содержимого» и о том, как они идентифицируют составные документы. В основном эти знания требуются только для более сложных приложений, и даже тогда — только о высокой структуре, а не о деталях представления этих структур. Поскольку MIME-типы содержимого широко используются в современном интернет-программном обеспечении (не только в почте), это понятие многим программистам будет знакомо.

В следующих разделах описывается функциональность пакета email. Мы начинаем с модели объектов message, которая является основным интерфейсом, используемым приложением, и следуем за компонентами parser и generator. Затем мы рассмотрим элементы управления policy, что завершает рассмотрение основных компонентов библиотеки.

Следующие три раздела описывают исключения, которые может генерировать пакет, и недостатки (несоответствие RFC), которые может обнаружить parser. Затем мы рассмотрим headerregistry и contentmanager подкомпоненты, которые предоставляют инструменты для более подробного управления заголовками и полезной нагрузкой соответственно. Оба компонента содержат функции, относящиеся к обработке нетривиальных сообщений, а также документацию по расширяемым API, что будет интересно для продвинутых приложений.

После этого представлен ряд примеров использования основных частей API, описанных в предыдущих разделах.

Вышеизложенное представляет собой современный (совместимый с Unicode) API пакета email. Остальные разделы, начиная с класса Message, охватывают устаревший API compat32, который намного более тесно связан с деталями представления почтовых сообщений. API compat32 не скрывает детали RFC от приложения, но для приложений, которым требуется работать на этом уровне, они могут быть полезными инструментами. Данная документация также актуальна для приложений, которые по-прежнему используют API compat32 по причинам обратной совместимости.

Содержание документации пакета email:

• email.message: Представление электронного сообщения
  • EmailMessage
    • as_string()
    • __str__()
    • as_bytes()
    • __bytes__()
    • is_multipart()
    • set_unixfrom()
    • get_unixfrom()
    • __len__()
    • __contains__()
    • __getitem__()
    • __setitem__()
    • __delitem__()
    • keys()
    • values()
    • items()
    • get()
    • get_all()
    • add_header()
    • replace_header()
    • get_content_type()
    • get_content_maintype()
    • get_content_subtype()
    • get_default_type()
    • set_default_type()
    • set_param()
    • del_param()
    • get_filename()
    • get_boundary()
    • set_boundary()
    • get_content_charset()
    • get_charsets()
    • is_attachment()
    • get_content_disposition()
    • walk()
    • get_body()
    • iter_attachments()
    • iter_parts()
    • get_content()
    • set_content()
    • make_related()
    • make_alternative()
    • make_mixed()
    • add_related()
    • add_alternative()
    • add_attachment()
    • clear()
    • clear_content()
    • preamble
    • epilogue
    • defects
  • MIMEPart
• email.parser: Парсинг электронных сообщений
  • API парсера Feed
    • BytesFeedParser
      • feed()
      • close()
    • FeedParser
  • API парсера
    • BytesParser
      • parse()
      • parsebytes()
    • BytesHeaderParser
    • Parser
      • parse()
      • parsestr()
    • HeaderParser
    • message_from_bytes()
    • message_from_binary_file()
    • message_from_string()
    • message_from_file()
  • Дополнительные заметки

• email.generator: Генерация MIME-документов
  • BytesGenerator
    • flatten()
    • clone()
    • write()
  • Generator
    • flatten()
    • clone()
    • write()
  • DecodedGenerator
• email.policy: Объекты политики
  • Policy
    • max_line_length
    • linesep
    • cte_type
    • raise_on_defect
    • mangle_from_
    • message_factory
    • verify_generated_headers
    • clone()
    • handle_defect()
    • register_defect()
    • header_max_count()
    • header_source_parse()
    • header_store_parse()
    • header_fetch_parse()
    • fold()
    • fold_binary()
  • EmailPolicy
    • utf8
    • refold_source
    • header_factory
    • content_manager
    • header_max_count()
    • header_source_parse()
    • header_store_parse()
    • header_fetch_parse()
    • fold()
    • fold_binary()
  • default
  • SMTP
  • SMTPUTF8
  • HTTP
  • strict
  • Compat32
    • mangle_from_
    • header_source_parse()
    • header_store_parse()
    • header_fetch_parse()
    • fold()
    • fold_binary()
  • compat32
• email.errors: Классы исключений и дефектов
  • MessageError
  • MessageParseError
  • HeaderParseError
  • BoundaryError
  • MultipartConversionError
  • HeaderWriteError
  • MessageDefect
  • HeaderDefect

• email.headerregistry: Настройка объектов заголовков
  • BaseHeader
    • name
    • defects
    • max_count
    • fold()
  • UnstructuredHeader
  • DateHeader
    • datetime
  • AddressHeader
    • groups
    • addresses
  • SingleAddressHeader
    • address
  • MIMEVersionHeader
    • version
    • major
    • minor
  • ParameterizedMIMEHeader
    • params
  • ContentTypeHeader
    • content_type
    • maintype
    • subtype
  • ContentDispositionHeader
    • content_disposition
  • ContentTransferEncoding
    • cte
  • HeaderRegistry
    • map_to_type()
    • __getitem__()
    • __call__()
  • Address
    • display_name
    • username
    • domain
    • addr_spec
    • __str__()
  • Group
    • display_name
    • addresses
    • __str__()
• email.contentmanager: Управление содержимым MIME
  • ContentManager
    • get_content()
    • set_content()
    • add_get_handler()
    • add_set_handler()
  • Примеры работы с менеджером содержимого
    • raw_data_manager
      • get_content()
      • set_content()
• email: Примеры

Запись API:

• email.message.Message: Представление сообщения электронной почты с помощью API compat32
  • Message
    • as_string()
    • __str__()
    • as_bytes()
    • __bytes__()
    • is_multipart()
    • set_unixfrom()
    • get_unixfrom()
    • attach()
    • get_payload()
    • set_payload()
    • set_charset()
    • get_charset()
    • __len__()
    • __contains__()
    • __getitem__()
    • __setitem__()
    • __delitem__()
    • keys()
    • values()
    • items()
    • get()
    • get_all()
    • add_header()
    • replace_header()
    • get_content_type()
    • get_content_maintype()
    • get_content_subtype()
    • get_default_type()
    • set_default_type()
    • get_params()
    • get_param()
    • set_param()
    • del_param()
    • set_type()
    • get_filename()
    • get_boundary()
    • set_boundary()
    • get_content_charset()
    • get_charsets()
    • get_content_disposition()
    • walk()
    • preamble
    • epilogue
    • defects
• email.mime: Создание объектов электронной почты и MIME с нуля
  • MIMEBase
  • MIMENonMultipart
  • MIMEMultipart
  • MIMEApplication
  • MIMEAudio
  • MIMEImage
  • MIMEMessage
  • MIMEText
• email.header: Локализованные заголовки
  • Header
    • append()
    • encode()
    • __str__()
    • __eq__()
    • __ne__()
  • decode_header()
  • make_header()

• email.charset: Представление наборов символов
  • Charset
    • input_charset
    • header_encoding
    • body_encoding
    • output_charset
    • input_codec
    • output_codec
    • get_body_encoding()
    • get_output_charset()
    • header_encode()
    • header_encode_lines()
    • body_encode()
    • __str__()
    • __eq__()
    • __ne__()
  • add_charset()
  • add_alias()
  • add_codec()
• email.encoders: Кодировщики
  • encode_quopri()
  • encode_base64()
  • encode_7or8bit()
  • encode_noop()
• email.utils: Разные служебные функции
  • localtime()
  • make_msgid()
  • quote()
  • unquote()
  • parseaddr()
  • formataddr()
  • getaddresses()
  • parsedate()
  • parsedate_tz()
  • parsedate_to_datetime()
  • mktime_tz()
  • formatdate()
  • format_datetime()
  • decode_rfc2231()
  • encode_rfc2231()
  • collapse_rfc2231_value()
  • decode_params()
• email.iterators: Итераторы
  • body_line_iterator()
  • typed_subpart_iterator()
  • _structure()