20.11. nntplib --- NNTP プロトコルクライアント¶
Source code: Lib/nntplib.py
このモジュールでは、クラス NNTP を定義しています。このクラスは NNTP プロトコルのクライアント側を実装しています。このモジュールを使えば、ニュースリーダや記事投稿プログラム、または自動的にニュース記事を 処理するプログラムを実装することができます。NNTP (Network News Transfer Protocol、ネットニュース転送プロトコル) の詳細については、インターネット RFC 977 を参照してください。
以下にこのモジュールの使い方の小さな例を二つ示します。ニュースグループに関する統計情報を列挙し、最新 10 件の記事を出力するには以下のようにします:
>>> s = NNTP('news.gmane.org')
>>> 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 1071 articles, range 1 to 1071
>>> resp, subs = s.xhdr('subject', first + '-' + last)
>>> for id, sub in subs[-10:]: print id, sub
...
1062 Re: Mercurial Status?
1063 Re: [python-committers] (Windows) buildbots on 3.x
1064 Re: Mercurial Status?
1065 Re: Mercurial Status?
1066 Python 2.6.6 status
1067 Commit Privileges for Ask Solem
1068 Re: Commit Privileges for Ask Solem
1069 Re: Commit Privileges for Ask Solem
1070 Re: Commit Privileges for Ask Solem
1071 2.6.6 rc 2
>>> s.quit()
'205 Bye!'
ファイルから記事を投稿するには、以下のようにします。 (この例では記事番号は有効な番号を指定していて、あなたがそのニュースグループに投稿する 権限を持っていると仮定しています)
>>> s = NNTP('news.gmane.org')
>>> f = open('articlefile')
>>> s.post(f)
'240 Article posted successfully.'
>>> s.quit()
'205 Bye!'
このモジュール自体では以下の内容を定義しています:
-
class
nntplib.NNTP(host[, port [, user[, password [, readermode] [, usenetrc]]]])¶ ホスト host 上で動作し、ポート番号 port で要求待ちをしている NNTP サーバとの接続を表現する新たな
NNTPクラスのインスタンスを返します。標準の port は 119 です。オプションの user および password が与えられているか、 または/.netrcに適切な認証情報が指定されていて usenetrc が真 (デフォルト) の場合、AUTHINFO USERおよびAUTHINFO PASS命令を使ってサーバに対して身元証明および認証を行います。オプションのフラグ readermode が真の場合、認証の実行に先立ってmode reader命令が送信されます。reader モードは、ローカルマシン上の NNTP サーバ に接続していて、groupのような reader 特有の命令を呼び出したい場合に便利なことがあります。予期せずNNTPPermanentErrorに遭遇したなら、 readermode を設定する必要があるかもしれません。 readermode のデフォルト値はNoneです。 usenetrc のデフォルト値はTrueです。バージョン 2.4 で変更: usenetrc 引数を追加しました.
-
exception
nntplib.NNTPReplyError¶ 期待はずれの応答がサーバから返された場合に送出される例外です。以前のバージョンとの互換性のために、
error_replyはこのクラスと等価になっています。
-
exception
nntplib.NNTPTemporaryError¶ エラーコードの範囲が 400-499 のエラーを受信した場合に送出される例外です。以前のバージョンとの互換性のために、
error_tempはこのクラスと等価になっています。
-
exception
nntplib.NNTPPermanentError¶ エラーコードの範囲が 500-599 のエラーを受信した場合に送出される例外です。以前のバージョンとの互換性のために、
error_permはこのクラスと等価になっています。
-
exception
nntplib.NNTPProtocolError¶ サーバから返される応答が 1--5 の範囲の数字で始まっていない場合に送出される例外です。以前のバージョンとの互換性のために、
error_protoはこのクラスと等価になっています。
-
exception
nntplib.NNTPDataError¶ 応答データ中に何らかのエラーが存在する場合に送出される例外です。以前のバージョンとの互換性のために、
error_dataはこのクラスと等価になっています。
20.11.1. NNTP オブジェクト¶
NNTP インスタンスは以下のメソッドを持っています。全てのメソッドにおける戻り値のタプルで最初の要素となる response は、サーバの応答です: この文字列は 3 桁の数字からなるコードで始まります。サーバの応答がエラーを示す場合、上記のいずれかの例外が送出されます。
-
NNTP.getwelcome()¶ サーバに最初に接続した際に送信される応答中のウェルカムメッセージを返します。(このメッセージには時に、ユーザにとって重要な免責事項や ヘルプ情報が入っています。)
-
NNTP.set_debuglevel(level)¶ インスタンスのデバッグレベルを設定します。このメソッドは印字されるデバッグ出力の量を制御します。標準では
0に設定されていて、 これはデバッグ出力を全く印字しません。1はそこそこの量、一般に NNTP 要求や応答あたり 1 行のデバッグ出力を生成します。値が2やそれ以上の場合、(メッセージテキストを含めて) NNTP 接続上で送受信された全ての内容を一行ごとにログ出力する、最大限のデバッグ出力を生成します。
-
NNTP.newgroups(date, time[, file])¶ NEWSGROUPS命令を送信します。 date 引数は'yymmdd'の形式を取り、日付を表します。 time 引数は'hhmmss'の形式をとり、時刻を表します。与えられた日付および時刻以後新たに出現したニュースグループ名のリストを groups として、(response, groups)を返します。 file 引数が指定されている場合、NEWGROUPSコマンドの出力結果は ファイルに格納されます。 file が文字列の場合、この文字列をファイル名としてファイルをオープンし、書き込み後にクローズします。 file がファ イルオブジェクトの場合、オブジェクトのwrite()メソッドを呼び出して出力結果を格納します。 file が指定されている場合は戻り値として空の リストを返します。
-
NNTP.newnews(group, date, time[, file])¶ NEWNEWS命令を送信します。ここで、 group はグループ名または'*'で、 date および time はnewsgrups()における引数と同じ意味を持ちます。(response, articles)からなるペアを返し、 articles はメッセージ ID のリストです。 file 引数が指定されている場合、NEWNEWSコマンドの出力結果は ファイルに格納されます。 file が文字列の場合、この文字列をファイル名としてファイルをオープンし、書き込み後にクローズします。 file がファ イルオブジェクトの場合、オブジェクトのwrite()メソッドを呼び出して出力結果を格納します。 file が指定されている場合は戻り値として空の リストを返します。
-
NNTP.list([file])¶ LIST命令を送信します。(response, list)からなるペアを返します。 list はタプルからなるリストです。各タプルは(group, last, first, flag)の形式をとり、 group がグループ名、 last および first はそれぞれ最新および最初の記事の記事番号 (を表す文字列)、そして flag は投稿が可能な場合には'y', そうでない場合には'n', グループがモデレート (moderated) されている場合には'm'となります。(順番に注意してください: last, first の順です。) file 引数が指定されている場合、LISTコマンドの出力結果は ファイルに格納されます。 file が文字列の場合、この文字列をファイル名としてファイルをオープンし、書き込み後にクローズします。 file がファ イルオブジェクトの場合、オブジェクトのwrite()メソッドを呼び出して出力結果を格納します。 file が指定されている場合は戻り値として空の リストを返します。
-
NNTP.descriptions(grouppattern)¶ LIST NEWSGROUPS命令を送信します。 grouppattern は RFC2980 の定義に従う wildmat 文字列です (実際には、 DOS や UNIX のシェルワイルドカード文字列と同じです)。(response,list)からなるペアを返し、 list はタプル(name, title)リストになります。バージョン 2.4 で追加.
-
NNTP.description(group)¶ 単一のグループ group から説明文字列を取り出します。 ('group' が実際には wildmat 文字列で) 複数のグループがマッチした場合、 最初にマッチしたものを返します。何もマッチしなければ空文字列を返します。
このメソッドはサーバからの応答コードを省略します。応答コードが必要なら、
descriptions()を使ってください。バージョン 2.4 で追加.
-
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 は ('<'と'>'に囲まれた形式の) メッセージ ID か、 (文字列の) 記事番号です。 三つ組み(response, number, id)を返します。 number は (文字列の) 記事番号で、 id は ('<'と'>'に囲まれた形式の) メッセージ ID です。
-
NNTP.head(id)¶ HEAD命令を送信します。 id はstat()におけるのと同じ意味を持ちます。(response, number, id, list)からなるタプルを返します。最初の 3 要素はstat()と同じもので、 list は記事のヘッダからなるリスト (まだ解析されておらず、末尾の改行が取り去られたヘッダ行のリスト) です。
-
NNTP.body(id[, file])¶ BODY命令を送信します。 id はstat()におけるのと同じ意味を持ちます。 file 引数が与えられている場合、記事本体 (body) はファイルに保存されます。 file が文字列の場合、このメソッドはその名前を持つファイルオブジェクトを 開き、記事を書き込んで閉じます。 file がファイルオブジェクトの場合、write()を呼び出して記事本体を記録します。head()のような戻り値を返します。 file が与えられていた場合、返される list は空のリストになります。
-
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 が指定されている場合は戻り値として空の リストを返します。
-
NNTP.post(file)¶ POST命令を使って記事をポストします。 file 引数は開かれているファイルオブジェクトで、その内容はreadline()メソッドを使って EOF まで読み出されます。内容は必要なヘッダを含め、正しい形式のニュース記事でなければなりません。post()メソッドは.で始まる行を自動的にエスケープします。
-
NNTP.ihave(id, file)¶ IHAVE命令を送信します。 id は ('<'と'>'に囲まれた) メッセージ ID です。 応答がエラーでない場合、 file をpost()と全く同じように扱います。
-
NNTP.date()¶ タプル
(response, date, time)を返します。このタプルにはnewnews()およびnewgroups()メソッドに合った形式の、現在の日付および時刻が入っています。これはオプションの NNTP 拡張なので、全てのサーバでサポートされているとは限りません。
-
NNTP.xgtitle(name[, file])¶ XGTITLE命令を処理し、(response, list)からなるペアを返します。 list は(name, title)を含むタプルのリストです。 file 引数が指定されている場合、XHDRコマンドの出力結果は ファイルに格納されます。 file が文字列の場合、この文字列をファイル名としてファイルをオープンし、書き込み後にクローズします。 file がファ イルオブジェクトの場合、オブジェクトのwrite()メソッドを呼び出して出力結果を格納します。 file が指定されている場合は戻り値として空の リストを返します。これはオプションの NNTP 拡張なので、全てのサーバでサポートされているとは限りません。RFC2980 では、 "この拡張は撤廃すべきである" と主張しています。
descriptions()またはdescription()を使うようにしてください。
-
NNTP.xover(start, end[, file])¶ (resp, list)からなるペアを返します。 list はタプルからなるリストで、各タプルは記事番号 start および end の間に区切られた記事です。各タプルは(article number, subject, poster, date, id, references, size, lines)の形式をとります。 file 引数が指定されている場合、XHDRコマンドの出力結果は ファイルに格納されます。 file が文字列の場合、この文字列をファイル名としてファイルをオープンし、書き込み後にクローズします。 file がファ イルオブジェクトの場合、オブジェクトのwrite()メソッドを呼び出して出力結果を格納します。 file が指定されている場合は戻り値として空の リストを返します。これはオプションの NNTP 拡張なので、全てのサーバでサポートされているとは限りません。
-
NNTP.xpath(id)¶ (resp, path)からなるペアを返します。 path はメッセージ ID が id である記事のディレクトリパスです。 これはオプションの NNTP 拡張なので、全てのサーバでサポートされているとは限りません。
-
NNTP.quit()¶ QUIT命令を送信し、接続を閉じます。このメソッドを呼び出した後は、NTTP オブジェクトの他のいかなるメソッドも呼び出してはいけません。