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)
В конце модуля есть тестовый раздел, содержащий более подробный пример использования.