"telnetlib" --- Telnet クライアント
***********************************

**ソースコード:** Lib/telnetlib.py

======================================================================

"telnetlib" モジュールでは、Telnet プロトコルを実装している "Telnet"
クラスを提供します。Telnet プロトコルについての詳細は **RFC 854** を参
照してください。加えて、このモジュールでは Telnet プロトコルにおける制
御文字 (下を参照してください) と、telnet オプションに対するシンボル定
数を提供しています。telnet オプションに対するシンボル名は
"arpa/telnet.h" の "TELOPT_" がない状態での定義に従います。伝統的に
"arpa/telnet.h" に含められていない telnet オプションのシンボル名につい
ては、このモジュールのソースコード自体を参照してください。

telnet コマンドのシンボル定数は、IAC、DONT、DO、WONT、WILL、SE (サブネ
ゴシエーション終了)、NOP (何もしない)、DM (データマーク)、BRK (ブレー
ク)、IP (プロセス中断)、AO (出力停止)、AYT (応答確認)、EC (文字削除)、
EL (行削除)、GA (進め)、SB (サブネゴシエーション開始) です。

class telnetlib.Telnet(host=None, port=0[, timeout])

   "Telnet" は Telnet サーバへの接続を表現します。デフォルトでは、
   "Telnet" クラスのインスタンスは最初はサーバに接続していません。接続
   を確立するには "open()" を使わなければなりません。別の方法として、
   コンストラクタにホスト名とオプションのポート番号を渡すこともできま
   す。この場合はコンストラクタの呼び出しが返る以前にサーバへの接続が
   確立されます。オプション引数の *timeout* が渡された場合、コネクショ
   ン接続時のタイムアウト時間を秒数で指定します (指定されなかった場合
   は、グローバルのデフォルトタイムアウト設定が利用されます)。

   すでに接続の開かれているンスタンスを再度開いてはいけません。

   このクラスは多くの "read_*()" メソッドを持っています。これらのメソ
   ッドのいくつかは、接続の終端を示す文字を読み込んだ場合に "EOFError"
   を送出するので注意してください。例外を送出するのは、これらの関数が
   終端に到達しなくても空の文字列を返す可能性があるからです。詳しくは
   下記の個々の説明を参照してください。

   "Telnet" オブジェクトはコンテキストマネージャであり、 "with" 文で使
   えます。 "with" ブロックから抜けるとき、 "close()" メソッドが呼び出
   されます:

      >>> from telnetlib import Telnet
      >>> with Telnet('localhost', 23) as tn:
      ...     tn.interact()
      ...

   バージョン 3.6 で変更: コンテキストマネージャーサポートが追加されま
   した。

参考:

  **RFC 854** - Telnet プロトコル仕様
     Telnet プロトコルの定義。


Telnet オブジェクト
===================

"Telnet" インスタンスは以下のメソッドを持っています:

Telnet.read_until(expected, timeout=None)

   *expected* で指定されたバイト文字列を読み込むか、*timeout* で指定さ
   れた秒数が経過するまで読み込みます。

   与えられた文字列に一致する部分が見つからなかった場合、読み込むこと
   ができたもの全てを返します。これは空のバイト列になる可能性がありま
   す。接続が閉じられ、転送処理済みのデータが得られない場合には
   "EOFError" が送出されます。

Telnet.read_all()

   EOFに到達するまでの全てのデータをバイト列として読み込みます; 接続が
   閉じられるまでブロックします。

Telnet.read_some()

   EOF に到達しない限り、少なくとも 1 バイトの転送処理済みデータを読み
   込みます。EOF に到達した場合は "b''" を返します。すぐに読み出せるデ
   ータが存在しない場合にはブロックします。

Telnet.read_very_eager()

   I/O によるブロックを起こさずに読み出せる全てのデータを読み込みます
   (eager モード)。

   接続が閉じられており、転送処理済みのデータとして読み出せるものがな
   い場合には "EOFError" が送出されます。それ以外の場合で、単に読み出
   せるデータがない場合には "b''" を返します。 IAC シーケンス操作中で
   ないかぎりブロックしません。

Telnet.read_eager()

   現在すぐに読み出せるデータを読み出します。

   接続が閉じられており、転送処理済みのデータとして読み出せるものがな
   い場合には "EOFError" が送出されます。それ以外の場合で、単に読み出
   せるデータがない場合には "b''" を返します。 IAC シーケンス操作中で
   ないかぎりブロックしません。

Telnet.read_lazy()

   すでにキューに入っているデータを処理して返します (lazy モード)。

   接続が閉じられており、読み出せるデータがない場合には "EOFError" を
   送出します。それ以外の場合で、転送処理済みのデータで読み出せるもの
   がない場合には "b''" を返します。 IAC シーケンス操作中でないかぎり
   ブロックしません。

Telnet.read_very_lazy()

   すでに処理済みキューに入っているデータを処理して返します (very lazy
   モード)。

   接続が閉じられており、読み出せるデータがない場合には "EOFError" を
   送出します。それ以外の場合で、転送処理済みのデータで読み出せるもの
   がない場合には "b''" を返します。このメソッドは決してブロックしませ
   ん。

Telnet.read_sb_data()

   SB/SE ペア (サブオプション開始／終了) の間に収集されたデータを返し
   ます。 "SE" コマンドによって起動されたコールバック関数はこれらのデ
   ータにアクセスしなければなりません。このメソッドはけっしてブロック
   しません。

Telnet.open(host, port=0[, timeout])

   サーバホストに接続します。第二引数はオプションで、ポート番号を指定
   します。標準の値は通常の Telnet ポート番号 (23) です。オプション引
   数の *timeout* が渡された場合、コネクション接続時などのブロックする
   操作のタイムアウト時間を秒数で指定します (指定されなかった場合は、
   グローバルのデフォルトタイムアウト設定が利用されます)。

   すでに接続しているインスタンスで再接続を試みてはいけません。

   引数 "self", "host", "port" 付きで 監査イベント
   "telnetlib.Telnet.open" を送出します。

Telnet.msg(msg, *args)

   デバッグレベルが ">" 0 のとき、デバッグ用のメッセージを出力します。
   追加の引数が存在する場合、標準の文字列書式化演算子 "%" を使って
   *msg* 中の書式指定子に代入されます。

Telnet.set_debuglevel(debuglevel)

   デバッグレベルを設定します。 *debuglevel* が大きくなるほど、
   ("sys.stdout" に) デバッグメッセージがたくさん出力されます。

Telnet.close()

   コネクションをクローズします。

Telnet.get_socket()

   内部的に使われているソケットオブジェクトです。

Telnet.fileno()

   内部的に使われているソケットオブジェクトのファイル記述子です。

Telnet.write(buffer)

   ソケットにバイト文字列を書き込みます。このとき IAC 文字については
   2 度送信します。接続がブロックした場合、書き込みがブロックする可能
   性があります。接続が閉じられた場合、 "OSError"  が送出されるかもし
   れません。

   引数 "self", "buffer" 付きで 監査イベント "telnetlib.Telnet.write"
   を送出します。

   バージョン 3.3 で変更: このメソッドは以前は "socket.error" を投げて
   いましたが、これは現在では "OSError" の別名になっています。

Telnet.interact()

   非常に低機能の telnet クライアントをエミュレートする対話関数です。

Telnet.mt_interact()

   "interact()" のマルチスレッド版です。

Telnet.expect(list, timeout=None)

   正規表現のリストのうちどれか一つにマッチするまでデータを読みます。

   第一引数は正規表現のリストです。コンパイルされたもの (regex オブジ
   ェクト) でも、コンパイルされていないもの (バイト文字列) でもかまい
   ません。オプションの第二引数はタイムアウトで、単位は秒です。標準の
   値は無期限に設定されています。

   3 つの要素からなるタプル: 最初にマッチした正規表現のインデクス; 返
   されたマッチオブジェクト; マッチ部分を含む、マッチするまでに読み込
   まれたバイト列、を返します。

   ファイル終了子が見つかり、かつ何もバイト列が読み込まれなかった場合
   、 "EOFError" が送出されます。そうでない場合で何もマッチしなかった
   場合には "(-1, None, data)" が返されます。ここで *data* はこれまで
   受信したバイト列です (タイムアウトが発生した場合には空のバイト列に
   なる場合もあります)。

   正規表現の末尾が (".*" のような) 貪欲マッチングになっている場合や、
   入力に対して 1 つ以上の正規表現がマッチする場合には、その結果は決定
   不能で、I/O のタイミングに依存するでしょう。

Telnet.set_option_negotiation_callback(callback)

   telnet オプションが入力フローから読み込まれるたびに、 *callback* が
   (設定されていれば) 以下の引数形式: callback(telnet socket, command
   (DO/DONT/WILL/WONT), option) で呼び出されます。その後 telnet オプシ
   ョンに対しては telnetlib は何も行いません。


Telnet Example
==============

典型的な使用例のサンプルコード:

   import getpass
   import telnetlib

   HOST = "localhost"
   user = input("Enter your remote account: ")
   password = getpass.getpass()

   tn = telnetlib.Telnet(HOST)

   tn.read_until(b"login: ")
   tn.write(user.encode('ascii') + b"\n")
   if password:
       tn.read_until(b"Password: ")
       tn.write(password.encode('ascii') + b"\n")

   tn.write(b"ls\n")
   tn.write(b"exit\n")

   print(tn.read_all().decode('ascii'))
