# `telnetlib` --- Telnet クライアント

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

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The `telnetlib` module is deprecated (see PEP 594 for details and alternatives).

`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 (サブネゴシエーション開始) です。

利用可能性: Emscripten でなく、WASI でもないこと。

このモジュールは WebAssembly プラットフォーム `wasm32-emscripten` と `wasm32-wasi` では動作しないか、利用不可です。詳しくは、WebAssemblyプラットフォーム を見てください。

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'))