20.14. nntplib – клиент протокола NNTP¶nntplib – NNTP protocol client

20.14.1. Объекты NNTP¶NNTP Objects

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

NNTP.getwelcome()¶

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

NNTP.set_debuglevel(level)¶

Устанавливает уровень отладки экземпляра. Он управляет объёмом выводимых отладочных сообщений. Значение по умолчанию, 0, не выводит отладочные сообщения. Значение 1 выдаёт умеренное количество отладочной информации, обычно одну строку на запрос или ответ. Значение 2 или больше выводит максимальный объём отладочной информации, регистрируя каждую отправленную и полученную строку соединения (включая текст сообщения).

NNTP.newgroups(date, time[, file])¶

Отправляет команду NEWGROUPS. Аргумент date должен быть строкой вида 'yymmdd', указывающей дату, а time – строкой вида 'hhmmss', указывающей время. Возвращает пару (response, groups), где groups – список названий групп, появившихся после указанной даты и времени. Если указан параметр file, вывод команды NEWGROUPS сохраняется в файл. Если file – строка, метод откроет файл с таким именем, запишет в него и закроет. Если file – файловый объект, то для сохранения строк вывода команды будет вызываться метод write(). Если file указан, возвращаемый список будет пустым.

NNTP.newnews(group, date, time[, file])¶

Отправляет команду NEWNEWS. Здесь group – название группы или '*', а date и time имеют тот же смысл, что и для newgroups(). Возвращает пару (response, articles), где articles – список идентификаторов сообщений. Если указан параметр file, вывод команды NEWNEWS сохраняется в файл. Если file – строка, метод откроет файл с таким именем, запишет в него и закроет. Если file – файловый объект, то для сохранения строк вывода команды будет вызываться метод write(). Если file указан, возвращаемый список будет пустым.

NNTP.list([file])¶

Отправляет команду LIST. Возвращает пару (response, list), где list – список кортежей. Каждый кортеж имеет вид (group, last, first, flag), где group – название группы, last и first – последний и первый номера статей (в виде строк), а flag равен 'y', если публикация разрешена, 'n' – если нет, и 'm' – если группа модерируется. (Обратите внимание на порядок: last, затем first.) Если указан параметр file, вывод команды LIST сохраняется в файл. Если file – строка, метод откроет файл с таким именем, запишет в него и закроет. Если file – файловый объект, то для сохранения строк вывода команды будет вызываться метод write(). Если file указан, возвращаемый список будет пустым.

NNTP.descriptions(grouppattern)¶

Отправляет команду LIST NEWSGROUPS, где grouppattern – строка wildmat, как указано в RFC2980 (по сути, это те же шаблоны подстановки, что в DOS или UNIX). Возвращает пару (response, list), где list – список кортежей, содержащих (name, title).

NNTP.description(group)¶

Получает описание для одной группы group. Если совпадает несколько групп (если ‘group’ – это строка шаблона wildmat), возвращается первое совпадение. Если ни одна группа не совпадает, возвращается пустая строка.

Этот метод опускает код ответа сервера. Если код ответа нужен, используйте descriptions().

NNTP.group(name)¶

Отправляет команду GROUP, где name – название группы. Возвращает кортеж (response, count, first, last, name), где count – (оценочное) количество статей в группе, first – номер первой статьи в группе, last – номер последней статьи в группе, а name – название группы. Числа возвращаются в виде строк.

NNTP.help([file])¶

Отправляет команду HELP. Возвращает пару (response, list), где list – список строк справки. Если указан параметр file, вывод команды HELP сохраняется в файл. Если file – строка, метод откроет файл с таким именем, запишет в него и закроет. Если file – файловый объект, то для сохранения строк вывода команды будет вызываться метод write(). Если file указан, возвращаемый список будет пустым.

NNTP.stat(id)¶

Отправляет команду STAT, где id – идентификатор сообщения (заключённый в '<' и '>') или номер статьи (в виде строки). Возвращает тройку (response, number, id), где number – номер статьи (в виде строки), а id – идентификатор сообщения (заключённый в '<' и '>').

NNTP.next()¶

Отправляет команду NEXT. Возвращаемое значение – как у stat().

NNTP.last()¶

Отправляет команду LAST. Возвращаемое значение – как у stat().

NNTP.head(id)¶

Отправляет команду HEAD, где id имеет то же значение, что и для stat(). Возвращает кортеж (response, number, id, list), где первые три элемента такие же, как для stat(), а list – это список заголовков статьи ( неинтерпретированный список строк без завершающих переводов строк).

NNTP.body(id[, file])¶

Отправляет команду BODY, где id имеет то же значение, что и для stat(). Если указан параметр file, то тело сохраняется в файл. Если file – строка, то метод откроет файл с таким именем, запишет в него, а затем закроет. Если file – файловый объект, то он начнёт вызывать write() для него, чтобы сохранить строки тела. Возвращаемое значение такое же, как для head(). Если передан file, то возвращаемый список будет пуст.

NNTP.article(id)¶

Отправляет команду ARTICLE, где id имеет то же значение, что и для stat(). Возвращаемое значение такое же, как для head().

NNTP.slave()¶

Отправляет команду SLAVE. Возвращает response сервера.

NNTP.xhdr(header, string[, file])¶

Отправляет команду XHDR. Эта команда не определена в RFC, но является распространённым расширением. Аргумент header – это ключевое слово заголовка, например 'subject'. Аргумент string должен иметь вид 'first-last', где first и last – это первый и последний номера статей для поиска. Возвращает пару (response, list), где list – список пар (id, text), где id – номер статьи (в виде строки), а text – текст запрошенного заголовка для этой статьи. Если передан параметр file, вывод команды XHDR сохраняется в файл. Если file – строка, метод откроет файл с таким именем, запишет в него и затем закроет. Если file – это объект файла, то метод начнёт вызывать write() для сохранения строк вывода команды. Если file передан, возвращаемый list будет пустым списком.

NNTP.post(file)¶

Отправляет статью с помощью команды POST. Аргумент file – это открытый файловый объект, который читается до конца (EOF) с помощью его метода readline(). Это должна быть правильно оформленная новостная статья, включающая необходимые заголовки. Метод post() автоматически экранирует строки, начинающиеся с ..

NNTP.ihave(id, file)¶

Отправляет команду IHAVE. id – это идентификатор сообщения (заключённый в '<' и '>'). Если ответ не является ошибкой, обрабатывать file точно так же, как в методе post().

NNTP.date()¶

Возвращает тройку (response, date, time), содержащую текущую дату и время в форме, подходящей для методов newnews() и newgroups(). Это необязательное расширение NNTP, которое может не поддерживаться всеми серверами.

NNTP.xgtitle(name[, file])¶

Обрабатывает команду XGTITLE, возвращая пару (response, list), где list – это список кортежей, содержащих (name, title). Если параметр file указан, то вывод команды XGTITLE сохраняется в файл. Если file – строка, то метод откроет файл с таким именем, запишет в него, а затем закроет. Если file – это file object, то он начнёт вызывать write() для сохранения строк вывода команды. Если file указан, то возвращаемый list будет пустым списком. Это необязательное расширение NNTP и может не поддерживаться всеми серверами.

В RFC2980 говорится: «Рекомендуется объявить это расширение устаревшим». Используйте descriptions() или description() вместо него.

NNTP.xover(start, end[, file])¶

Возвращает пару (resp, list). list – это список кортежей, по одному для каждой статьи в диапазоне, ограниченном номерами статей start и end. Каждый кортеж имеет вид (article number, subject, poster, date, id, references, size, lines). Если параметр file указан, то вывод команды XOVER сохраняется в файл. Если file – строка, то метод откроет файл с таким именем, запишет в него, а затем закроет. Если file – это file object, то он начнёт вызывать write() для сохранения строк вывода команды. Если file указан, то возвращаемый list будет пустым списком. Это необязательное расширение NNTP и может не поддерживаться всеми серверами.

NNTP.xpath(id)¶

Возвращает пару (resp, path), где path – это путь к каталогу статьи с идентификатором сообщения id. Это необязательное расширение NNTP и может не поддерживаться всеми серверами.

NNTP.quit()¶

Отправляет команду QUIT и закрывает соединение. После вызова этого метода не следует вызывать другие методы объекта NNTP.