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

Availability: не WASI.

Этот модуль не работает или недоступен на WebAssembly. Дополнительную информацию см. в разделе Платформы WebAssembly.

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

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

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

Поднимает auditing event poplib.connect с аргументами self, host, port.

Поднимает auditing event poplib.putline с аргументами self, line.

Изменено в версии 3.9: Если параметр timeout установлен в нулевое значение, он вызовет ошибку ValueError, чтобы предотвратить создание неблокирующего сокета.

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

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

Поднимает auditing event poplib.connect с аргументами self, host, port.

Поднимает auditing event poplib.putline с аргументами self, line.

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

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

Изменено в версии 3.9: Если параметр timeout установлен в нулевое значение, он вызовет ошибку ValueError, чтобы предотвратить создание неблокирующего сокета.

Изменено в версии 3.12: Устаревшие параметры keyfile и certfile были удалены.

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

exception poplib.error_proto

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

См.также

Модуль imaplib

Стандартный модуль Python IMAP.

Frequently Asked Questions About Fetchmail

В FAQ по fetchmail POP/IMAP-клиента собрана информация о вариациях POP3-серверов и несоответствии RFC, которая может оказаться полезной, если вам нужно написать приложение, основанное на протоколе POP.

Объекты POP3

Все команды POP3 представлены одноименными методами, написанными в нижнем регистре; большинство из них возвращают текст ответа, отправленный сервером.

У экземпляра POP3 есть следующие методы:

POP3.set_debuglevel(level)

Установите уровень отладки экземпляра. Это управляет количеством выводимых отладочных данных. По умолчанию, 0, отладочный вывод не производится. Значение 1 выводит умеренное количество отладочных данных, обычно одну строку на запрос. Значение 2 или выше обеспечивает максимальный объем отладочной информации, регистрируя каждую строку, отправленную и полученную по управляющему соединению.

POP3.getwelcome()

Возвращает строку приветствия, отправленную сервером POP3.

POP3.capa()

Запрашивает возможности сервера, указанные в RFC 2449. Возвращает словарь в форме {'name': ['param'...]}.

Added in version 3.4.

POP3.user(username)

Отправьте команду пользователю, в ответе должно быть указано, что требуется пароль.

POP3.pass_(password)

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

POP3.apop(user, secret)

Используйте более безопасную аутентификацию APOP для входа на сервер POP3.

POP3.rpop(user)

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

POP3.stat()

Получение статуса почтового ящика. Результатом является кортеж из 2 целых чисел: (message count, mailbox size).

POP3.list([which])

Запрос списка сообщений, результат в виде (response, ['mesg_num octets', ...], octets). Если установлено значение which, то это сообщение, которое нужно перечислить.

POP3.retr(which)

Получение целого номера сообщения which и установка его флага seen. Результат имеет вид (response, ['line', ...], octets).

POP3.dele(which)

Отметить номер сообщения как для удаления. На большинстве серверов удаление фактически не выполняется до QUIT (основным исключением является Eudora QPOP, которая намеренно нарушает RFC, выполняя отложенное удаление при любом отключении).

POP3.rset()

Удалите все отметки об удалении почтового ящика.

POP3.noop()

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

POP3.quit()

Подписание: фиксация изменений, разблокировка почтового ящика, сброс соединения.

POP3.top(which, howmuch)

Получает заголовок сообщения плюс сколько строк сообщения после заголовка сообщения с номером как. Результат имеет вид (response, ['line', ...], octets).

Команда POP3 TOP, используемая в этом методе, в отличие от команды RETR, не устанавливает флаг seen сообщения; к сожалению, TOP плохо прописана в RFC и часто нарушается в серверах других марок. Прежде чем доверять этому методу, протестируйте его вручную на серверах POP3, которые вы будете использовать.

POP3.uidl(which=None)

Возвращает список дайджестов сообщений (уникальных идентификаторов). Если указано which, результат содержит уникальный id для данного сообщения в виде 'response mesgnum uid, иначе результат - список (response, ['mesgnum uid', ...], octets).

POP3.utf8()

Попытка перейти в режим UTF-8. В случае успеха возвращает ответ сервера, в противном случае выдает error_proto. Указывается в RFC 6856.

Added in version 3.5.

POP3.stls(context=None)

Начать сеанс TLS на активном соединении, указанном в RFC 2595. Это разрешено только перед аутентификацией пользователя

Параметр context - это объект ssl.SSLContext, который позволяет объединить параметры конфигурации SSL, сертификаты и закрытые ключи в единую (потенциально долгоживущую) структуру. Пожалуйста, прочитайте Соображения безопасности о лучших практиках.

Этот метод поддерживает проверку имени хоста через ssl.SSLContext.check_hostname и индикацию имени сервера (см. ssl.HAS_SNI).

Added in version 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)

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