# `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)

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