11.11.1 NNTP オブジェクト

NNTP インスタンスは以下のメソッドを持っています。全てのメソッドにおける戻り値のタプルで最初の要素となる response は、サーバの応答です: この文字列は 3 桁の数字からなるコードで始まります。サーバの応答がエラーを示す場合、上記のいずれかの例外が送出されます。

getwelcome( ): サーバに最初に接続した際に送信される応答中のウェルカムメッセージを返します。(このメッセージには時に、ユーザにとって重要な免責事項やヘルプ情報が入っています。)

set_debuglevel( level): インスタンスのデバッグレベルを設定します。このメソッドは印字されるデバッグ出力の量を制御します。標準では 0 に設定されていて、これはデバッグ出力を全く印字しません。1 はそこそこの量、一般に NNTP 要求や応答あたり 1 行のデバッグ出力を生成します。値が 2 やそれ以上の場合、(メッセージテキストを含めて) NNTP 接続上で送受信された全ての内容を一行ごとにログ出力する、最大限のデバッグ出力を生成します。

newgroups( date, time, [file]): "NEWSGROUPS" 命令を送信します。date 引数は 'yymmdd' の形式を取り、日付を表します。 time 引数は 'hhmmss' の形式をとり、時刻を表します。与えられた日付および時刻以後新たに出現したニュースグループ名のリストを groups として、 (response, groups) を返します。 file引数が指定されている場合、"NEWGROUPS"コマンドの出力結果はファイルに格納されます。fileが文字列の場合、この文字列をファイル名としてファイルをオープンし、書き込み後にクローズします。fileがファイルオブジェクトの場合、オブジェクトのwrite()メソッドを呼び出して出力結果を格納します。fileが指定されている場合は戻り値として空のリストを返します。

newnews( group, date, time, [file]): "NEWNEWS" 命令を送信します。ここで、group はグループ名または '*' で、 date および time は newsgrups() における引数と同じ意味を持ちます。 (response, articles) からなるペアを返し、 articles は記事 ID のリストです。 file引数が指定されている場合、"NEWNEWS"コマンドの出力結果はファイルに格納されます。fileが文字列の場合、この文字列をファイル名としてファイルをオープンし、書き込み後にクローズします。fileがファイルオブジェクトの場合、オブジェクトのwrite()メソッドを呼び出して出力結果を格納します。fileが指定されている場合は戻り値として空のリストを返します。

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が指定されている場合は戻り値として空のリストを返します。

descriptions( grouppattern): "LIST NEWSGROUPS" 命令を送信します。grouppattern は RFC2980 の定義に従う wildmat 文字列です (実際には、 DOS や UNIX のシェルワイルドカード文字列と同じです)。 (response,list) からなるペアを返し、list はタプル(name, title) リストになります。バージョン 2.4 で新たに追加された仕様です。

description( group)

単一のグループgroup から説明文字列を取り出します。 ('group' が実際には wildmat 文字列で) 複数のグループがマッチした場合、最初にマッチしたものを返します。何もマッチしなければ空文字列を返します。

このメソッドはサーバからの応答コードを省略します。応答コードが必要なら、descriptions() を使ってください。

バージョン 2.4 で新たに追加された仕様です。

group( name): "GROUP" 命令を送信します。name はグループ名です。タプル (response, count, first, last, name) を返します。count はグループ中の記事数 (の推定値) で、 first はグループ中の最初の記事番号、last はグループ中の最新の記事番号、name はグループ名です。記事番号は文字列で返されます。

help( [file]): "HELP" 命令を送信します。(response, list) からなるペアを返します。list はヘルプ文字列からなるリストです。 file引数が指定されている場合、"HELP"コマンドの出力結果はファイルに格納されます。fileが文字列の場合、この文字列をファイル名としてファイルをオープンし、書き込み後にクローズします。fileがファイルオブジェクトの場合、オブジェクトのwrite()メソッドを呼び出して出力結果を格納します。fileが指定されている場合は戻り値として空のリストを返します。

stat( id): "STAT" 命令を送信します。id は ("<" と ">" に囲まれた形式の) メッセージ ID か、 (文字列の) 記事番号です。三つ組み (response, number, id) を返します。 number は (文字列の) 記事番号で、id は ("<" と ">" に囲まれた形式の) メッセージ ID です。

next( ): "NEXT" 命令を送信します。stat() のような応答を返します。

last( ): "LAST" 命令を送信します。stat() のような応答を返します。

head( id): "HEAD" 命令を送信します。id は stat() におけるのと同じ意味を持ちます。 (response, number, id, list) からなるタプルを返します。最初の 3 要素は stat() と同じもので、list は記事のヘッダからなるリスト (まだ解析されておらず、末尾の改行が取り去られたヘッダ行のリスト) です。

body( id,[file]): "BODY" 命令を送信します。id は stat() におけるのと同じ意味を持ちます。file 引数が与えられている場合、記事本体 (body) はファイルに保存されます。file が文字列の場合、このメソッドはその名前を持つファイルオブジェクトを開き、記事を書き込んで閉じます。file がファイルオブジェクトの場合、write() を呼び出して記事本体を記録します。 head() のような戻り値を返します。file が与えられていた場合、返される list は空のリストになります。

article( id): "ARTICLE" 命令を送信します。id は stat() におけるのと同じ意味を持ちます。head() のような戻り値を返します。

slave( ): "SLAVE" 命令を送信します。サーバの response を返します。

xhdr( header, string, [file]): "XHDR" 命令を送信します、この命令は RFC には定義されていませんが、一般に広まっている拡張です。header 引数は、例えば 'subject' といったヘッダキーワードです。string 引数は 'first-last' の形式でなければならず、ここで first および last は検索の対象とする記事範囲の最初と最後の記事番号です。(response, list) のペアを返します。 list は (id, text) のペアからなるリストで、 id が (文字列で表した) 記事 ID、text がその記事のヘッダテキストです。 file引数が指定されている場合、"XHDR"コマンドの出力結果はファイルに格納されます。fileが文字列の場合、この文字列をファイル名としてファイルをオープンし、書き込み後にクローズします。fileがファイルオブジェクトの場合、オブジェクトのwrite()メソッドを呼び出して出力結果を格納します。fileが指定されている場合は戻り値として空のリストを返します。

post( file): "POST" 命令を使って記事をポストします。file 引数は開かれているファイルオブジェクトで、その内容は readline() メソッドを使って EOF まで読み出されます。内容は必要なヘッダを含め、正しい形式のニュース記事でなければなりません。post() メソッドは "."で始まる行を自動的にエスケープします。

ihave( id, file): "IHAVE" 命令を送信します。応答がエラーでない場合、 file を post() と全く同じように扱います。

date( ): タプル (response, date, time) を返します。このタプルには newnews() および newgroups() メソッドに合った形式の、現在の日付および時刻が入っています。これはオプションの NNTP 拡張なので、全てのサーバでサポートされているとは限りません。

xgtitle( name, [file]): "XGTITLE" 命令を処理し、(response, list) からなるペアを返します。list は (name, title) を含むタプルのリストです。 file引数が指定されている場合、"XHDR"コマンドの出力結果はファイルに格納されます。fileが文字列の場合、この文字列をファイル名としてファイルをオープンし、書き込み後にクローズします。fileがファイルオブジェクトの場合、オブジェクトのwrite()メソッドを呼び出して出力結果を格納します。fileが指定されている場合は戻り値として空のリストを返します。これはオプションの NNTP 拡張なので、全てのサーバでサポートされているとは限りません。
RFC2980 では、 ``この拡張は撤廃すべきである'' と主張しています。 descriptions() または description() を使うようにしてください。

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 拡張なので、全てのサーバでサポートされているとは限りません。

xpath( id): (resp, path) からなるペアを返します。 path はメッセージ ID が id である記事のディレクトリパスです。これはオプションの NNTP 拡張なので、全てのサーバでサポートされているとは限りません。

quit( ): "QUIT" 命令を送信し、接続を閉じます。このメソッドを呼び出した後は、NTTP オブジェクトの他のいかなるメソッドも呼び出してはいけません。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。