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

Атрибуты¶

NNTP.nntp_version¶

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

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

NNTP.nntp_implementation¶

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

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

Методы¶

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

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

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, и отдельный вызов этой функции не требуется. Чтобы принудительно отложить аутентификацию, вы не должны указывать пользователя или пароль при создании объекта, а должны установить для usenetrc значение False.

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

NNTP.starttls(context=None)¶

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

Обратите внимание, что это может быть сделано не после передачи аутентификационной информации, и аутентификация выполняется по умолчанию, если это возможно, во время инициализации объекта 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 - это список, представляющий группы, которые являются новыми с указанной даты. Если указан файл, то 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). Возвращает пару (response, 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) набором цифр, указывающим диапазон статей, начиная с первой и заканчивая последней статьей в текущей группе. текущую группу или None, чтобы выбрать текущую статью в текущей группе.

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

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

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

NNTP.post(data)¶

Опубликуйте статью, используя команду POST. Аргументом data является либо file object, открытый для двоичного чтения, либо любой итерируемый объект bytes (представляющий необработанные строки статьи, которую нужно опубликовать). Это должна быть хорошо оформленная новостная статья, включающая обязательные заголовки. Метод 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 является file object, то для него будет запущен вызов write(), чтобы сохранить строки вывода команды. Если указан file, то возвращаемый list будет пустым списком.

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

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