nntplib — NNTPプロトコルクライアント—Pythonドキュメント

nntplib —NNTPプロトコルクライアント

ソースコード： ：source： `Lib / nntplib.py`

---

このモジュールは、Network News TransferProtocolのクライアント側を実装するクラス NNTP を定義します。 ニュースリーダーやポスター、または自動ニュースプロセッサを実装するために使用できます。 RFC 3977 だけでなく、古い RFC 977 および RFC 2980 [と互換性があります。 X121X]。

使用方法の2つの小さな例を次に示します。 ニュースグループに関するいくつかの統計を一覧表示し、最後の10件の記事の主題を印刷するには：

>>> s = nntplib.NNTP('news.gmane.io')
>>> 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 1096 articles, range 1 to 1096
>>> resp, overviews = s.over((last - 9, last))
>>> for id, over in overviews:
...     print(id, nntplib.decode_header(over['subject']))
...
1087 Re: Commit privileges for Łukasz Langa
1088 Re: 3.2 alpha 2 freeze
1089 Re: 3.2 alpha 2 freeze
1090 Re: Commit privileges for Łukasz Langa
1091 Re: Commit privileges for Łukasz Langa
1092 Updated ssh key
1093 Re: Updated ssh key
1094 Re: Updated ssh key
1095 Hello fellow committers!
1096 Re: Hello fellow committers!
>>> s.quit()
'205 Bye!'

バイナリファイルから記事を投稿するには（これは、記事に有効なヘッダーがあり、特定のニュースグループに投稿する権利があることを前提としています）。

>>> s = nntplib.NNTP('news.gmane.io')
>>> f = open('article.txt', 'rb')
>>> s.post(f)
'240 Article posted successfully.'
>>> s.quit()
'205 Bye!'

モジュール自体は、次のクラスを定義します。

class nntplib.NNTP(host, port=119, user=None, password=None, readermode=None, usenetrc=False[, timeout])

ポートポートでリッスンしているホストホストで実行されているNNTPサーバーへの接続を表す新しい NNTP オブジェクトを返します。 オプションの timeout をソケット接続に指定できます。 オプションの user および password が提供されている場合、または適切な資格情報が/.netrcに存在し、オプションのフラグ usenetrc がtrueの場合、[ X171X] およびAUTHINFO PASSコマンドは、サーバーに対してユーザーを識別および認証するために使用されます。 オプションのフラグ readermode がtrueの場合、認証が実行される前にmode readerコマンドが送信されます。 ローカルマシン上のNNTPサーバーに接続していて、groupなどのリーダー固有のコマンドを呼び出す場合は、リーダーモードが必要になることがあります。 予期しない NNTPPermanentError が発生した場合は、 readermode を設定する必要があります。 NNTP クラスは、 with ステートメントをサポートして、 OSError 例外を無条件に消費し、完了したらNNTP接続を閉じます。

>>> from nntplib import NNTP
>>> with NNTP('news.gmane.io') as n:
...     n.group('gmane.comp.python.committers')
... 
('211 1755 1 1755 gmane.comp.python.committers', 1755, 1, 1755, 'gmane.comp.python.committers')
>>>

バージョン3.2で変更： usenetrc はデフォルトでFalseになりました。

バージョン3.3で変更： with ステートメントのサポートが追加されました。

class nntplib.NNTP_SSL(host, port=563, user=None, password=None, ssl_context=None, readermode=None, usenetrc=False[, timeout])

ポートポートでリッスンしているホストホストで実行されているNNTPサーバーへの暗号化された接続を表す新しい NNTP_SSL オブジェクトを返します。 NNTP_SSL オブジェクトには、 NNTP オブジェクトと同じメソッドがあります。 ポートを省略すると、ポート563（NNTPS）が使用されます。 ssl_context もオプションであり、 SSLContext オブジェクトです。 ベストプラクティスについては、セキュリティに関する考慮事項をお読みください。 他のすべてのパラメータは、 NNTP の場合と同じように動作します。

RFC 4642 に従って、SSL-on-563は推奨されておらず、以下で説明するSTARTTLSが優先されます。 ただし、一部のサーバーは前者のみをサポートします。

バージョン3.2の新機能。

バージョン3.4で変更：クラスは ssl.SSLContext.check_hostname および Server Name Indication によるホスト名チェックをサポートするようになりました（ ssl.HAS_SNI を参照） ）。

exception nntplib.NNTPError

標準例外 Exception から派生した、これは nntplib モジュールによって発生するすべての例外の基本クラスです。 このクラスのインスタンスには、次の属性があります。

response

str オブジェクトとしての、使用可能な場合のサーバーの応答。

exception nntplib.NNTPReplyError

サーバーから予期しない応答を受信すると、例外が発生します。

exception nntplib.NNTPTemporaryError

400〜499の範囲の応答コードを受信すると例外が発生します。

exception nntplib.NNTPPermanentError

500〜599の範囲の応答コードを受信すると例外が発生します。

exception nntplib.NNTPProtocolError

1〜5の範囲の数字で始まらない応答をサーバーから受信すると、例外が発生します。

exception nntplib.NNTPDataError

応答データにエラーがある場合に例外が発生します。

NNTPオブジェクト

接続すると、 NNTP および NNTP_SSL オブジェクトは次のメソッドと属性をサポートします。

属性

NNTP.nntp_version

サーバーでサポートされているNNTPプロトコルのバージョンを表す整数。 実際には、これは、 RFC 3977 準拠をアドバタイズするサーバーの場合は2、その他のサーバーの場合は1である必要があります。

バージョン3.2の新機能。

NNTP.nntp_implementation

NNTPサーバーのソフトウェア名とバージョンを説明する文字列。サーバーによってアドバタイズされていない場合は None 。

バージョン3.2の新機能。

メソッド

ほとんどすべてのメソッドの戻りタプルの最初の項目として返される response は、サーバーの応答、つまり3桁のコードで始まる文字列です。 サーバーの応答がエラーを示している場合、メソッドは上記の例外の1つを発生させます。

次のメソッドの多くは、オプションのキーワードのみの引数 file を取ります。 file 引数を指定する場合は、バイナリ書き込み用に開いた fileオブジェクトか、書き込むディスク上のファイルの名前のいずれかである必要があります。 次に、このメソッドは、サーバーから返されたすべてのデータ（応答行と終了ドットを除く）をファイルに書き込みます。 メソッドが通常返す行、タプル、またはオブジェクトのリストはすべて空になります。

バージョン3.2で変更：次のメソッドの多くが作り直されて修正されたため、3.1の対応するメソッドと互換性がなくなりました。

NNTP.quit()

QUITコマンドを送信して、接続を閉じます。 このメソッドが呼び出されると、NNTPオブジェクトの他のメソッドは呼び出されません。

NNTP.getwelcome()

最初の接続に応答してサーバーから送信されたウェルカムメッセージを返します。 （このメッセージには、ユーザーに関連する可能性のある免責事項またはヘルプ情報が含まれている場合があります。）

NNTP.getcapabilities()

サーバーによってアドバタイズされた RFC 3977 機能を、 dict インスタンスマッピング機能名として（おそらく空の）値のリストとして返します。 CAPABILITIESコマンドを理解しないレガシーサーバーでは、代わりに空の辞書が返されます。

>>> s = NNTP('news.gmane.io')
>>> 'POST' in s.getcapabilities()
True

バージョン3.2の新機能。

NNTP.login(user=None, password=None, usenetrc=True)

AUTHINFOコマンドをユーザー名とパスワードとともに送信します。 user と password がNoneで、 usenetrc がtrueの場合、可能であれば~/.netrcの資格情報が使用されます。

意図的に遅延させない限り、ログインは通常 NNTP オブジェクトの初期化中に実行され、この関数を個別に呼び出す必要はありません。 認証を強制的に遅らせるには、オブジェクトの作成時に user または password を設定せず、 usenetrc をFalseに設定する必要があります。

バージョン3.2の新機能。

NNTP.starttls(context=None)

STARTTLSコマンドを送信します。 これにより、NNTP接続で暗号化が有効になります。 context 引数はオプションであり、 ssl.SSLContext オブジェクトである必要があります。 ベストプラクティスについては、セキュリティに関する考慮事項をお読みください。

これは、認証情報が送信された後は実行できない場合があり、 NNTP オブジェクトの初期化中に、可能であればデフォルトで認証が行われることに注意してください。 この動作の抑制については、 NNTP.login（）を参照してください。

バージョン3.2の新機能。

バージョン3.4で変更：このメソッドは、 ssl.SSLContext.check_hostname および Server Name Indication によるホスト名チェックをサポートするようになりました（ ssl.HAS_SNI を参照） ）。

NNTP.newgroups(date, *, file=None)

NEWGROUPSコマンドを送信します。 date 引数は、 datetime.date または datetime.datetime オブジェクトである必要があります。 ペア(response, groups)を返します。ここで、 groups は、指定された date 以降に新しいグループを表すリストです。 ただし、ファイルが指定されている場合、グループは空になります。

>>> from datetime import date, timedelta
>>> resp, groups = s.newgroups(date.today() - timedelta(days=3))
>>> len(groups) 
85
>>> groups[0] 
GroupInfo(group='gmane.network.tor.devel', last='4', first='1', flag='m')

NNTP.newnews(group, date, *, file=None)

NEWNEWSコマンドを送信します。 ここで、 group はグループ名または'*'であり、 date は newgroups（）と同じ意味です。 ペア(response, articles)を返します。ここで、 articles はメッセージIDのリストです。

このコマンドは、NNTPサーバー管理者によって頻繁に無効にされます。

NNTP.list(group_pattern=None, *, file=None)

LISTまたはLIST ACTIVEコマンドを送信します。 ペア(response, list)を返します。ここで、 list は、このNNTPサーバーから利用可能なすべてのグループを表すタプルのリストであり、オプションでパターン文字列 group_pattern と一致します。 各タプルの形式は(group, last, first, flag)です。ここで、 group はグループ名、 last および first は最後と最初の記事番号、[ X150X] flag は通常、次のいずれかの値を取ります。

• y：ピアからのローカル投稿と記事が許可されます。

• m：グループはモデレートされており、すべての投稿が承認される必要があります。

• n：ローカル投稿は許可されていません。ピアからの記事のみが許可されています。

• j：ピアからの記事は、代わりにジャンクグループにファイルされます。

• x：ローカル投稿はなく、ピアからの記事は無視されます。

• =foo.bar：代わりにfoo.barグループに記事が提出されます。

flag に別の値がある場合、ニュースグループのステータスは不明と見なす必要があります。

このコマンドは、特に group_pattern が指定されていない場合、非常に大きな結果を返す可能性があります。 本当に更新する必要がない限り、結果をオフラインでキャッシュすることをお勧めします。

バージョン3.2で変更： group_pattern が追加されました。

NNTP.descriptions(grouppattern)

LIST NEWSGROUPSコマンドを送信します。ここで、 grouppattern は、 RFC 3977 で指定されているワイルドマット文字列です（基本的にDOSまたはUNIXシェルのワイルドカードと同じです）。文字列）。 ペア(response, descriptions)を返します。ここで、 description は、グループ名をテキストの説明にマッピングする辞書です。

>>> resp, descs = s.descriptions('gmane.comp.python.*')
>>> len(descs) 
295
>>> descs.popitem() 
('gmane.comp.python.bio.general', 'BioPython discussion list (Moderated)')

NNTP.description(group)

単一のグループグループの説明を取得します。 複数のグループが一致する場合（「group」が実際のワイルドマット文字列の場合）、最初の一致を返します。 一致するグループがない場合は、空の文字列を返します。

これにより、サーバーからの応答コードが削除されます。 応答コードが必要な場合は、 description（）を使用してください。

NNTP.group(name)

GROUPコマンドを送信します。ここで、 name はグループ名です。 グループが存在する場合は、現在のグループとして選択されます。 タプル(response, count, first, last, name)を返します。ここで、 count はグループ内の（推定）記事数、 first はグループ内の最初の記事番号、 last [ X163X]はグループの最後の記事番号であり、 name はグループ名です。

NNTP.over(message_spec, *, file=None)

レガシーサーバーでOVERコマンドまたはXOVERコマンドを送信します。 message_spec は、メッセージIDを表す文字列、現在のグループの記事の範囲を示す(first, last)タプル、または範囲を示す(first, None)タプルのいずれかです。 最初から現在のグループの最後の記事までの記事、またはなしで現在のグループの現在の記事を選択します。

ペア(response, overviews)を返します。 概要は、(article_number, overview)タプルのリストであり、 message_spec によって選択された記事ごとに1つです。 各概要は同じ数のアイテムを持つ辞書ですが、この数はサーバーによって異なります。 これらのアイテムは、メッセージヘッダー（キーは小文字のヘッダー名）またはメタデータアイテム（キーは":"が前に付いたメタデータ名）のいずれかです。 次のアイテムは、NNTP仕様によって存在することが保証されています。

• subject、from、date、message-id、およびreferencesヘッダー

• :bytesメタデータ：生の記事全体（ヘッダーと本文を含む）のバイト数

• :linesメタデータ：記事本文の行数

各項目の値は文字列であるか、存在しない場合は None です。

非ASCII文字が含まれている可能性がある場合は、ヘッダー値に decode_header（）関数を使用することをお勧めします。

>>> _, _, first, last, _ = s.group('gmane.comp.python.devel')
>>> resp, overviews = s.over((last, last))
>>> art_num, over = overviews[0]
>>> art_num
117216
>>> list(over.keys())
['xref', 'from', ':lines', ':bytes', 'references', 'date', 'message-id', 'subject']
>>> over['from']
'=?UTF-8?B?Ik1hcnRpbiB2LiBMw7Z3aXMi?= <[email protected]>'
>>> nntplib.decode_header(over['from'])
'"Martin v. Löwis" <[email protected]>'

バージョン3.2の新機能。

NNTP.help(*, file=None)

HELPコマンドを送信します。 ペア(response, list)を返します。ここで、 list はヘルプ文字列のリストです。

NNTP.stat(message_spec=None)

STATコマンドを送信します。ここで、 message_spec は、メッセージID（'<'および'>'で囲まれています）または現在のグループの記事番号です。 message_spec が省略されているか、 None の場合、現在のグループの現在の記事が考慮されます。 トリプル(response, number, id)を返します。ここで、 number は記事番号、 id はメッセージIDです。

>>> _, _, first, last, _ = s.group('gmane.comp.python.devel')
>>> resp, number, message_id = s.stat(first)
>>> number, message_id
(9099, '<[email protected]>')

NNTP.next()

NEXTコマンドを送信します。 stat（）と同様に戻ります。

NNTP.last()

LASTコマンドを送信します。 stat（）と同様に戻ります。

NNTP.article(message_spec=None, *, file=None)

ARTICLEコマンドを送信します。ここで、 message_spec は stat（）と同じ意味です。 タプル(response, info)を返します。ここで、 info は、 number 、 message_id 、 lines [の3つの属性を持つ namedtuple です。 X142X]（この順序で）。 number はグループ内の記事番号（または情報が利用できない場合は0）、 message_id は文字列としてのメッセージID、 lines はヘッダーと本文を含む生のメッセージを構成する行（改行を終了しない）。

>>> resp, info = s.article('<[email protected]>')
>>> info.number
0
>>> info.message_id
'<[email protected]>'
>>> len(info.lines)
65
>>> info.lines[0]
b'Path: main.gmane.org!not-for-mail'
>>> info.lines[1]
b'From: Neal Norwitz <[email protected]>'
>>> info.lines[-3:]
[b'There is a patch for 2.3 as well as 2.2.', b'', b'Neal']

NNTP.head(message_spec=None, *, file=None)

article（）と同じですが、HEADコマンドを送信します。 返される（またはファイルに書き込まれる） lines には、メッセージヘッダーのみが含まれ、本文は含まれません。

NNTP.body(message_spec=None, *, file=None)

article（）と同じですが、BODYコマンドを送信します。 返される（またはファイルに書き込まれる） lines には、ヘッダーではなくメッセージ本文のみが含まれます。

NNTP.post(data)

POSTコマンドを使用して記事を投稿します。 data 引数は、バイナリ読み取り用に開かれたファイルオブジェクト、または反復可能なバイトオブジェクト（投稿される記事の生の行を表す）のいずれかです。 必要なヘッダーを含む、整形式のニュース記事を表す必要があります。 post（）メソッドは、.で始まる行を自動的にエスケープし、終了行を追加します。

メソッドが成功すると、サーバーの応答が返されます。 サーバーが投稿を拒否した場合、 NNTPReplyError が発生します。

NNTP.ihave(message_id, data)

IHAVEコマンドを送信します。 message_id は、サーバーに送信するメッセージのIDです（'<'および'>'で囲まれています）。 data パラメーターと戻り値は、 post（）の場合と同じです。

NNTP.date()

ペア(response, date)を返します。 date は、サーバーの現在の日付と時刻を含む datetime オブジェクトです。

NNTP.slave()

SLAVEコマンドを送信します。 サーバーの応答を返します。

NNTP.set_debuglevel(level)

インスタンスのデバッグレベルを設定します。 これは、出力されるデバッグ出力の量を制御します。 デフォルトの0は、デバッグ出力を生成しません。 1の値は、適度な量のデバッグ出力を生成します。通常、要求または応答ごとに1行です。 2以上の値は、最大量のデバッグ出力を生成し、接続で送受信された各行（メッセージテキストを含む）をログに記録します。

以下は、 RFC 2980 で定義されているオプションのNNTP拡張機能です。 それらのいくつかは、 RFC 3977 の新しいコマンドに置き換えられました。

NNTP.xhdr(hdr, str, *, file=None)

XHDRコマンドを送信します。 hdr 引数は、ヘッダーキーワードです。例： 'subject'。 str 引数は、'first-last'の形式である必要があります。ここで、 first および last は、検索する最初と最後の記事番号です。 ペア(response, list)を返します。ここで、 list はペア(id, text)のリストです。ここで、 id は記事番号（文字列として）であり、[X134X ] text は、その記事に対して要求されたヘッダーのテキストです。 file パラメーターが指定されている場合、XHDRコマンドの出力はファイルに保存されます。 file が文字列の場合、メソッドはその名前のファイルを開き、そのファイルに書き込んでから閉じます。 file が fileオブジェクトの場合、コマンド出力の行を格納するためにwrite()の呼び出しを開始します。 file が指定されている場合、返される list は空のリストです。

NNTP.xover(start, end, *, file=None)

XOVERコマンドを送信します。 start および end は、選択する記事の範囲を区切る記事番号です。 戻り値は over（）の場合と同じです。 代わりに over（）を使用することをお勧めします。使用可能な場合は、新しいOVERコマンドが自動的に使用されるためです。

NNTP.xpath(id)

ペア(resp, path)を返します。ここで、 path は、メッセージID id の記事へのディレクトリパスです。 ほとんどの場合、この拡張機能はNNTPサーバー管理者によって有効にされていません。

バージョン3.3以降非推奨： XPATH拡張機能はアクティブに使用されていません。

ユーティリティ機能

このモジュールは、次のユーティリティ関数も定義します。

nntplib.decode_header(header_str)

ヘッダー値をデコードし、エスケープされた非ASCII文字をエスケープ解除します。 header_str は str オブジェクトである必要があります。 エスケープされていない値が返されます。 一部のヘッダーを人間が読める形式で表示するには、この関数を使用することをお勧めします。

>>> decode_header("Some subject")
'Some subject'
>>> decode_header("=?ISO-8859-15?Q?D=E9buter_en_Python?=")
'Débuter en Python'
>>> decode_header("Re: =?UTF-8?B?cHJvYmzDqG1lIGRlIG1hdHJpY2U=?=")
'Re: problème de matrice'