`poplib.md`

176 строк · 15.6 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.15/library/poplib.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `poplib` – клиент протокола POP389**Исходный код:** [Lib/poplib.py](https://python-all.ru/src/3.15/Lib/poplib.py)1011---1213Этот модуль определяет класс [`POP3`](https://python-all.ru/3.15/library/poplib.html#poplib.POP3), который инкапсулирует соединение с POP3-сервером и реализует протокол, определённый в [**RFC 1939**](https://python-all.ru/3.15/library/poplib.html). Класс `POP3` поддерживает как минимальный, так и дополнительный наборы команд из [**RFC 1939**](https://python-all.ru/3.15/library/poplib.html). Класс `POP3` также поддерживает команду `STLS`, введённую в [**RFC 2595**](https://python-all.ru/3.15/library/poplib.html), для обеспечения шифрованной связи по уже установленному соединению.1415Кроме того, этот модуль предоставляет класс [`POP3_SSL`](https://python-all.ru/3.15/library/poplib.html#poplib.POP3_SSL), который обеспечивает поддержку подключения к POP3-серверам, использующим SSL в качестве базового протокольного уровня.1617Обратите внимание, что POP3, хотя и широко поддерживается, устаревает. Качество реализации POP3-серверов сильно различается, и слишком многие из них довольно плохи. Если ваш почтовый сервер поддерживает IMAP, лучше использовать класс [`imaplib.IMAP4`](https://python-all.ru/3.15/library/imaplib.html#imaplib.IMAP4), так как IMAP-серверы, как правило, реализованы лучше.1819[Доступность](https://python-all.ru/3.15/library/intro.html#availability): не WASI.2021Этот модуль не работает или недоступен на WebAssembly. Подробнее см. [платформы WebAssembly](https://python-all.ru/3.15/library/intro.html#wasm-availability).2223Модуль `poplib` предоставляет два класса:2425#### `class poplib.POP3(host, port=POP3_PORT[, timeout])`2627Этот класс реализует собственно протокол POP3. Соединение создаётся при инициализации экземпляра. Если параметр *port* опущен, используется стандартный порт POP3 (110). Необязательный параметр *timeout* задаёт тайм-аут в секундах для попытки подключения (если не указан, будет использована глобальная настройка тайм-аута по умолчанию).2829Вызывает [событие аудита](https://python-all.ru/3.15/library/sys.html#auditing) `poplib.connect` с аргументами `self`, `host`, `port`.3031Все команды вызывают [событие аудита](https://python-all.ru/3.15/library/sys.html#auditing) `poplib.putline` с аргументами `self` и `line`, где `line` – это байты, которые будут отправлены удалённому хосту.3233Изменено в версии 3.9: Если параметр *timeout* установлен в ноль, будет возбуждено исключение [`ValueError`](https://python-all.ru/3.15/library/exceptions.html#ValueError), чтобы предотвратить создание неблокирующего сокета.3435#### `class poplib.POP3_SSL(host, port=POP3_SSL_PORT, *, timeout=None, context=None)`3637Это подкласс [`POP3`](https://python-all.ru/3.15/library/poplib.html#poplib.POP3), который подключается к серверу через SSL-шифрованный сокет. Если *port* не указан, используется порт 995 – стандартный порт POP3 через SSL. *timeout* работает так же, как в конструкторе `POP3`. *context* – необязательный объект [`ssl.SSLContext`](https://python-all.ru/3.15/library/ssl.html#ssl.SSLContext), который позволяет объединять параметры конфигурации SSL, сертификаты и закрытые ключи в единую (потенциально долгоживущую) структуру. Пожалуйста, прочтите [Рекомендации по безопасности](https://python-all.ru/3.15/library/ssl.html#ssl-security) для получения наилучших практик.3839Вызывает [событие аудита](https://python-all.ru/3.15/library/sys.html#auditing) `poplib.connect` с аргументами `self`, `host`, `port`.4041Все команды вызывают [событие аудита](https://python-all.ru/3.15/library/sys.html#auditing) `poplib.putline` с аргументами `self` и `line`, где `line` – это байты, которые будут отправлены удалённому хосту.4243Изменено в версии 3.2: Добавлен параметр *context*.4445Изменено в версии 3.4: Теперь класс поддерживает проверку имени хоста с помощью [`ssl.SSLContext.check_hostname`](https://python-all.ru/3.15/library/ssl.html#ssl.SSLContext.check_hostname) и *Server Name Indication* (см. [`ssl.HAS_SNI`](https://python-all.ru/3.15/library/ssl.html#ssl.HAS_SNI)).4647Изменено в версии 3.9: Если параметр *timeout* установлен в ноль, будет возбуждено исключение [`ValueError`](https://python-all.ru/3.15/library/exceptions.html#ValueError), чтобы предотвратить создание неблокирующего сокета.4849Изменено в версии 3.12: Устаревшие параметры *keyfile* и *certfile* были удалены.5051В модуле `poplib` определено одно исключение в качестве атрибута:5253#### `exception poplib.error_proto`5455Исключение, возбуждаемое при любых ошибках этого модуля (ошибки из модуля [`socket`](https://python-all.ru/3.15/library/socket.html#module-socket) не перехватываются). Причина исключения передаётся конструктору в виде строки.5657> **См. также**58>59> **Модуль [`imaplib`](https://python-all.ru/3.15/library/imaplib.html#module-imaplib)**60>61> Стандартный модуль Python для IMAP.62>63> **[Часто задаваемые вопросы о Fetchmail](https://python-all.ru/3.15/library/poplib.html)**64>65> FAQ для POP/IMAP-клиента **fetchmail** содержит информацию о вариациях POP3-серверов и несоблюдении RFC, которая может быть полезна, если вам нужно написать приложение на основе протокола POP.6667## Объекты POP36869Все команды POP3 представлены методами с теми же именами в нижнем регистре; большинство возвращает текст ответа, отправленный сервером.7071Экземпляр [`POP3`](https://python-all.ru/3.15/library/poplib.html#poplib.POP3) имеет следующие методы:7273#### `POP3.set_debuglevel(level)`7475Устанавливает уровень отладки экземпляра. Это контролирует объём выводимой отладочной информации. Значение по умолчанию, `0`, не даёт отладочного вывода. Значение `1` даёт умеренный объём отладочного вывода, как правило, одну строку на запрос. Значение `2` или выше даёт максимальный объём отладочного вывода, с записью каждой строки, отправленной и полученной по управляющему соединению.7677#### `POP3.getwelcome()`7879Возвращает приветственную строку, отправленную POP3-сервером.8081#### `POP3.capa()`8283Запрашивает возможности сервера, как указано в [**RFC 2449**](https://python-all.ru/3.15/library/poplib.html). Возвращает словарь в формате `{'name': ['param'...]}`.8485Добавлено в версии 3.4.8687#### `POP3.user(username)`8889Отправляет команду USER; ответ должен указать, что требуется пароль.9091#### `POP3.pass_(password)`9293Отправляет пароль; ответ включает количество сообщений и размер почтового ящика. Примечание: почтовый ящик на сервере блокируется до вызова [`quit()`](https://python-all.ru/3.15/library/poplib.html#poplib.POP3.quit).9495#### `POP3.apop(user, secret)`9697Использует более безопасную аутентификацию APOP для входа на POP3-сервер.9899#### `POP3.rpop(user)`100101Использует аутентификацию RPOP (аналогично UNIX-командам r-\*) для входа на POP3-сервер.102103#### `POP3.stat()`104105Получает статус почтового ящика. Результат – кортеж из двух целых чисел: `(message count, mailbox size)`.106107#### `POP3.list([which])`108109Запрашивает список сообщений; результат возвращается в формате `(response, ['mesg_num octets', ...], octets)`. Если задан *which*, это номер сообщения для вывода списка.110111#### `POP3.retr(which)`112113Извлекает сообщение номер *which* целиком и устанавливает его флаг прочитанности. Результат возвращается в формате `(response, ['line', ...], octets)`.114115#### `POP3.dele(which)`116117Помечает сообщение номер *which* для удаления. На большинстве серверов удаление фактически не выполняется до команды QUIT (основное исключение – Eudora QPOP, который намеренно нарушает RFC, выполняя отложенные удаления при любом разрыве соединения).118119#### `POP3.rset()`120121Удаляет все пометки удаления для почтового ящика.122123#### `POP3.noop()`124125Ничего не делает. Может использоваться для поддержания соединения.126127#### `POP3.quit()`128129Завершение сеанса: фиксирует изменения, разблокирует почтовый ящик, закрывает соединение.130131#### `POP3.top(which, howmuch)`132133Извлекает заголовок сообщения и *howmuch* строк после заголовка сообщения номер *which*. Результат возвращается в формате `(response, ['line', ...], octets)`.134135Команда TOP POP3, используемая этим методом, в отличие от команды RETR, не устанавливает флаг прочитанности сообщения; к сожалению, TOP плохо специфицирован в RFC и часто некорректно работает на серверах малоизвестных производителей. Перед использованием этого метода проверьте его вручную на тех POP3-серверах, с которыми вы будете работать, прежде чем доверять ему.136137#### `POP3.uidl(which=None)`138139Возвращает список дайджестов сообщений (уникальных идентификаторов). Если указан *which*, результат содержит уникальный идентификатор для этого сообщения в формате `'response mesgnum uid`, в противном случае результат – список `(response, ['mesgnum uid', ...], octets)`.140141#### `POP3.utf8()`142143Пытается переключиться в режим UTF-8. В случае успеха возвращает ответ сервера, в противном случае возбуждает [`error_proto`](https://python-all.ru/3.15/library/poplib.html#poplib.error_proto). Описано в [**RFC 6856**](https://python-all.ru/3.15/library/poplib.html).144145Добавлено в версии 3.5.146147#### `POP3.stls(context=None)`148149Запускает сеанс TLS на активном соединении, как описано в [**RFC 2595**](https://python-all.ru/3.15/library/poplib.html). Это разрешено только до аутентификации пользователя.150151Параметр *context* – это объект [`ssl.SSLContext`](https://python-all.ru/3.15/library/ssl.html#ssl.SSLContext), который позволяет объединять параметры конфигурации SSL, сертификаты и закрытые ключи в единую (потенциально долгоживущую) структуру. Рекомендуется прочитать раздел [Вопросы безопасности](https://python-all.ru/3.15/library/ssl.html#ssl-security) для получения наилучших практик.152153Этот метод поддерживает проверку имени хоста через [`ssl.SSLContext.check_hostname`](https://python-all.ru/3.15/library/ssl.html#ssl.SSLContext.check_hostname) и *Server Name Indication* (см. [`ssl.HAS_SNI`](https://python-all.ru/3.15/library/ssl.html#ssl.HAS_SNI)).154155Добавлено в версии 3.4.156157Экземпляры [`POP3_SSL`](https://python-all.ru/3.15/library/poplib.html#poplib.POP3_SSL) не имеют дополнительных методов. Интерфейс этого подкласса идентичен родительскому.158159## Пример POP3160161Вот минимальный пример (без проверки ошибок), который открывает почтовый ящик и извлекает и выводит все сообщения:162163```python164import getpass, poplib165166M = poplib.POP3('localhost')167M.user(getpass.getuser())168M.pass_(getpass.getpass())169numMessages = len(M.list()[1])170for i in range(numMessages):171    for j in M.retr(i+1)[1]:172        print(j)173```174175В конце модуля есть тестовый раздел, содержащий более полный пример использования.176