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')
... # doctest: +SKIP
('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 и 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

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

1. Объекты NNTP

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

1.1. Атрибуты

NNTP.nntp_version

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

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

NNTP.nntp_implementation

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

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

1.2. Методы

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

Многие из следующих методов принимают необязательный ключевой параметр 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(ssl_context=None)

Отправить команду STARTTLS. Это позволит включить шифрование на подключении NNTP. Аргумент ssl_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. Если совпадений несколько (если ‘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) строки будут содержать только заголовки сообщения, а не тело.

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

То же, что и article(), но отправляет команду BODY. Возвращаемые (или записываемые в 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. Возвращает ответ сервера.

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

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'