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 задаёт тайм-аут в секундах для попытки соединения (если не указан, используется глобальный стандартный тайм-аут).

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-соединения.

Изменено в версии 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 не обрабатываются). Причина исключения передаётся конструктору в виде строки.

21.14.1. Объекты 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()

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

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 не имеют дополнительных методов. Интерфейс этого подкласса идентичен родительскому.

21.14.2. Пример 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)

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