Документация Python неофициальный перевод
Содержание страницы

20.11. nntplib – клиент протокола NNTPnntplib – NNTP protocol client

Исходный код: Lib/nntplib.py

Этот модуль определяет класс NNTP, который реализует клиентскую сторону протокола NNTP. Он может использоваться для создания программы чтения новостей или автоматических обработчиков новостей. Для получения дополнительной информации о NNTP (Network News Transfer Protocol, протоколе передачи новостей), см. Internet RFC 977.

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

>>> 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!'

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

>>> s = NNTP('news.gmane.org')
>>> f = open('articlefile')
>>> s.post(f)
'240 Article posted successfully.'
>>> s.quit()
'205 Bye!'

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

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

Возвращает новый экземпляр класса NNTP, представляющий подключение к серверу NNTP, работающему на узле host, прослушивающему порт port. По умолчанию порт port – 119. Если указаны необязательные user и password, или если соответствующие учетные данные присутствуют в /.netrc и необязательный флаг usenetrc истинен (по умолчанию), то для идентификации и аутентификации пользователя на сервере используются команды AUTHINFO USER и AUTHINFO PASS. Если необязательный флаг readermode истинен, то команда mode reader отправляется перед выполнением аутентификации. Режим чтения иногда необходим если вы подключаетесь к серверу NNTP на локальной машине и собираетесь вызывать команды, специфичные для режима чтения, такие как group. Если вы получаете неожиданные NNTPPermanentError, возможно, вам потребуется установить readermode. readermode по умолчанию равен None. usenetrc по умолчанию равен True.

Изменено в версии 2.4: добавлен аргумент usenetrc.

exception nntplib.NNTPError

Производный от стандартного исключения 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.11.1. Объекты NNTPNNTP Objects

Экземпляры 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 – файловый объект, то он начнет вызывать write() для сохранения строк вывода команды. Если указан file, то возвращаемый list будет пустым списком.

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

Отправляет команду NEWNEWS. Здесь group – имя группы или '*', а date и time имеют то же значение, что и для newgroups(). Возвращает пару (response, articles), где articles – это список идентификаторов сообщений. Если указан параметр file, то вывод команды NEWNEWS сохраняется в файл. Если file – строка, то метод откроет файловый объект с этим именем, запишет в него и закроет. Если file – файловый объект, то он начнет вызывать write() для сохранения строк вывода команды. Если указан file, то возвращаемый list будет пустым списком.

NNTP.list([file])

Отправляет команду LIST. Возвращает пару (response, list), где list – список кортежей. Каждый кортеж имеет вид (group, last, first, flag), где group – имя группы, last и first – номера последней и первой статей (в виде строк), а flag равен 'y', если отправка разрешена, 'n', если нет, и 'm', если группа модерируется. (Обратите внимание на порядок: last, first.) Если указан параметр file, то вывод команды LIST сохраняется в файл. Если file – строка, то метод откроет файловый объект с этим именем, запишет в него и закроет. Если file – файловый объект, то он начнет вызывать write() для сохранения строк вывода команды. Если указан file, то возвращаемый list будет пустым списком.

NNTP.descriptions(grouppattern)

Отправляет команду LIST NEWSGROUPS, где grouppattern – строка wildmat, как указано в RFC2980 (по сути, это то же самое, что строки подстановки DOS или UNIX shell strings). Возвращает пару (response, list), где list – список кортежей, содержащих (name, title).

Новое в версии 2.4.

NNTP.description(group)

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

Этот метод скрывает код ответа от сервера. Если код ответа необходим, используйте descriptions().

Новое в версии 2.4.

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 – файловый объект, то он начнет вызывать write() для сохранения строк вывода команды. Если указан file, то возвращаемый list будет пустым списком.

NNTP.stat(id)

Отправляет команду STAT, где id – идентификатор сообщения (заключенный в '<' и '>') или номер статьи (в виде строки). Возвращает тройку (response, number, id), где number – номер статьи (в виде строки), а id – идентификатор сообщения (заключенный в '<' и '>').

NNTP.next()

Отправляет команду NEXT. Возвращаемое значение такое же, как для stat().

NNTP.last()

Отправляет команду LAST. Возвращаемое значение такое же, как для stat().

NNTP.head(id)

Отправляет команду HEAD, где id имеет то же значение, что и для stat(). Возвращает кортеж (response, number, id, list), где первые три элемента те же, что и для stat(), а list – список заголовков статьи (неинтерпретированный список строк, без завершающих символов новой строки).

NNTP.body(id[, file])

Отправляет команду BODY, где id имеет то же значение, что и для stat(). Если указан параметр file, то тело сохраняется в файл. Если file – строка, то метод откроет файловый объект с этим именем, запишет в него и закроет. Если file – файловый объект, то он начнет вызывать write() для сохранения строк тела. Возвращает то же, что и head(). Если указан file, то возвращаемый list будет пустым списком.

NNTP.article(id)

Отправляет команду ARTICLE, где id имеет то же значение, что и для stat(). Возвращает то же, что и head().

NNTP.slave()

Отправляет команду SLAVE. Возвращает ответ сервера.

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 – файловый объект, то он начнет вызывать write() для сохранения строк вывода команды. Если указан file, то возвращаемый list будет пустым списком.

NNTP.post(file)

Отправляет статью с помощью команды POST. Аргумент file – открытый файловый объект, который читается до конца (EOF) с помощью его метода readline(). Это должна быть правильно оформленная новостная статья, включающая необходимые заголовки. Метод post() автоматически экранирует строки, начинающиеся с ..

NNTP.ihave(id, file)

Отправляет команду IHAVE. id – это идентификатор сообщения (заключённый в '<' и '>'). Если ответ не является ошибкой, обрабатывайте file точно так же, как для метода post().

NNTP.date()

Возвращает тройку (response, date, time), содержащую текущие дату и время в формате, подходящем для методов newnews() и newgroups(). Это необязательное расширение NNTP, которое может не поддерживаться всеми серверами.

NNTP.xgtitle(name[, file])

Обрабатывает команду XGTITLE, возвращая пару (response, list), где list – это список кортежей, содержащих (name, title). Если передан параметр file, то вывод команды XGTITLE сохраняется в файл. Если file – строка, метод откроет файловый объект с таким именем, запишет в него, а затем закроет. Если file – файловый объект, то метод начнёт вызывать для него write(), сохраняя строки вывода команды. Если file передан, то возвращаемый list будет пустым списком. Это необязательное расширение NNTP, которое может не поддерживаться всеми серверами.

RFC2980 гласит: «Рекомендуется отказаться от этого расширения». Используйте descriptions() или description() вместо него.

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

Возвращает пару (resp, list). list – это список кортежей, по одному для каждой статьи в диапазоне, ограниченном номерами статей от start до end. Каждый кортеж имеет вид (article number, subject, poster, date, id, references, size, lines). Если передан параметр file, то вывод команды XOVER сохраняется в файл. Если file – строка, метод откроет файловый объект с таким именем, запишет в него, а затем закроет. Если file – файловый объект, то метод начнёт вызывать для него write(), сохраняя строки вывода команды. Если передан file, то возвращаемый list будет пустым списком. Это необязательное расширение NNTP, которое может не поддерживаться всеми серверами.

NNTP.xpath(id)

Возвращает пару (resp, path), где path – это путь к каталогу статьи с идентификатором сообщения id. Это необязательное расширение NNTP, которое может не поддерживаться всеми серверами.

NNTP.quit()

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