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-over-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).

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

exception poplib.error_proto

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

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

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)

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