# `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 WASI.

This module does not work or is not available on WebAssembly. 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)

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