poplib — клиент протокола POP3

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

Этот модуль определяет класс POP3, который инкапсулирует подключение к серверу POP3 и реализует протокол, описанный в RFC 1939. Класс POP3 поддерживает как минимальный, так и необязательный набор команд из RFC 1939. Класс POP3 также поддерживает команду STLS, введённую в RFC 2595 для обеспечения зашифрованной связи по уже установленному соединению.

Кроме того, этот модуль предоставляет класс POP3_SSL, который поддерживает подключение к серверам POP3, использующим SSL в качестве базового уровня протокола.

Обратите внимание, что POP3, несмотря на широкую поддержку, устаревает. Качество реализации серверов POP3 сильно различается, и слишком многие из них работают довольно плохо. Если ваш почтовый сервер поддерживает IMAP, лучше использовать класс imaplib.IMAP4, поскольку серверы IMAP, как правило, реализованы лучше.

Доступность: недоступен в Emscripten и WASI.

Этот модуль не работает или недоступен на платформах WebAssembly wasm32-emscripten и wasm32-wasi. Дополнительную информацию см. в разделе Платформы WebAssembly.

Модуль poplib предоставляет два класса:

class poplib.POP3(host, port=POP3_PORT[, timeout])

Этот класс реализует сам протокол POP3. Соединение устанавливается при инициализации экземпляра. Если параметр port не указан, используется стандартный порт POP3 (110). Необязательный параметр timeout задаёт время ожидания в секундах при попытке установить соединение (если параметр не указан, используется глобальное значение времени ожидания по умолчанию).

Вызывает событие аудита poplib.connect с аргументами self, host, port.

Все команды вызывают событие аудита poplib.putline с аргументами self и line, где line — байты, которые будут отправлены удалённому узлу.

Изменено в версии 3.9: Если для параметра timeout задано значение 0, будет вызвано исключение ValueError, чтобы предотвратить создание неблокирующего сокета.

class poplib.POP3_SSL(host, port=POP3_SSL_PORT, *, timeout=None, context=None)

Это подкласс POP3, который подключается к серверу через зашифрованный SSL-сокет. Если параметр port не указан, используется стандартный порт POP3 поверх SSL — 995. Параметр timeout работает так же, как в конструкторе POP3. Необязательный параметр context — это объект ssl.SSLContext, позволяющий объединить параметры конфигурации SSL, сертификаты и закрытые ключи в одну структуру, потенциально рассчитанную на длительное использование. Рекомендации по безопасной работе см. в разделе Рекомендации по безопасности.

Вызывает событие аудита poplib.connect с аргументами self, host, port.

Изменено в версии 3.2: Добавлен параметр context.

Изменено в версии 3.4: Класс теперь поддерживает проверку имени узла с помощью ssl.SSLContext.check_hostname и индикацию имени сервера (см. ssl.HAS_SNI).

Изменено в версии 3.12: Устаревшие параметры keyfile и certfile удалены.

В качестве атрибута модуля poplib определено одно исключение:

exception poplib.error_proto: Исключение, возникающее при любых ошибках этого модуля (ошибки модуля socket не перехватываются). Причина исключения передаётся конструктору в виде строки.

См. также

Module imaplib: Стандартный модуль Python для IMAP.
Часто задаваемые вопросы о Fetchmail: В разделе часто задаваемых вопросов о POP/IMAP-клиенте fetchmail собраны сведения о различиях между серверами POP3 и их несоответствиях RFC. Эта информация может пригодиться, если вам нужно написать приложение на основе протокола POP.

Объекты POP3

Все команды POP3 представлены методами с такими же именами в нижнем регистре; большинство из них возвращают текст ответа сервера.

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

POP3.set_debuglevel(level): Задаёт уровень отладки экземпляра. Он определяет объём выводимых отладочных данных. Значение по умолчанию, 0, отключает вывод отладочных данных. Значение 1 включает умеренный объём отладочных данных — обычно одну строку на запрос. Значение 2 или выше включает максимальный объём отладочных данных, записывая каждую строку, отправленную через управляющее соединение или полученную по нему.

POP3.getwelcome(): Возвращает строку приветствия, отправленную сервером POP3.

POP3.capa(): Запрашивает возможности сервера, описанные в RFC 2449. Возвращает словарь в формате {'name': ['param'...]}.

Добавлено в версии 3.4.

POP3.user(username): Отправляет команду user; ответ должен указывать на необходимость указать пароль.

POP3.pass_(password): Отправляет пароль; ответ содержит количество сообщений и размер почтового ящика. Примечание: почтовый ящик на сервере заблокирован до вызова quit().

POP3.apop(user, secret): Использует более безопасную аутентификацию APOP для входа на сервер POP3.

POP3.rpop(user): Использует аутентификацию RPOP (аналогичную r-командам UNIX) для входа на сервер POP3.

POP3.stat(): Получает состояние почтового ящика. Результат — кортеж из двух целых чисел: (message count, mailbox size).

POP3.list([which]): Запрашивает список сообщений; результат имеет формат (response, ['mesg_num octets', ...], octets). Если задан параметр which, возвращается указанное сообщение.

POP3.retr(which): Получает сообщение с номером which целиком и устанавливает для него флаг «прочитано». Результат имеет формат (response, ['line', ...], octets).

POP3.dele(which): Помечает сообщение с номером which для удаления. На большинстве серверов сообщения фактически удаляются только после команды QUIT (главное исключение — Eudora QPOP, который намеренно нарушает RFC, выполняя отложенное удаление при любом разрыве соединения).

POP3.rset(): Снимает все отметки об удалении в почтовом ящике.

POP3.noop(): Ничего не делает. Может использоваться для поддержания соединения.

POP3.quit(): Завершает сеанс: фиксирует изменения, разблокирует почтовый ящик и закрывает соединение.

POP3.top(which, howmuch)

Получает заголовок сообщения и howmuch строк после заголовка сообщения с номером which. Результат имеет формат (response, ['line', ...], octets).

Команда POP3 TOP, используемая этим методом, в отличие от команды RETR, не устанавливает флаг «прочитано» для сообщения; к сожалению, команда TOP плохо описана в RFC и часто неправильно работает на малоизвестных серверах. Прежде чем полагаться на этот метод, проверьте его вручную на используемых вами серверах POP3.

POP3.uidl(which=None): Возвращает список дайджестов сообщений (уникальных идентификаторов). Если задан параметр which, результат содержит уникальный идентификатор этого сообщения в формате 'response mesgnum uid; в противном случае результат представляет собой список (response, ['mesgnum uid', ...], octets).

POP3.utf8(): Пытается переключиться в режим UTF-8. В случае успеха возвращает ответ сервера, в противном случае вызывает исключение error_proto. Описано в RFC 6856.

Добавлено в версии 3.5.

POP3.stls(context=None)

Запускает сеанс TLS для активного соединения, как описано в RFC 2595. Это разрешено только до аутентификации пользователя.

Параметр context — это объект ssl.SSLContext, позволяющий объединить параметры конфигурации SSL, сертификаты и закрытые ключи в одну структуру, потенциально рассчитанную на длительное использование. Рекомендации по безопасной работе см. в разделе Рекомендации по безопасности.

Этот метод поддерживает проверку имени узла с помощью ssl.SSLContext.check_hostname и индикацию имени сервера (см. ssl.HAS_SNI).

Добавлено в версии 3.4.

У экземпляров POP3_SSL нет дополнительных методов. Интерфейс этого подкласса идентичен интерфейсу родительского класса.

Пример POP3

Ниже приведён минимальный пример (без проверки ошибок), который открывает почтовый ящик, получает все сообщения и выводит их:

import getpass, poplib

M = poplib.POP3('localhost')
M.user(getpass.getuser())
M.pass_(getpass.getpass())
numMessages = len(M.list()[1])
for i in range(numMessages):
    for j in M.retr(i+1)[1]:
        print(j)

В конце модуля находится раздел с тестами, содержащий более подробный пример использования.