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 имеет значение 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.io') 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 и 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 предоставлен, он должен быть либо файловым объектом, открытым для двоичного записи, либо именем файла на диске, в который необходимо записать данные. Метод запишет любые данные, возвращенные сервером (за исключением строки ответа и заключительной точки) в файл; любой список строк, кортежей или объектов, который метод обычно возвращает, будет пустым.

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