`nntplib.md`

943 строк · 22.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/library/nntplib.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 20.14. `nntplib` – клиент протокола NNTP89Этот модуль определяет класс [`NNTP`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP), который реализует клиентскую сторону протокола NNTP. Его можно использовать для создания программы чтения новостей, отправки сообщений или автоматической обработки новостей. Дополнительную информацию о NNTP (Network News Transfer Protocol, протокол передачи сетевых новостей) см. в [**RFC 977**](https://python-all.ru/3.1/library/nntplib.html).1011Вот два небольших примера использования. Чтобы вывести статистику по группе новостей и напечатать темы последних 10 статей:1213```python14>>> s = NNTP('news.gmane.org')15>>> resp, count, first, last, name = s.group('gmane.comp.python.committers')16>>> print('Group', name, 'has', count, 'articles, range', first, 'to', last)17Group gmane.comp.python.committers has 1071 articles, range 1 to 107118>>> resp, subs = s.xhdr('subject', first + '-' + last)19>>> for id, sub in subs[-10:]: print(id, sub)20...211062 Re: Mercurial Status?221063 Re: [python-committers]  (Windows) buildbots on 3.x231064 Re: Mercurial Status?241065 Re: Mercurial Status?251066 Python 2.6.6 status261067 Commit Privileges for Ask Solem271068 Re: Commit Privileges for Ask Solem281069 Re: Commit Privileges for Ask Solem291070 Re: Commit Privileges for Ask Solem301071 2.6.6 rc 231>>> s.quit()32'205 Bye!'33```3435Чтобы отправить статью из файла (предполагается, что статья имеет корректные заголовки и у вас есть право публиковать сообщения в данной группе новостей):3637```python38>>> s = NNTP('news.gmane.org')39>>> f = open('/tmp/article')40>>> s.post(f)41'240 Article posted successfully.'42>>> s.quit()43'205 Bye!'44```4546Сам модуль определяет следующие элементы:4748#### `class nntplib.NNTP(host[, port[, user[, password[, readermode][, usenetrc]]]])`4950Возвращает новый экземпляр класса5152[`NNTP`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP)5354, представляющий подключение к серверу NNTP, работающему на узле5556*host*5758и ожидающему на порту5960*port*6162. По умолчанию6364*port*6566равен 119. Если указаны необязательные6768*user*6970и7172*password*7374, или если подходящие учётные данные есть в7576`/.netrc`7778и необязательный флаг7980*usenetrc*8182имеет значение true (по умолчанию), для идентификации и аутентификации пользователя на сервере используются команды8384`AUTHINFO USER`8586и8788`AUTHINFO PASS`8990. Если необязательный флаг9192*readermode*9394равен true, перед выполнением аутентификации отправляется команда9596`mode reader`9798. Режим чтения иногда требуется, если вы подключаетесь к серверу NNTP на локальной машине и собираетесь вызывать команды, специфичные для чтения, например99100`group`101102. Если возникают неожиданные103104[`NNTPPermanentError`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTPPermanentError)105106, возможно, потребуется установить107108*readermode*109110. Значением111112*readermode*113114по умолчанию является115116`None`117118. Значением119120*usenetrc*121122по умолчанию является123124`True`125126.127128#### `exception nntplib.NNTPError`129130Этот класс, производный от стандартного исключения131132[`Exception`](https://python-all.ru/3.1/library/exceptions.html#Exception)133134, является базовым для всех исключений, вызываемых модулем135136`nntplib`137138.139140#### `exception nntplib.NNTPReplyError`141142Исключение, вызываемое при получении от сервера неожиданного ответа. Для обратной совместимости исключение143144`error_reply`145146эквивалентно данному классу.147148#### `exception nntplib.NNTPTemporaryError`149150Исключение, вызываемое при получении кода ошибки в диапазоне 400–499. Для обратной совместимости исключение151152`error_temp`153154эквивалентно данному классу.155156#### `exception nntplib.NNTPPermanentError`157158Исключение, вызываемое при получении кода ошибки в диапазоне 500–599. Для обратной совместимости исключение159160`error_perm`161162эквивалентно данному классу.163164#### `exception nntplib.NNTPProtocolError`165166Исключение, вызываемое при получении от сервера ответа, который не начинается с цифры в диапазоне 1–5. Для обратной совместимости исключение167168`error_proto`169170эквивалентно данному классу.171172#### `exception nntplib.NNTPDataError`173174Исключение, вызываемое при ошибке в данных ответа. Для обратной совместимости исключение175176`error_data`177178эквивалентно данному классу.179180## 20.14.1. Объекты NNTP181182Экземпляры NNTP имеют следующие методы. *response*, возвращаемый как первый элемент кортежа результатов почти всех методов, – это ответ сервера: строка, начинающаяся с трёхзначного кода. Если ответ сервера указывает на ошибку, метод вызывает одно из перечисленных выше исключений.183184#### `NNTP.getwelcome()`185186Возвращает приветственное сообщение, отправленное сервером в ответ на начальное подключение. (Это сообщение иногда содержит отказ от ответственности или справочную информацию, которая может быть полезна пользователю.)187188#### `NNTP.set_debuglevel(level)`189190Устанавливает уровень отладки экземпляра. Он управляет объёмом выводимых отладочных сообщений. Значение по умолчанию,191192`0`193194, не выводит отладочные сообщения. Значение195196`1`197198выдаёт умеренное количество отладочной информации, обычно одну строку на запрос или ответ. Значение199200`2`201202или больше выводит максимальный объём отладочной информации, регистрируя каждую отправленную и полученную строку соединения (включая текст сообщения).203204#### `NNTP.newgroups(date, time[, file])`205206Отправляет команду207208`NEWGROUPS`209210. Аргумент211212*date*213214должен быть строкой вида215216`'yymmdd'`217218, указывающей дату, а219220*time*221222– строкой вида223224`'hhmmss'`225226, указывающей время. Возвращает пару227228`(response, groups)`229230, где231232*groups*233234– список названий групп, появившихся после указанной даты и времени. Если указан параметр235236*file*237238, вывод команды239240`NEWGROUPS`241242сохраняется в файл. Если243244*file*245246– строка, метод откроет файл с таким именем, запишет в него и закроет. Если247248*file*249250–251252[*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object)253254, то для сохранения строк вывода команды будет вызываться метод255256`write()`257258. Если259260*file*261262указан, возвращаемый263264*список*265266будет пустым.267268#### `NNTP.newnews(group, date, time[, file])`269270Отправляет команду271272`NEWNEWS`273274. Здесь275276*group*277278– название группы или279280`'*'`281282, а283284*date*285286и287288*time*289290имеют тот же смысл, что и для291292[`newgroups()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.newgroups)293294. Возвращает пару295296`(response, articles)`297298, где299300*articles*301302– список идентификаторов сообщений. Если указан параметр303304*file*305306, вывод команды307308`NEWNEWS`309310сохраняется в файл. Если311312*file*313314– строка, метод откроет файл с таким именем, запишет в него и закроет. Если315316*file*317318–319320[*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object)321322, то для сохранения строк вывода команды будет вызываться метод323324`write()`325326. Если327328*file*329330указан, возвращаемый331332*список*333334будет пустым.335336#### `NNTP.list([file])`337338Отправляет команду339340`LIST`341342. Возвращает пару343344`(response, list)`345346, где347348*list*349350– список кортежей. Каждый кортеж имеет вид351352`(group, last, first, flag)`353354, где355356*group*357358– название группы,359360*last*361362и363364*first*365366– последний и первый номера статей (в виде строк), а367368*flag*369370равен371372`'y'`373374, если публикация разрешена,375376`'n'`377378– если нет, и379380`'m'`381382– если группа модерируется. (Обратите внимание на порядок:383384*last*385386, затем387388*first*389390.) Если указан параметр391392*file*393394, вывод команды395396`LIST`397398сохраняется в файл. Если399400*file*401402– строка, метод откроет файл с таким именем, запишет в него и закроет. Если403404*file*405406–407408[*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object)409410, то для сохранения строк вывода команды будет вызываться метод411412`write()`413414. Если415416*file*417418указан, возвращаемый419420*список*421422будет пустым.423424#### `NNTP.descriptions(grouppattern)`425426Отправляет команду427428`LIST NEWSGROUPS`429430, где431432*grouppattern*433434– строка wildmat, как указано в RFC2980 (по сути, это те же шаблоны подстановки, что в DOS или UNIX). Возвращает пару435436`(response, list)`437438, где439440*list*441442– список кортежей, содержащих443444`(name, title)`445446.447448#### `NNTP.description(group)`449450Получает описание для одной группы *group*. Если совпадает несколько групп (если ‘group’ – это строка шаблона wildmat), возвращается первое совпадение. Если ни одна группа не совпадает, возвращается пустая строка.451452Этот метод опускает код ответа сервера. Если код ответа нужен, используйте [`descriptions()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.descriptions).453454#### `NNTP.group(name)`455456Отправляет команду457458`GROUP`459460, где461462*name*463464– название группы. Возвращает кортеж465466`(response, count, first, last, name)`467468, где469470*count*471472– (оценочное) количество статей в группе,473474*first*475476– номер первой статьи в группе,477478*last*479480– номер последней статьи в группе, а481482*name*483484– название группы. Числа возвращаются в виде строк.485486#### `NNTP.help([file])`487488Отправляет команду489490`HELP`491492. Возвращает пару493494`(response, list)`495496, где497498*list*499500– список строк справки. Если указан параметр501502*file*503504, вывод команды505506`HELP`507508сохраняется в файл. Если509510*file*511512– строка, метод откроет файл с таким именем, запишет в него и закроет. Если513514*file*515516–517518[*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object)519520, то для сохранения строк вывода команды будет вызываться метод521522`write()`523524. Если525526*file*527528указан, возвращаемый529530*список*531532будет пустым.533534#### `NNTP.stat(id)`535536Отправляет команду537538`STAT`539540, где541542*id*543544– идентификатор сообщения (заключённый в545546`'<'`547548и549550`'>'`551552) или номер статьи (в виде строки). Возвращает тройку553554`(response, number, id)`555556, где557558*number*559560– номер статьи (в виде строки), а561562*id*563564– идентификатор сообщения (заключённый в565566`'<'`567568и569570`'>'`571572).573574#### `NNTP.next()`575576Отправляет команду577578`NEXT`579580. Возвращаемое значение – как у581582[`stat()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.stat)583584.585586#### `NNTP.last()`587588Отправляет команду589590`LAST`591592. Возвращаемое значение – как у593594[`stat()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.stat)595596.597598#### `NNTP.head(id)`599600Отправляет команду601602`HEAD`603604, где605606*id*607608имеет то же значение, что и для609610[`stat()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.stat)611612. Возвращает кортеж613614`(response, number, id, list)`615616, где первые три элемента такие же, как для617618[`stat()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.stat)619620, а621622*list*623624– это список заголовков статьи ( неинтерпретированный список строк без завершающих переводов строк).625626#### `NNTP.body(id[, file])`627628Отправляет команду629630`BODY`631632, где633634*id*635636имеет то же значение, что и для637638[`stat()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.stat)639640. Если указан параметр641642*file*643644, то тело сохраняется в файл. Если645646*file*647648– строка, то метод откроет файл с таким именем, запишет в него, а затем закроет. Если649650*file*651652–653654[*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object)655656, то он начнёт вызывать657658`write()`659660для него, чтобы сохранить строки тела. Возвращаемое значение такое же, как для661662[`head()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.head)663664. Если передан665666*file*667668, то возвращаемый669670*список*671672будет пуст.673674#### `NNTP.article(id)`675676Отправляет команду677678`ARTICLE`679680, где681682*id*683684имеет то же значение, что и для685686[`stat()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.stat)687688. Возвращаемое значение такое же, как для689690[`head()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.head)691692.693694#### `NNTP.slave()`695696Отправляет команду697698`SLAVE`699700. Возвращает701702*response*703704сервера.705706#### `NNTP.xhdr(header, string[, file])`707708Отправляет команду709710`XHDR`711712. Эта команда не определена в RFC, но является распространённым расширением. Аргумент713714*header*715716– это ключевое слово заголовка, например717718`'subject'`719720. Аргумент721722*string*723724должен иметь вид725726`'first-last'`727728, где729730*first*731732и733734*last*735736– это первый и последний номера статей для поиска. Возвращает пару737738`(response, list)`739740, где741742*list*743744– список пар745746`(id, text)`747748, где749750*id*751752– номер статьи (в виде строки), а753754*text*755756– текст запрошенного заголовка для этой статьи. Если передан параметр757758*file*759760, вывод команды761762`XHDR`763764сохраняется в файл. Если765766*file*767768– строка, метод откроет файл с таким именем, запишет в него и затем закроет. Если769770*file*771772– это773774[*объект файла*](https://python-all.ru/3.1/glossary.html#term-file-object)775776, то метод начнёт вызывать777778`write()`779780для сохранения строк вывода команды. Если781782*file*783784передан, возвращаемый785786*list*787788будет пустым списком.789790#### `NNTP.post(file)`791792Отправляет статью с помощью команды793794`POST`795796. Аргумент797798*file*799800– это открытый файловый объект, который читается до конца (EOF) с помощью его метода801802`readline()`803804. Это должна быть правильно оформленная новостная статья, включающая необходимые заголовки. Метод805806[`post()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.post)807808автоматически экранирует строки, начинающиеся с809810`.`811812.813814#### `NNTP.ihave(id, file)`815816Отправляет команду817818`IHAVE`819820.821822*id*823824– это идентификатор сообщения (заключённый в825826`'<'`827828и829830`'>'`831832). Если ответ не является ошибкой, обрабатывать833834*file*835836точно так же, как в методе837838[`post()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.post)839840.841842#### `NNTP.date()`843844Возвращает тройку845846`(response, date, time)`847848, содержащую текущую дату и время в форме, подходящей для методов849850[`newnews()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.newnews)851852и853854[`newgroups()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.newgroups)855856. Это необязательное расширение NNTP, которое может не поддерживаться всеми серверами.857858#### `NNTP.xgtitle(name[, file])`859860Обрабатывает команду `XGTITLE`, возвращая пару `(response, list)`, где *list* – это список кортежей, содержащих `(name, title)`. Если параметр *file* указан, то вывод команды `XGTITLE` сохраняется в файл. Если *file* – строка, то метод откроет файл с таким именем, запишет в него, а затем закроет. Если *file* – это [*file object*](https://python-all.ru/3.1/glossary.html#term-file-object), то он начнёт вызывать `write()` для сохранения строк вывода команды. Если *file* указан, то возвращаемый *list* будет пустым списком. Это необязательное расширение NNTP и может не поддерживаться всеми серверами.861862В RFC2980 говорится: «Рекомендуется объявить это расширение устаревшим». Используйте [`descriptions()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.descriptions) или [`description()`](https://python-all.ru/3.1/library/nntplib.html#nntplib.NNTP.description) вместо него.863864#### `NNTP.xover(start, end[, file])`865866Возвращает пару867868`(resp, list)`869870.871872*list*873874– это список кортежей, по одному для каждой статьи в диапазоне, ограниченном номерами статей875876*start*877878и879880*end*881882. Каждый кортеж имеет вид883884`(article number, subject, poster, date, id, references, size, lines)`885886. Если параметр887888*file*889890указан, то вывод команды891892`XOVER`893894сохраняется в файл. Если895896*file*897898– строка, то метод откроет файл с таким именем, запишет в него, а затем закроет. Если899900*file*901902– это903904[*file object*](https://python-all.ru/3.1/glossary.html#term-file-object)905906, то он начнёт вызывать907908`write()`909910для сохранения строк вывода команды. Если911912*file*913914указан, то возвращаемый915916*list*917918будет пустым списком. Это необязательное расширение NNTP и может не поддерживаться всеми серверами.919920#### `NNTP.xpath(id)`921922Возвращает пару923924`(resp, path)`925926, где927928*path*929930– это путь к каталогу статьи с идентификатором сообщения931932*id*933934. Это необязательное расширение NNTP и может не поддерживаться всеми серверами.935936#### `NNTP.quit()`937938Отправляет команду939940`QUIT`941942и закрывает соединение. После вызова этого метода не следует вызывать другие методы объекта NNTP.943