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

Атрибуты

NNTP.nntp_version

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

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

NNTP.nntp_implementation

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

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

Методы

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

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