> **Источник:** https://python-all.ru/3.1/library/nntplib.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# 20.14. `nntplib` – клиент протокола NNTP

Этот модуль определяет класс [`NNTP`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP), который реализует клиентскую сторону протокола NNTP. Его можно использовать для создания программы чтения новостей, отправки сообщений или автоматической обработки новостей. Дополнительную информацию о NNTP (Network News Transfer Protocol, протокол передачи сетевых новостей) см. в [**RFC 977**](https://python-all.ru/3.1/library/nntplib.html).

Вот два небольших примера использования. Чтобы вывести статистику по группе новостей и напечатать темы последних 10 статей:

```python
>>> s = NNTP('news.gmane.org')
>>> resp, count, first, last, name = s.group('gmane.comp.python.committers')
>>> print('Group', name, 'has', count, 'articles, range', first, 'to', last)
Group gmane.comp.python.committers has 1071 articles, range 1 to 1071
>>> resp, subs = s.xhdr('subject', first + '-' + last)
>>> for id, sub in subs[-10:]: print(id, sub)
...
1062 Re: Mercurial Status?
1063 Re: [python-committers]  (Windows) buildbots on 3.x
1064 Re: Mercurial Status?
1065 Re: Mercurial Status?
1066 Python 2.6.6 status
1067 Commit Privileges for Ask Solem
1068 Re: Commit Privileges for Ask Solem
1069 Re: Commit Privileges for Ask Solem
1070 Re: Commit Privileges for Ask Solem
1071 2.6.6 rc 2
>>> s.quit()
'205 Bye!'
```

Чтобы отправить статью из файла (предполагается, что статья имеет корректные заголовки и у вас есть право публиковать сообщения в данной группе новостей):

```python
>>> s = NNTP('news.gmane.org')
>>> f = open('/tmp/article')
>>> s.post(f)
'240 Article posted successfully.'
>>> s.quit()
'205 Bye!'
```

Сам модуль определяет следующие элементы:

#### `class nntplib.NNTP(host[, port[, user[, password[, readermode][, usenetrc]]]])`

Возвращает новый экземпляр класса

[`NNTP`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP)

, представляющий подключение к серверу NNTP, работающему на узле

*host*

и ожидающему на порту

*port*

. По умолчанию

*port*

равен 119. Если указаны необязательные

*user*

и

*password*

, или если подходящие учётные данные есть в

`/.netrc`

и необязательный флаг

*usenetrc*

имеет значение true (по умолчанию), для идентификации и аутентификации пользователя на сервере используются команды

`AUTHINFO USER`

и

`AUTHINFO PASS`

. Если необязательный флаг

*readermode*

равен true, перед выполнением аутентификации отправляется команда

`mode reader`

. Режим чтения иногда требуется, если вы подключаетесь к серверу NNTP на локальной машине и собираетесь вызывать команды, специфичные для чтения, например

`group`

. Если возникают неожиданные

[`NNTPPermanentError`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTPPermanentError)

, возможно, потребуется установить

*readermode*

. Значением

*readermode*

по умолчанию является

`None`

. Значением

*usenetrc*

по умолчанию является

`True`

.

#### `exception nntplib.NNTPError`

Этот класс, производный от стандартного исключения

[`Exception`](https://python-all.ru/3.1/library/exceptions.html#Exception)

, является базовым для всех исключений, вызываемых модулем

`nntplib`

.

#### `exception nntplib.NNTPReplyError`

Исключение, вызываемое при получении от сервера неожиданного ответа. Для обратной совместимости исключение

`error_reply`

эквивалентно данному классу.

#### `exception nntplib.NNTPTemporaryError`

Исключение, вызываемое при получении кода ошибки в диапазоне 400–499. Для обратной совместимости исключение

`error_temp`

эквивалентно данному классу.

#### `exception nntplib.NNTPPermanentError`

Исключение, вызываемое при получении кода ошибки в диапазоне 500–599. Для обратной совместимости исключение

`error_perm`

эквивалентно данному классу.

#### `exception nntplib.NNTPProtocolError`

Исключение, вызываемое при получении от сервера ответа, который не начинается с цифры в диапазоне 1–5. Для обратной совместимости исключение

`error_proto`

эквивалентно данному классу.

#### `exception nntplib.NNTPDataError`

Исключение, вызываемое при ошибке в данных ответа. Для обратной совместимости исключение

`error_data`

эквивалентно данному классу.

## 20.14.1. Объекты NNTP

Экземпляры NNTP имеют следующие методы. *response*, возвращаемый как первый элемент кортежа результатов почти всех методов, – это ответ сервера: строка, начинающаяся с трёхзначного кода. Если ответ сервера указывает на ошибку, метод вызывает одно из перечисленных выше исключений.

#### `NNTP.getwelcome()`

Возвращает приветственное сообщение, отправленное сервером в ответ на начальное подключение. (Это сообщение иногда содержит отказ от ответственности или справочную информацию, которая может быть полезна пользователю.)

#### `NNTP.set_debuglevel(level)`

Устанавливает уровень отладки экземпляра. Он управляет объёмом выводимых отладочных сообщений. Значение по умолчанию,

`0`

, не выводит отладочные сообщения. Значение

`1`

выдаёт умеренное количество отладочной информации, обычно одну строку на запрос или ответ. Значение

`2`

или больше выводит максимальный объём отладочной информации, регистрируя каждую отправленную и полученную строку соединения (включая текст сообщения).

#### `NNTP.newgroups(date, time[, file])`

Отправляет команду

`NEWGROUPS`

. Аргумент

*date*

должен быть строкой вида

`'yymmdd'`

, указывающей дату, а

*time*

– строкой вида

`'hhmmss'`

, указывающей время. Возвращает пару

`(response, groups)`

, где

*groups*

– список названий групп, появившихся после указанной даты и времени. Если указан параметр

*file*

, вывод команды

`NEWGROUPS`

сохраняется в файл. Если

*file*

– строка, метод откроет файл с таким именем, запишет в него и закроет. Если

*file*

–

[*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object)

, то для сохранения строк вывода команды будет вызываться метод

`write()`

. Если

*file*

указан, возвращаемый

*список*

будет пустым.

#### `NNTP.newnews(group, date, time[, file])`

Отправляет команду

`NEWNEWS`

. Здесь

*group*

– название группы или

`'*'`

, а

*date*

и

*time*

имеют тот же смысл, что и для

[`newgroups()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.newgroups)

. Возвращает пару

`(response, articles)`

, где

*articles*

– список идентификаторов сообщений. Если указан параметр

*file*

, вывод команды

`NEWNEWS`

сохраняется в файл. Если

*file*

– строка, метод откроет файл с таким именем, запишет в него и закроет. Если

*file*

–

[*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object)

, то для сохранения строк вывода команды будет вызываться метод

`write()`

. Если

*file*

указан, возвращаемый

*список*

будет пустым.

#### `NNTP.list([file])`

Отправляет команду

`LIST`

. Возвращает пару

`(response, list)`

, где

*list*

– список кортежей. Каждый кортеж имеет вид

`(group, last, first, flag)`

, где

*group*

– название группы,

*last*

и

*first*

– последний и первый номера статей (в виде строк), а

*flag*

равен

`'y'`

, если публикация разрешена,

`'n'`

– если нет, и

`'m'`

– если группа модерируется. (Обратите внимание на порядок:

*last*

, затем

*first*

.) Если указан параметр

*file*

, вывод команды

`LIST`

сохраняется в файл. Если

*file*

– строка, метод откроет файл с таким именем, запишет в него и закроет. Если

*file*

–

[*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object)

, то для сохранения строк вывода команды будет вызываться метод

`write()`

. Если

*file*

указан, возвращаемый

*список*

будет пустым.

#### `NNTP.descriptions(grouppattern)`

Отправляет команду

`LIST NEWSGROUPS`

, где

*grouppattern*

– строка wildmat, как указано в RFC2980 (по сути, это те же шаблоны подстановки, что в DOS или UNIX). Возвращает пару

`(response, list)`

, где

*list*

– список кортежей, содержащих

`(name, title)`

.

#### `NNTP.description(group)`

Получает описание для одной группы *group*. Если совпадает несколько групп (если ‘group’ – это строка шаблона wildmat), возвращается первое совпадение. Если ни одна группа не совпадает, возвращается пустая строка.

Этот метод опускает код ответа сервера. Если код ответа нужен, используйте [`descriptions()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.descriptions).

#### `NNTP.group(name)`

Отправляет команду

`GROUP`

, где

*name*

– название группы. Возвращает кортеж

`(response, count, first, last, name)`

, где

*count*

– (оценочное) количество статей в группе,

*first*

– номер первой статьи в группе,

*last*

– номер последней статьи в группе, а

*name*

– название группы. Числа возвращаются в виде строк.

#### `NNTP.help([file])`

Отправляет команду

`HELP`

. Возвращает пару

`(response, list)`

, где

*list*

– список строк справки. Если указан параметр

*file*

, вывод команды

`HELP`

сохраняется в файл. Если

*file*

– строка, метод откроет файл с таким именем, запишет в него и закроет. Если

*file*

–

[*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object)

, то для сохранения строк вывода команды будет вызываться метод

`write()`

. Если

*file*

указан, возвращаемый

*список*

будет пустым.

#### `NNTP.stat(id)`

Отправляет команду

`STAT`

, где

*id*

– идентификатор сообщения (заключённый в

`'<'`

и

`'>'`

) или номер статьи (в виде строки). Возвращает тройку

`(response, number, id)`

, где

*number*

– номер статьи (в виде строки), а

*id*

– идентификатор сообщения (заключённый в

`'<'`

и

`'>'`

).

#### `NNTP.next()`

Отправляет команду

`NEXT`

. Возвращаемое значение – как у

[`stat()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.stat)

.

#### `NNTP.last()`

Отправляет команду

`LAST`

. Возвращаемое значение – как у

[`stat()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.stat)

.

#### `NNTP.head(id)`

Отправляет команду

`HEAD`

, где

*id*

имеет то же значение, что и для

[`stat()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.stat)

. Возвращает кортеж

`(response, number, id, list)`

, где первые три элемента такие же, как для

[`stat()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.stat)

, а

*list*

– это список заголовков статьи ( неинтерпретированный список строк без завершающих переводов строк).

#### `NNTP.body(id[, file])`

Отправляет команду

`BODY`

, где

*id*

имеет то же значение, что и для

[`stat()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.stat)

. Если указан параметр

*file*

, то тело сохраняется в файл. Если

*file*

– строка, то метод откроет файл с таким именем, запишет в него, а затем закроет. Если

*file*

–

[*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object)

, то он начнёт вызывать

`write()`

для него, чтобы сохранить строки тела. Возвращаемое значение такое же, как для

[`head()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.head)

. Если передан

*file*

, то возвращаемый

*список*

будет пуст.

#### `NNTP.article(id)`

Отправляет команду

`ARTICLE`

, где

*id*

имеет то же значение, что и для

[`stat()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.stat)

. Возвращаемое значение такое же, как для

[`head()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.head)

.

#### `NNTP.slave()`

Отправляет команду

`SLAVE`

. Возвращает

*response*

сервера.

#### `NNTP.xhdr(header, string[, file])`

Отправляет команду

`XHDR`

. Эта команда не определена в RFC, но является распространённым расширением. Аргумент

*header*

– это ключевое слово заголовка, например

`'subject'`

. Аргумент

*string*

должен иметь вид

`'first-last'`

, где

*first*

и

*last*

– это первый и последний номера статей для поиска. Возвращает пару

`(response, list)`

, где

*list*

– список пар

`(id, text)`

, где

*id*

– номер статьи (в виде строки), а

*text*

– текст запрошенного заголовка для этой статьи. Если передан параметр

*file*

, вывод команды

`XHDR`

сохраняется в файл. Если

*file*

– строка, метод откроет файл с таким именем, запишет в него и затем закроет. Если

*file*

– это

[*объект файла*](https://python-all.ru/3.1/glossary.html#term-file-object)

, то метод начнёт вызывать

`write()`

для сохранения строк вывода команды. Если

*file*

передан, возвращаемый

*list*

будет пустым списком.

#### `NNTP.post(file)`

Отправляет статью с помощью команды

`POST`

. Аргумент

*file*

– это открытый файловый объект, который читается до конца (EOF) с помощью его метода

`readline()`

. Это должна быть правильно оформленная новостная статья, включающая необходимые заголовки. Метод

[`post()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.post)

автоматически экранирует строки, начинающиеся с

`.`

.

#### `NNTP.ihave(id, file)`

Отправляет команду

`IHAVE`

.

*id*

– это идентификатор сообщения (заключённый в

`'<'`

и

`'>'`

). Если ответ не является ошибкой, обрабатывать

*file*

точно так же, как в методе

[`post()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.post)

.

#### `NNTP.date()`

Возвращает тройку

`(response, date, time)`

, содержащую текущую дату и время в форме, подходящей для методов

[`newnews()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.newnews)

и

[`newgroups()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.newgroups)

. Это необязательное расширение NNTP, которое может не поддерживаться всеми серверами.

#### `NNTP.xgtitle(name[, file])`

Обрабатывает команду `XGTITLE`, возвращая пару `(response, list)`, где *list* – это список кортежей, содержащих `(name, title)`. Если параметр *file* указан, то вывод команды `XGTITLE` сохраняется в файл. Если *file* – строка, то метод откроет файл с таким именем, запишет в него, а затем закроет. Если *file* – это [*file object*](https://python-all.ru/3.1/glossary.html#term-file-object), то он начнёт вызывать `write()` для сохранения строк вывода команды. Если *file* указан, то возвращаемый *list* будет пустым списком. Это необязательное расширение NNTP и может не поддерживаться всеми серверами.

В RFC2980 говорится: «Рекомендуется объявить это расширение устаревшим». Используйте [`descriptions()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.descriptions) или [`description()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.description) вместо него.

#### `NNTP.xover(start, end[, file])`

Возвращает пару

`(resp, list)`

.

*list*

– это список кортежей, по одному для каждой статьи в диапазоне, ограниченном номерами статей

*start*

и

*end*

. Каждый кортеж имеет вид

`(article number, subject, poster, date, id, references, size, lines)`

. Если параметр

*file*

указан, то вывод команды

`XOVER`

сохраняется в файл. Если

*file*

– строка, то метод откроет файл с таким именем, запишет в него, а затем закроет. Если

*file*

– это

[*file object*](https://python-all.ru/3.1/glossary.html#term-file-object)

, то он начнёт вызывать

`write()`

для сохранения строк вывода команды. Если

*file*

указан, то возвращаемый

*list*

будет пустым списком. Это необязательное расширение NNTP и может не поддерживаться всеми серверами.

#### `NNTP.xpath(id)`

Возвращает пару

`(resp, path)`

, где

*path*

– это путь к каталогу статьи с идентификатором сообщения

*id*

. Это необязательное расширение NNTP и может не поддерживаться всеми серверами.

#### `NNTP.quit()`

Отправляет команду

`QUIT`

и закрывает соединение. После вызова этого метода не следует вызывать другие методы объекта NNTP.