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

Объекты 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 и указанием имени сервера (см. 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)

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