##
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 オブジェクトの他のいかなるメソッドも呼び出してはいけません。