Содержание страницы
21.14. poplib – клиент протокола POP3¶poplib – POP3 protocol client
Исходный код: 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 не перехватываются). Причина исключения передаётся конструктору в виде строки.
См. также
- Модуль imaplib
- Стандартный модуль Python для IMAP.
- Часто задаваемые вопросы о Fetchmail
- FAQ для POP/IMAP-клиента fetchmail содержит информацию о вариациях POP3-серверов и несоблюдении RFC, которая может быть полезна, если вам нужно написать приложение на основе протокола POP.
21.14.1. Объекты POP3¶POP3 Objects
Все команды POP3 представлены одноимёнными методами в нижнем регистре; большинство из них возвращает текст ответа, отправленный сервером.
Экземпляр POP3 имеет следующие методы:
- POP3.set_debuglevel(level)¶
Устанавливает уровень отладки экземпляра. Это контролирует объём выводимой отладочной информации. Значение по умолчанию, 0, не даёт отладочного вывода. Значение 1 даёт умеренный объём отладочного вывода, как правило, одну строку на запрос. Значение 2 или выше даёт максимальный объём отладочного вывода, с записью каждой строки, отправленной и полученной по управляющему соединению.
- POP3.getwelcome()¶
Возвращает приветственную строку, отправленную POP3-сервером.
- POP3.capa()¶
Запрашивает возможности сервера, как указано в RFC 2449. Возвращает словарь вида {'name': ['param'...]}.
Новое в версии 3.4.
- POP3.user(username)¶
Отправляет команду USER; ответ должен указать, что требуется пароль.
- POP3.pass_(password)¶
Отправляет пароль, ответ включает количество сообщений и размер почтового ящика. Примечание: почтовый ящик на сервере блокируется до вызова quit().
- POP3.apop(user, secret)¶
Использует более безопасную аутентификацию APOP для входа на POP3-сервер.
- POP3.rpop(user)¶
Использует аутентификацию RPOP (аналогично UNIX-командам r-*) для входа на POP3-сервер.
- POP3.stat()¶
Получает статус почтового ящика. Результат – кортеж из двух целых чисел: (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).
Команда TOP POP3, используемая этим методом, в отличие от команды RETR, не устанавливает флаг прочитанности сообщения; к сожалению, TOP плохо специфицирован в RFC и часто некорректно работает на серверах малоизвестных производителей. Перед использованием этого метода проверьте его вручную на тех POP3-серверах, с которыми вы будете работать, прежде чем доверять ему.
- POP3.uidl(which=None)¶
Возвращает список дайджестов сообщений (уникальных идентификаторов). Если указан which, результат содержит уникальный идентификатор для этого сообщения в формате 'response mesgnum uid, в противном случае результат представляет собой список (response, ['mesgnum uid', ...], octets).
- POP3.stls(context=None)¶
Запускает сеанс TLS на активном соединении, как описано в RFC 2595. Это разрешено только до аутентификации пользователя.
Параметр context представляет собой объект ssl.SSLContext, который позволяет объединять параметры конфигурации SSL, сертификаты и закрытые ключи в единую (потенциально долгоживущую) структуру. Для получения рекомендаций по использованию прочтите рекомендации по безопасности.
Этот метод поддерживает проверку имени хоста с помощью ssl.SSLContext.check_hostname и индикации имени сервера (см. ssl.HAS_SNI).
Новое в версии 3.4.
Экземпляры POP3_SSL не имеют дополнительных методов. Интерфейс этого подкласса идентичен родительскому.
21.14.2. Пример POP3¶POP3 Example
Вот минимальный пример (без проверки ошибок), который открывает почтовый ящик и извлекает и выводит все сообщения:
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)
В конце модуля есть тестовый раздел, содержащий более полный пример использования.