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

Данный модуль определяет класс NNTP, реализующий клиентскую часть протокола передачи сетевых новостей. Его можно использовать для реализации программы чтения новостей или плакатов, а также автоматических обработчиков новостей. Он совместим с 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('digitology.tech')
>>> 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 установлен, то перед выполнением аутентификации отправляется команда mode reader. Режим чтения иногда необходим, если вы подключаетесь к серверу NNTP на локальном компьютере и собираетесь вызывать команды, специфичные для чтения, такие как group. Если вы получаете неожиданные исключения NNTPPermanentError, вам может потребоваться установить 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')
>>>

Вызывает событие аудита nntplib.connect с аргументами self, host, port.

Все команды вызовут событие аудита 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, как приведено ниже. Однако некоторые серверы поддерживают только первое.

Вызывает событие аудита nntplib.connect с аргументами self, host, port.

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

Добавлено в версии 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

Исключение вызывается, когда в данных ответа есть какая-то ошибка.

Объекты NNTP

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

Атрибуты

NNTP.nntp_version

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

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

NNTP.nntp_implementation

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

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

Методы

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

Многие из следующих методов принимают необязательный ключевой аргумент 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 имеют значение истина, по возможности будут использоваться учётные данные из ~/.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 и Индикации имени сервера (см. 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 — это строка с подстановочными знаками, как указано в 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'