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 установлен в ноль, будет вызвано исключение ValueError для предотвращения создания неблокируемого сокета.

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() выбрать доверенные сертификаты ЦС системы для вас.

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

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

См. также

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

END_OF_DOCUMENT_MARKER

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

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

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