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, как правило, реализованы лучше.

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

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

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

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

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

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

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

keyfile и certfile — устаревшая альтернатива context. Они могут указывать на файлы с закрытыми ключами и цепочкой сертификатов в формате PEM для SSL-соединения соответственно.

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

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

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

Устарело начиная с версии 3.6: keyfile и certfile устарели в пользу context. Пожалуйста, используйте ssl.SSLContext.load_cert_chain() вместо этого или позвольте ssl.create_default_context() выбрать доверенные сертификаты CA системы.

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

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

См. также

Module imaplib: Стандартный модуль Python IMAP.
Часто задаваемые вопросы о Fetchmail: В FAQ для клиента 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): Отправляет команду пользователя, ответ должен указать, что требуется пароль.

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

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

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

POP3.stat(): Получает статус почтового ящика. Результат — кортеж из 2 целых чисел: (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(): Не делает ничего. Может использоваться в качестве keep-alive.

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 и Server Name Indication (см. 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)

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