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

keyfile and certfile are a legacy alternative to context - they can point to PEM-formatted private key and certificate chain files, respectively, for the SSL connection.

Викликає подію аудиту 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.6: keyfile and certfile are deprecated in favor of context. Please use ssl.SSLContext.load_cert_chain() instead, or let ssl.create_default_context() select the system’s trusted CA certificates for you.

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

Один виняток визначено як атрибут модуля 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 lower-case; most return the response text sent by the server.

An POP3 instance has the following methods:

POP3.set_debuglevel(level)

Установіть рівень налагодження примірника. Це контролює кількість надрукованих виводів налагодження. Значення за замовчуванням, 0, не створює вихідних даних для налагодження. Значення 1 створює помірну кількість налагоджувальних виводів, як правило, один рядок на запит. Значення 2 або вище створює максимальну кількість налагоджувальних виводів, реєструючи кожен рядок, надісланий і отриманий через контрольне з’єднання.

POP3.getwelcome()

Повертає рядок привітання, надісланий сервером POP3.

POP3.capa()

Запитуйте можливості сервера, як зазначено в RFC 2449. Повертає словник у формі {'name': ['param'...]}.

Нове в версії 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.

Нове в версії 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).

Нове в версії 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)

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