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 краще реалізовані.

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssembly platforms for more information.

Модуль poplib надає два класи:

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

Цей клас реалізує фактичний протокол POP3. Підключення створюється під час ініціалізації екземпляра. Якщо порт не вказано, використовується стандартний порт 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, *, timeout=None, context=None)

Це підклас POP3, який підключається до сервера через сокет, зашифрований SSL. Якщо порт не вказано, 995, використовується стандартний порт POP3 через SSL. timeout працює як у конструкторі POP3. context — це необов’язковий об’єкт ssl.SSLContext, який дозволяє об’єднувати параметри конфігурації SSL, сертифікати та приватні ключі в єдину (потенційно довговічну) структуру. Будь ласка, прочитайте Міркування безпеки, щоб дізнатися про найкращі практики.

Викликає подію аудиту poplib.connect з аргументами self, host, port.

Усі команди викличуть подію аудиту poplib.putline з аргументами self і line, де line — це байти, які мають бути надіслані на віддалений пристрій хост.

Змінено в версії 3.2: Додано параметр context.

Змінено в версії 3.4: The class now supports hostname check with ssl.SSLContext.check_hostname and Server Name Indication (see ssl.HAS_SNI).

Змінено в версії 3.9: Якщо параметр timeout дорівнює нулю, це викличе ValueError, щоб запобігти створенню неблокуючого сокета.

Змінено в версії 3.12: The deprecated keyfile and certfile parameters have been removed.

Один виняток визначено як атрибут модуля poplib:

exception poplib.error_proto

Виняток виникає при будь-яких помилках із цього модуля (помилки з модуля socket не переймаються). Причина винятку передається конструктору у вигляді рядка.

Дивись також

Модуль imaplib

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

Часті запитання про Fetchmail

Поширені запитання щодо POP/IMAP-клієнта fetchmail збирають інформацію про варіанти POP3-сервера та невідповідність RFC, що може бути корисним, якщо вам потрібно написати програму на основі протоколу POP.

Об’єкти POP3

All POP3 commands are represented by methods of the same name, in lowercase; most return the response text sent by the server.

A POP3 instance has the following methods:

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)

Send password, response includes message count and mailbox size. Note: the mailbox on the server is locked until quit() is called.

POP3.apop(user, secret)

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

POP3.rpop(user)

Використовуйте аутентифікацію RPOP (подібно до r-команд UNIX), щоб увійти на сервер POP3.

POP3.stat()

Отримати статус поштової скриньки. Результатом є кортеж із 2 цілих чисел: (кількість повідомлень, розмір поштової скриньки).

POP3.list([which])

Список повідомлень запиту, результат у формі (відповідь, ['mesg_num octets', ...], octets). Якщо встановлено which, це повідомлення для списку.

POP3.retr(which)

Отримайте повний номер повідомлення which і встановіть для нього позначку «переглянуто». Результат має форму (відповідь, ['рядок', ...], октети).

POP3.dele(which)

Позначити номер повідомлення яке для видалення. На більшості серверів видалення фактично не виконується, доки не буде вимкнено (основним винятком є Eudora QPOP, яка навмисно порушує RFC, виконуючи очікувані видалення під час будь-якого відключення).

POP3.rset()

Видаліть усі позначки видалення з поштової скриньки.

POP3.noop()

Нічого не робити. Може використовуватися як засіб підтримки життя.

POP3.quit()

Підпис: внести зміни, розблокувати поштову скриньку, розірвати з’єднання.

POP3.top(which, howmuch)

Отримує заголовок повідомлення плюс скільки рядків повідомлення після заголовка номера повідомлення which. Результат має форму (відповідь, ['рядок', ...], октети).

Команда 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.

Added in version 3.5.

POP3.stls(context=None)

Розпочніть сеанс TLS на активному з’єднанні, як зазначено в RFC 2595. Це дозволено лише перед автентифікацією користувача

Параметр context — це об’єкт ssl.SSLContext, який дозволяє об’єднувати параметри конфігурації SSL, сертифікати та приватні ключі в єдину (потенційно довговічну) структуру. Будь ласка, прочитайте Міркування безпеки, щоб дізнатися про найкращі практики.

This method supports hostname checking via ssl.SSLContext.check_hostname and Server Name Indication (see 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)

Наприкінці модуля є тестовий розділ, який містить докладніший приклад використання.