nntplib — Клиент протокола NNTP

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

В этом модуле определён класс NNTP, реализующий клиентскую часть протокола NNTP. Его можно использовать для реализации новостного читателя или постинга, или автоматизированных обработчиков новостей. Более подробную информацию о протоколе NNTP (Network News Transfer Protocol) можно найти в интернет-документе 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 имеет значение true (по умолчанию), используются команды AUTHINFO USER и AUTHINFO PASS для идентификации и аутентификации пользователя на сервере. Если опциональный флаг readermode имеет значение true, то перед выполнением аутентификации отправляется команда 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 эквивалентно этому классу.

1. Объекты NNTP

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

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 — строка подстановок, как указано в RFC2980 (по сути, она такая же, как в командной строке DOS или UNIX). Возвращает пару (response, list), где list — список кортежей, содержащих (name, title).

Добавлена в версии 2.4.

NNTP.description(group)

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

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

NNTP.post(file): Опубликовать статью с помощью команды POST. Аргумент file — открытый объект файла, который читается до конца файла с помощью метода 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 вызывать нельзя.