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

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

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

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

>>> s = nntplib.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 1096 articles, range 1 to 1096
>>> resp, overviews = s.over((last - 9, last))
>>> for id, over in overviews:
...     print(id, nntplib.decode_header(over['subject']))
...
1087 Re: Commit privileges for Łukasz Langa
1088 Re: 3.2 alpha 2 freeze
1089 Re: 3.2 alpha 2 freeze
1090 Re: Commit privileges for Łukasz Langa
1091 Re: Commit privileges for Łukasz Langa
1092 Updated ssh key
1093 Re: Updated ssh key
1094 Re: Updated ssh key
1095 Hello fellow committers!
1096 Re: Hello fellow committers!
>>> s.quit()
'205 Bye!'

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

>>> s = nntplib.NNTP('news.gmane.org')
>>> f = open('article.txt', 'rb')
>>> s.post(f)
'240 Article posted successfully.'
>>> s.quit()
'205 Bye!'

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

class nntplib.NNTP(host, port=119, user=None, password=None, readermode=None, usenetrc=False[, timeout])

Возвращает новый объект NNTP, представляющий подключение к серверу NNTP, работающему на хосте host и прослушивающему порт port. Можно указать необязательное значение timeout для подключения сокета. Если указаны необязательные user и password, или если соответствующие учетные данные присутствуют в /.netrc и необязательный флаг usenetrc имеет значение True, то используются команды AUTHINFO USER и AUTHINFO PASS для идентификации и аутентификации пользователя на сервере. Если необязательный флаг readermode имеет значение True, то перед выполнением аутентификации отправляется команда mode reader. Режим чтения иногда необходим, если вы подключаетесь к серверу NNTP на локальной машине и планируете вызывать команды, специфичные для чтения, такие как group. Если вы получаете неожиданные ошибки NNTPPermanentError, вам может потребоваться установить readermode. Класс NNTP поддерживает оператор with для безусловного обработки исключений OSError и закрытия подключения к NNTP по завершении, например:

>>> from nntplib import NNTP
>>> with NNTP('news.gmane.org') as n:
...     n.group('gmane.comp.python.committers')
... 
('211 1755 1 1755 gmane.comp.python.committers', 1755, 1, 1755, 'gmane.comp.python.committers')
>>>

Изменено в версии 3.2: usenetrc теперь False по умолчанию.

Изменено в версии 3.3: Добавлена поддержка оператора with.

class nntplib.NNTP_SSL(host, port=563, user=None, password=None, ssl_context=None, readermode=None, usenetrc=False[, timeout])

Возвращает новый объект NNTP_SSL, представляющий зашифрованное подключение к серверу NNTP, работающему на хосте host и прослушивающему порт port. Объекты NNTP_SSL имеют те же методы, что и объекты NNTP. Если port опущен, используется порт 563 (NNTPS). ssl_context также является необязательным и представляет собой объект SSLContext. Пожалуйста, ознакомьтесь с разделом Учесть безопасность, чтобы узнать лучшие методы работы. Все остальные параметры ведут себя так же, как и для NNTP.

Обратите внимание, что SSL-на-563 не рекомендуется согласно RFC 4642 в пользу STARTTLS, как описано ниже. Однако некоторые серверы поддерживают только первый вариант.

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

Изменено в версии 3.4: Теперь класс поддерживает проверку имени хоста с помощью ssl.SSLContext.check_hostname и указанием имени сервера (см. ssl.HAS_SNI).

exception nntplib.NNTPError

Производный от стандартного исключения Exception, это базовый класс для всех исключений, генерируемых модулем nntplib. У экземпляров этого класса есть атрибут:

response

Ответ сервера, если доступен, в виде объекта str.

exception nntplib.NNTPReplyError

Исключение, генерируемое при получении неожиданного ответа от сервера.

exception nntplib.NNTPTemporaryError

Исключение, генерируемое при получении кода ответа в диапазоне 400–499.

exception nntplib.NNTPPermanentError

Исключение, генерируемое при получении кода ответа в диапазоне 500–599.

exception nntplib.NNTPProtocolError

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

exception nntplib.NNTPDataError

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

21.16.1. Объекты NNTP

При подключении объекты NNTP и NNTP_SSL поддерживают следующие методы и атрибуты.

21.16.1.1. Атрибуты

NNTP.nntp_version

Целое число, представляющее версию протокола NNTP, поддерживаемую сервером. На практике это должно быть 2 для серверов, объявляющих соответствие RFC 3977, и 1 для других.

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

NNTP.nntp_implementation

Строка, описывающая имя и версию программного обеспечения сервера NNTP, или None, если не указано сервером.

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

21.16.1.2. Методы

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

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

NNTP.quit()

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

NNTP.getwelcome()

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

NNTP.getcapabilities()

Возвращает возможности RFC 3977, объявленные сервером, в виде объекта dict, сопоставляющего имена возможностей со списками значений (возможно, пустых). На устаревших серверах, которые не понимают команду CAPABILITIES возвращается пустой словарь.

>>> s = NNTP('news.gmane.org')
>>> 'POST' in s.getcapabilities()
True

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

NNTP.login(user=None, password=None, usenetrc=True)

Отправляет команды AUTHINFO с именем пользователя и паролем. Если user и password None и usenetrc имеет значение True, учетные данные из ~/.netrc будут использоваться, если возможно.

Если не задерживать намеренно, вход обычно выполняется во время инициализации объекта NNTP, и отдельно вызывать эту функцию не нужно. Чтобы отложить аутентификацию, вы не должны указывать user или password при создании объекта и должны установить usenetrc в False.

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

NNTP.starttls(context=None)

Отправить команду STARTTLS. Это включит шифрование на соединении NNTP. Аргумент context является необязательным и должен быть объектом ssl.SSLContext. Для наилучшей практики ознакомьтесь с Рекомендациями по безопасности.

Обратите внимание, что это может быть выполнено не после передачи информации об аутентификации, и аутентификация происходит по умолчанию, если возможно, во время инициализации объекта NNTP. Для получения информации о подавлении этого поведения см. NNTP.login().

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

Изменено в версии 3.4: Теперь метод поддерживает проверку имени хоста с помощью ssl.SSLContext.check_hostname и Server Name Indication (см. ssl.HAS_SNI).

NNTP.newgroups(date, *, file=None)

Отправить команду NEWGROUPS. Аргумент date должен быть объектом datetime.date или datetime.datetime. Возвращает пару (response, groups), где groups — список, представляющий группы, которые появились после заданной даты date. Однако, если указан аргумент file, то groups будет пустым.

>>> from datetime import date, timedelta
>>> resp, groups = s.newgroups(date.today() - timedelta(days=3))
>>> len(groups) 
85
>>> groups[0] 
GroupInfo(group='gmane.network.tor.devel', last='4', first='1', flag='m')

NNTP.newnews(group, date, *, file=None)

Отправить команду NEWNEWS. Здесь group — имя группы или '*', а date имеет то же значение, что и для newgroups(). Возвращает пару (response, articles), где articles — список идентификаторов сообщений.

Эта команда часто отключается администраторами серверов NNTP.

NNTP.list(group_pattern=None, *, file=None)

Отправить команду LIST или LIST ACTIVE . Возвращает пару (response, list), где list — список кортежей, представляющих все доступные группы на этом сервере NNTP, необязательно соответствующие шаблону строки group_pattern. Каждый кортеж имеет вид (group, last, first, flag), где group — имя группы, last и first — номера последнего и первого сообщения, а flag обычно принимает одно из этих значений:

• y: Разрешены локальные публикации и сообщения от других пользователей.
• m: Группа модерации, и все публикации должны быть одобрены.
• n: Не разрешены локальные публикации, только сообщения от других пользователей.
• j: Сообщения от других пользователей помещаются в группу спама.
• x: Не разрешены локальные публикации, и сообщения от других пользователей игнорируются.
• =foo.bar: Сообщения помещаются в группу foo.bar.

Если flag имеет другое значение, то состояние новостной группы считается неизвестным.

Эта команда может возвращать очень большие результаты, особенно если group_pattern не указан. Лучше кешировать результаты офлайн, если вам не нужно их обновлять.

Изменено в версии 3.2: Добавлен параметр group_pattern.

NNTP.descriptions(grouppattern)

Отправить команду LIST NEWSGROUPS, где grouppattern — строка подстановочных значений, как указано в RFC 3977 (по сути, такие же, как в DOS или UNIX shell). Возвращает пару (response, descriptions), где descriptions — словарь, сопоставляющий имена групп текстовым описаниям.

>>> resp, descs = s.descriptions('gmane.comp.python.*')
>>> len(descs) 
295
>>> descs.popitem() 
('gmane.comp.python.bio.general', 'BioPython discussion list (Moderated)')

NNTP.description(group)

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

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

NNTP.group(name)

Отправить команду GROUP, где name — имя группы. Группа выбирается в качестве текущей, если она существует. Возвращает кортеж (response, count, first, last, name), где count — (приблизительное) количество сообщений в группе, first — номер первого сообщения в группе, last — номер последнего сообщения в группе, а name — имя группы.

NNTP.over(message_spec, *, file=None)

Отправить команду OVER или команду XOVER на серверах устаревшего типа. message_spec может быть либо строкой, представляющей идентификатор сообщения, либо кортежем (first, last) чисел, указывающим диапазон статей в текущей группе, или кортежем (first, None) чисел, указывающим диапазон статей с first до последней статьи в текущей группе, или None для выбора текущей статьи в текущей группе.

Возвращает пару (response, overviews). overviews — список кортежей (article_number, overview), по одному для каждой статьи, выбранной message_spec. Каждый overview — это словарь с таким же количеством элементов, но это количество зависит от сервера. Эти элементы — либо заголовки сообщений (ключ — тогда имя заголовка в нижнем регистре), либо метаданные (ключ — тогда имя метаданных, префикс ":"). Следующие элементы гарантированно присутствуют по спецификации NNTP:

• заголовки subject, from, date, message-id и references
• метаданные :bytes: количество байтов в всей исходной статье (включая заголовки и тело)
• метаданные :lines: количество строк в теле статьи

Значение каждого элемента — либо строка, либо None, если элемент отсутствует.

Рекомендуется использовать функцию decode_header() для значений заголовков, когда они могут содержать не-ASCII символы:

>>> _, _, first, last, _ = s.group('gmane.comp.python.devel')
>>> resp, overviews = s.over((last, last))
>>> art_num, over = overviews[0]
>>> art_num
117216
>>> list(over.keys())
['xref', 'from', ':lines', ':bytes', 'references', 'date', 'message-id', 'subject']
>>> over['from']
'=?UTF-8?B?Ik1hcnRpbiB2LiBMw7Z3aXMi?= <martin@v.loewis.de>'
>>> nntplib.decode_header(over['from'])
'"Martin v. Löwis" <martin@v.loewis.de>'

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

NNTP.help(*, file=None)

Отправить команду HELP. Возвращает пару (response, list), где list — список строк помощи.

NNTP.stat(message_spec=None)

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

>>> _, _, first, last, _ = s.group('gmane.comp.python.devel')
>>> resp, number, message_id = s.stat(first)
>>> number, message_id
(9099, '<20030112190404.GE29873@epoch.metaslash.com>')

NNTP.next()

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

NNTP.last()

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

NNTP.article(message_spec=None, *, file=None)

Отправить команду ARTICLE, где message_spec имеет то же значение, что и для stat(). Возвращает кортеж (response, info), где info — namedtuple с тремя атрибутами number, message_id и lines (в указанном порядке). number — номер статьи в группе (или 0, если информация недоступна), message_id — идентификатор сообщения в виде строки, а lines — список строк (без завершающих символов новой строки), составляющих исходное сообщение, включая заголовки и тело.

>>> resp, info = s.article('<20030112190404.GE29873@epoch.metaslash.com>')
>>> info.number
0
>>> info.message_id
'<20030112190404.GE29873@epoch.metaslash.com>'
>>> len(info.lines)
65
>>> info.lines[0]
b'Path: main.gmane.org!not-for-mail'
>>> info.lines[1]
b'From: Neal Norwitz <neal@metaslash.com>'
>>> info.lines[-3:]
[b'There is a patch for 2.3 as well as 2.2.', b'', b'Neal']

NNTP.head(message_spec=None, *, file=None)

То же, что и article(), но отправляет команду HEAD. Возвращаемые (или записываемые в file) строки lines будут содержать только заголовки сообщения, а не тело.

NNTP.body(message_spec=None, *, file=None)

То же, что и article(), но отправляет команду BODY. Возвращаемые (или записываемые в file) строки lines будут содержать только тело сообщения, а не заголовки.

NNTP.post(data)

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

Если метод выполняется успешно, возвращается ответ сервера. Если сервер отказывается от публикации, возникает ошибка NNTPReplyError.

NNTP.ihave(message_id, data)

Отправить команду IHAVE. message_id — это идентификатор сообщения, которое нужно отправить на сервер (окруженный '<' и '>'). Параметр data и возвращаемое значение такие же, как и для post().

NNTP.date()

Возвращает пару (response, date). date — объект datetime, содержащий текущую дату и время сервера.

NNTP.slave()

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

NNTP.set_debuglevel(level)

Установить уровень отладки экземпляра. Это контролирует количество выводимой информации об отладке. По умолчанию, 0, вывод отладки не отображается. Значение 1 отображает умеренное количество информации об отладке, как правило, одна строка на запрос или ответ. Значение 2 или выше отображает максимальное количество информации об отладке, регистрируя каждую отправленную и полученную строку по подключению (включая текст сообщения).

Ниже приведены необязательные расширения NNTP, определенные в RFC 2980. Некоторые из них были заменены новыми командами в RFC 3977.

NNTP.xhdr(hdr, str, *, file=None)

Отправить команду XHDR . Аргумент hdr — это ключевое слово заголовка, например 'subject'. Аргумент str должен иметь вид 'first-last', где first и last — это первые и последние номера статей для поиска. Возвращает пару (response, list), где list — список пар (id, text), где id — номер статьи (в виде строки) и text — текст запрошенного заголовка для этой статьи. Если параметр file указан, то вывод команды XHDR сохраняется в файле. Если file — строка, то метод откроет файл с этим именем, запишет в него данные, а затем закроет его. Если file — объект объекта файла, то он будет вызывать write() для записи строк вывода команды. Если file указан, то возвращаемый list — пустой список.

NNTP.xover(start, end, *, file=None)

Отправить команду XOVER. start и end — номера статей, определяющие диапазон выбираемых статей. Возвращаемое значение такое же, как и для over(). Рекомендуется использовать over(), так как он автоматически будет использовать новую команду OVER , если она доступна.

NNTP.xpath(id)

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

Устарело начиная с версии 3.3: Расширение XPATH не активно используется.

21.16.2. Служебные функции

В модуле также определена следующая служебная функция:

nntplib.decode_header(header_str)

Декодирует значение заголовка, снимая экранирование любых экранированных символов, не входящих в ASCII. header_str должен быть объектом str. Возвращается неэкранированное значение. Рекомендуется использовать эту функцию для отображения некоторых заголовков в удобочитаемой форме:

>>> decode_header("Some subject")
'Some subject'
>>> decode_header("=?ISO-8859-15?Q?D=E9buter_en_Python?=")
'Débuter en Python'
>>> decode_header("Re: =?UTF-8?B?cHJvYmzDqG1lIGRlIG1hdHJpY2U=?=")
'Re: problème de matrice'