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

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

---

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

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

>>> s = nntplib.NNTP('news.gmane.io')
>>> 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.io')
>>> 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 верен, команды AUTHINFO USER и AUTHINFO PASS - используемый, чтобы опознать и подтвердить подлинность пользователя к серверу. Если необязательный флаг readermode имеет значение true, то перед выполнением аутентификации отправляется команда mode reader. Режим читателя иногда необходим, если вы соединяетесь с сервером сППН на машине локальная и намереваетесь назвать определенные для читателя команды, такие как group. Если вы получаете непредвиденный NNTPPermanentErrors, возможно, вам потребуется установить readermode. Класс NNTP поддерживает with инструкция для безусловного использования исключений OSError и закрытия соединения NNTP по завершении, например:

>>> from nntplib import NNTP
>>> with NNTP('news.gmane.io') as n:
...     n.group('gmane.comp.python.committers')
... # doctest: +SKIP
('211 1755 1 1755 gmane.comp.python.committers', 1755, 1, 1755, 'gmane.comp.python.committers')
>>>

Raises an auditing event nntplib.connect with arguments self, host, port.

Все команды поднимут auditing event nntplib.putline с аргументами self и line, где line - это байты, отправляемые удаленному узлу.

Изменено в версии 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-on-563 не поощряется на RFC 4642, в пользу STARTTLS, как описано ниже. Однако некоторые серверы поддерживают только первые.

Raises an auditing event nntplib.connect with arguments self, host, port.

Все команды поднимут событие аудита nntplib.putline с аргументами self и line, где line - это байты, отправляемые удаленному узлу.

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

Изменено в версии 3.4: Теперь класс поддерживает проверку имени хоста с помощью ssl.SSLContext.check_hostname и Server Name Indication (см. 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

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

Объекты NNTP

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

Признаки

NNTP.nntp_version

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

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

NNTP.nntp_implementation

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

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

Методы

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

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

Изменено в версии 3.2: Многие из следующих методов были переработаны и исправлены, что делает их несовместимыми с их 3.1 аналогами.

NNTP.quit()

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

NNTP.getwelcome()

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

NNTP.getcapabilities()

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

>>> s = NNTP('news.gmane.io')
>>> '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) # doctest: +SKIP
85
>>> groups[0] # doctest: +SKIP
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 - wildmat строка, как указано в RFC 3977 (по сути, она совпадает с подстановочным знаком оболочки DOS или UNIX строки). Возвращает пара (response, descriptions), где descriptions - словарь, сопоставляющий имена групп текстовым описаниям.

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

NNTP.description(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. lines возвращенный (или записанный в file) будет содержать только заголовки сообщений, а не тело.

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

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

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. Возвращает response сервера.

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 не активно используемый.

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

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

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'