rfc822 — Разбор заголовков почтовых сообщений RFC 2822

В данном модуле определён класс Message, представляющий «сообщение электронной почты» в соответствии с интернет-стандартом RFC 2822. 1 Такие сообщения состоят из набора заголовков и тела сообщения. Модуль также определяет вспомогательный класс AddressList для разбора адресов RFC 2822. Для получения информации о синтаксисе сообщений RFC 2822 обратитесь к RFC.

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

class rfc822.Message(file[, seekable])

Экземпляр Message создаётся с входным объектом в качестве параметра. Класс Message полагается только на то, что входной объект имеет метод readline(); в частности, обычные объекты файлов подходят. При создании экземпляра из входного объекта считываются заголовки до разделительной строки (обычно пустая строка) и сохраняются в экземпляре. Тело сообщения, идущее после заголовков, не потребляется.

Этот класс может работать с любым входным объектом, поддерживающим метод readline(). Если входной объект поддерживает возможности seek и tell, метод rewindbody() будет работать; также, некорректные строки будут возвращены обратно в поток ввода. Если входной объект не поддерживает seek, но имеет метод unread(), который может вернуть строку ввода, Message будет использовать его для возврата некорректных строк. Таким образом, этот класс может использоваться для разбора сообщений, поступающих из буферизованного потока.

Необязательный аргумент seekable предоставлен как обходной путь для некоторых библиотек stdio, в которых tell() отбрасывает буферизованные данные перед обнаружением того, что системный вызов lseek() не работает. Для максимальной переносимости вы должны установить аргумент seekable в ноль, чтобы предотвратить начальный tell() при передаче неискаемого объекта, такого как объект файла, созданный из объекта сокета.

Строки, считанные из файла, могут завершаться CR-LF или одним символом перевода строки; завершающий CR-LF заменяется одним символом перевода строки перед сохранением строки.

Все проверки соответствия заголовков выполняются независимо от регистра; например, m['From'], m['from'] и m['FROM'] дают один и тот же результат.

class rfc822.AddressList(field)

Вы можете создать экземпляр вспомогательного класса AddressList, используя единственный строковый параметр, список адресов RFC 2822, разделённых запятыми, для разбора. (Параметр None возвращает пустой список.)

rfc822.quote(str)

Возвращает новую строку, в которой обратные слэши в str заменены на два обратных слэша, а двойные кавычки заменены на обратный слэш и двойную кавычку.

rfc822.unquote(str)

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

rfc822.parseaddr(address)

Разбирает address, который должен быть значением некоторого поля, содержащего адрес, например, To или Cc, на составляющие части «имя» и «адрес электронной почты». Возвращает кортеж этой информации, если разбор не удался, возвращается кортеж (None, None).

rfc822.dump_address_pair(pair)

Обратная функция parseaddr(), которая принимает кортеж из двух элементов вида (realname, email_address) и возвращает строковое значение, подходящее для заголовка To или Cc. Если первый элемент pair ложный, то возвращается второй элемент без изменений.

rfc822.parsedate(date)

Попытка разбора даты по правилам RFC 2822. Однако некоторые почтовые клиенты не следуют этому формату, поэтому parsedate() пытается угадать в таких случаях. date — строка, содержащая дату RFC 2822, например, 'Mon, 20 Nov 1995 19:12:08 -0500'. Если разбор даты успешен, parsedate() возвращает 9-элементный кортеж, который можно напрямую передать в time.mktime(); в противном случае возвращается None. Обратите внимание, что индексы 6, 7 и 8 результата кортежа не используются.

rfc822.parsedate_tz(date)

Выполняет ту же функцию, что и parsedate(), но возвращает либо None, либо 10-элементный кортеж; первые 9 элементов образуют кортеж, который можно напрямую передать в time.mktime(), а десятый — смещение часового пояса даты от UTC (официальное название — Всемирное координированное время). (Обратите внимание, что знак смещения часового пояса является обратным знаку time.timezone переменной для того же часового пояса; последняя переменная следует стандарту POSIX, а этот модуль следует RFC 2822). Если во входной строке нет часового пояса, последний элемент возвращаемого кортежа None. Обратите внимание, что индексы 6, 7 и 8 результата кортежа не используются.

rfc822.mktime_tz(tuple)

Преобразует 10-элементный кортеж, возвращаемый parsedate_tz(), в метку времени UTC. Если элемент часового пояса в кортеже None, предполагается местное время. Незначительный недостаток: сначала интерпретируются первые 8 элементов как местное время, а затем компенсируется разница во времени часовых поясов; это может привести к небольшой ошибке около дат перехода на летнее/зимнее время. Достаточно незначительная ошибка для общего использования.

1. Объекты сообщений

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

Message.rewindbody()

Переход к началу тела сообщения. Это работает только если объект файла поддерживает seek.

Message.isheader(line)

Возвращает канонизированное имя поля строки (ключ словаря, который будет использоваться для его индексирования), если строка является законным заголовком RFC 2822; в противном случае возвращает None (что подразумевает, что разбор должен остановиться здесь, и строка должна быть возвращена в поток ввода). Иногда бывает полезно переопределить этот метод в подклассе.

Message.islast(line)

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

Message.iscomment(line)

Возвращает True, если заданную строку следует игнорировать, просто пропустить. По умолчанию это заглушка, которая всегда возвращает False, но вы можете переопределить её в подклассе.

Message.getallmatchingheaders(name)

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

Message.getfirstmatchingheader(name)

Возвращает список строк, составляющих первый заголовок, соответствующий name, и его строку(и) продолжения, если таковые имеются. Возвращает None если заголовок не соответствует name.

Message.getrawheader(name)

Возвращает одну строку, состоящую из текста после двоеточия в первом заголовке, соответствующем name. Это включает в себя ведущие пробелы, конечную строку переноса, а также внутренние переносы строк и пробелы, если присутствуют строки продолжения. Возвращает None если заголовок не соответствует name.

Message.getheader(name[, default])

Возвращает одну строку, состоящую из последнего заголовка, соответствующего name, но удаляет ведущие и хвостовые пробелы. Внутренние пробелы не удаляются. Необязательный аргумент default может быть использован для указания другого значения по умолчанию, которое будет возвращено, если заголовок не соответствует name; по умолчанию это None. Это предпочтительный способ получения разобранных заголовков.

Message.get(name[, default])

Псевдоним для getheader(), чтобы сделать интерфейс более совместимым с обычными словарями.

Message.getaddr(name)

Возвращает пару (full name, email address) , разобранную из строки, возвращенной getheader(name). Если заголовок, соответствующий name, не существует, возвращается (None, None); в противном случае и полное имя, и адрес являются (возможно, пустыми) строками.

Пример: если первый заголовок From у m содержит строку 'jack@cwi.nl (Jack Jansen)', то m.getaddr('From') вернёт пару ('Jack Jansen', 'jack@cwi.nl'). Если заголовок содержал 'Jack Jansen <jack@cwi.nl>' вместо этого, результат был бы точно таким же.

Message.getaddrlist(name)

Это аналогично getaddr(list), но анализирует заголовок, содержащий список адресов электронной почты (например, заголовок To), и возвращает список пар (full name, email address) (даже если в заголовке был только один адрес). Если заголовок, соответствующий name, отсутствует, возвращается пустой список.

Если существует несколько заголовков, соответствующих заданному заголовку (например, если есть несколько заголовков Cc), все они анализируются для поиска адресов. Также анализируются любые строки продолжения, содержащиеся в именованных заголовках.

Message.getdate(name)

Извлекает заголовок с помощью getheader() и анализирует его в 9-кортеж, совместимый с time.mktime(); обратите внимание, что поля 6, 7 и 8 неприменимы. Если заголовок, соответствующий name, отсутствует или не поддаётся анализу, возвращается None.

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

Message.getdate_tz(name)

Извлекает заголовок с помощью getheader() и анализирует его в 10-кортеж; первые 9 элементов сформируют кортеж, совместимый с time.mktime(), а 10-й — число, представляющее смещение часового пояса даты от UTC. Аналогично getdate(), если заголовок, соответствующий name, отсутствует или не поддаётся анализу, возвращается None.

Message объекты также поддерживают ограниченный интерфейс сопоставления. В частности: m[name] похож на m.getheader(name), но вызывает KeyError, если соответствующего заголовка нет; и len(m), m.get(name[, default]), name in m, m.keys(), m.values() m.items(), и m.setdefault(name[, default]) работают как ожидается, с одним отличием, что setdefault() использует пустую строку в качестве значения по умолчанию. Message объекты также поддерживают интерфейс изменения отображения m[name] = value и del m[name]. Message объекты не поддерживают clear(), copy(), popitem(), или update() методы интерфейса отображения. (Поддержка get() и setdefault() была добавлена только в Python 2.2.)

Наконец, у Message объектов есть некоторые публичные переменные экземпляров:

Message.headers

Список, содержащий весь набор строк заголовка в том порядке, в котором они были прочитаны (за исключением того, что вызовы setitem могут нарушить этот порядок). Каждая строка содержит заключительный символ новой строки. Пустая строка, завершающая заголовки, не содержится в списке.

Message.fp

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

Message.unixfrom

Строка Unix From, если в сообщении была такая строка, или пустая строка. Это необходимо для восстановления сообщения в некоторых контекстах, таких как файл почтового ящика в формате mbox.

2. Объекты AddressList

У экземпляра AddressList есть следующие методы:

AddressList.__len__()

Возвращает количество адресов в списке адресов.

AddressList.__str__()

Возвращает канонизированное строковое представление списка адресов. Адреса отображаются в формате «имя» <host@domain>, разделенные запятыми.

AddressList.__add__(alist)

Возвращает новый экземпляр AddressList, содержащий все адреса в обоих операндах AddressList, с удалением дубликатов (объединение множеств).

AddressList.__iadd__(alist)

Поэлементная версия __add__(); преобразует этот экземпляр AddressList в объединение его самого и правого экземпляра, alist.

AddressList.__sub__(alist)

Возвращает новый экземпляр AddressList, содержащий каждый адрес в левом операнде AddressList, который отсутствует в правом операнде адреса (разность множеств).

AddressList.__isub__(alist)

Поэлементная версия __sub__(), удаляющая адреса в этом списке, которые также присутствуют в alist.

Наконец, у AddressList экземпляров есть одна публичная переменная экземпляра:

AddressList.addresslist

Список пар кортежей строк, по одному на адрес. В каждом члене первый — канонизированная часть имени, второй — фактический адрес маршрута (пара пользователя-хоста, разделенная '@', домен).

Приложения

1

Этот модуль изначально соответствовал RFC 822, отсюда и название. С тех пор была выпущена RFC 2822 как обновление к RFC 822. Этот модуль следует считать совместимым с RFC 2822, особенно в случаях, когда синтаксис или семантика изменились с RFC 822.