1 

     2 :mod:`telnetlib` --- Telnet client

     3 ==================================

     4 

     5 .. module:: telnetlib

     6    :synopsis: Telnet client class.

     7 .. sectionauthor:: Skip Montanaro <skip@pobox.com>

     8 

     9 

    10 .. index:: single: protocol; Telnet

    11 

    12 The :mod:`telnetlib` module provides a :class:`Telnet` class that implements the

    13 Telnet protocol.  See :rfc:`854` for details about the protocol. In addition, it

    14 provides symbolic constants for the protocol characters (see below), and for the

    15 telnet options. The symbolic names of the telnet options follow the definitions

    16 in ``arpa/telnet.h``, with the leading ``TELOPT_`` removed. For symbolic names

    17 of options which are traditionally not included in ``arpa/telnet.h``, see the

    18 module source itself.

    19 

    20 The symbolic constants for the telnet commands are: IAC, DONT, DO, WONT, WILL,

    21 SE (Subnegotiation End), NOP (No Operation), DM (Data Mark), BRK (Break), IP

    22 (Interrupt process), AO (Abort output), AYT (Are You There), EC (Erase

    23 Character), EL (Erase Line), GA (Go Ahead), SB (Subnegotiation Begin).

    24 

    25 

    26 .. class:: Telnet([host[, port[, timeout]]])

    27 

    28    :class:`Telnet` represents a connection to a Telnet server. The instance is

    29    initially not connected by default; the :meth:`open` method must be used to

    30    establish a connection.  Alternatively, the host name and optional port

    31    and timeout can be passed to the constructor, in which case the connection to

    32    the server will be established before the constructor returns.  The optional

    33    *timeout* parameter specifies a timeout in seconds for the connection attempt (if

    34    not specified, the global default timeout setting will be used).

    35 

    36    number can be passed to the constructor, to, in which case the connection to

    37    the server will be established before the constructor returns. The optional

    38    *timeout* parameter specifies a timeout in seconds for blocking operations

    39    like the connection attempt (if not specified, or passed as None, the global

    40    default timeout setting will be used).

    41 

    42    Do not reopen an already connected instance.

    43 

    44    This class has many :meth:`read_\*` methods.  Note that some of them  raise

    45    :exc:`EOFError` when the end of the connection is read, because they can return

    46    an empty string for other reasons.  See the individual descriptions below.

    47 

    48    .. versionchanged:: 2.6

    49       *timeout* was added.

    50 

    51 

    52 .. seealso::

    53 

    54    :rfc:`854` - Telnet Protocol Specification

    55       Definition of the Telnet protocol.

    56 

    57 

    58 .. _telnet-objects:

    59 

    60 Telnet Objects

    61 --------------

    62 

    63 :class:`Telnet` instances have the following methods:

    64 

    65 

    66 .. method:: Telnet.read_until(expected[, timeout])

    67 

    68    Read until a given string, *expected*, is encountered or until *timeout* seconds

    69    have passed.

    70 

    71    When no match is found, return whatever is available instead, possibly the empty

    72    string.  Raise :exc:`EOFError` if the connection is closed and no cooked data is

    73    available.

    74 

    75 

    76 .. method:: Telnet.read_all()

    77 

    78    Read all data until EOF; block until connection closed.

    79 

    80 

    81 .. method:: Telnet.read_some()

    82 

    83    Read at least one byte of cooked data unless EOF is hit. Return ``''`` if EOF is

    84    hit.  Block if no data is immediately available.

    85 

    86 

    87 .. method:: Telnet.read_very_eager()

    88 

    89    Read everything that can be without blocking in I/O (eager).

    90 

    91    Raise :exc:`EOFError` if connection closed and no cooked data available.  Return

    92    ``''`` if no cooked data available otherwise. Do not block unless in the midst

    93    of an IAC sequence.

    94 

    95 

    96 .. method:: Telnet.read_eager()

    97 

    98    Read readily available data.

    99 

   100    Raise :exc:`EOFError` if connection closed and no cooked data available.  Return

   101    ``''`` if no cooked data available otherwise. Do not block unless in the midst

   102    of an IAC sequence.

   103 

   104 

   105 .. method:: Telnet.read_lazy()

   106 

   107    Process and return data already in the queues (lazy).

   108 

   109    Raise :exc:`EOFError` if connection closed and no data available. Return ``''``

   110    if no cooked data available otherwise.  Do not block unless in the midst of an

   111    IAC sequence.

   112 

   113 

   114 .. method:: Telnet.read_very_lazy()

   115 

   116    Return any data available in the cooked queue (very lazy).

   117 

   118    Raise :exc:`EOFError` if connection closed and no data available. Return ``''``

   119    if no cooked data available otherwise.  This method never blocks.

   120 

   121 

   122 .. method:: Telnet.read_sb_data()

   123 

   124    Return the data collected between a SB/SE pair (suboption begin/end). The

   125    callback should access these data when it was invoked with a ``SE`` command.

   126    This method never blocks.

   127 

   128    .. versionadded:: 2.3

   129 

   130 

   131 .. method:: Telnet.open(host[, port[, timeout]])

   132 

   133    Connect to a host. The optional second argument is the port number, which

   134    defaults to the standard Telnet port (23). The optional *timeout* parameter

   135    specifies a timeout in seconds for blocking operations like the connection

   136    attempt (if not specified, the global default timeout setting will be used).

   137 

   138    Do not try to reopen an already connected instance.

   139 

   140    .. versionchanged:: 2.6

   141       *timeout* was added.

   142 

   143 

   144 .. method:: Telnet.msg(msg[, *args])

   145 

   146    Print a debug message when the debug level is ``>`` 0. If extra arguments are

   147    present, they are substituted in the message using the standard string

   148    formatting operator.

   149 

   150 

   151 .. method:: Telnet.set_debuglevel(debuglevel)

   152 

   153    Set the debug level.  The higher the value of *debuglevel*, the more debug

   154    output you get (on ``sys.stdout``).

   155 

   156 

   157 .. method:: Telnet.close()

   158 

   159    Close the connection.

   160 

   161 

   162 .. method:: Telnet.get_socket()

   163 

   164    Return the socket object used internally.

   165 

   166 

   167 .. method:: Telnet.fileno()

   168 

   169    Return the file descriptor of the socket object used internally.

   170 

   171 

   172 .. method:: Telnet.write(buffer)

   173 

   174    Write a string to the socket, doubling any IAC characters. This can block if the

   175    connection is blocked.  May raise :exc:`socket.error` if the connection is

   176    closed.

   177 

   178 

   179 .. method:: Telnet.interact()

   180 

   181    Interaction function, emulates a very dumb Telnet client.

   182 

   183 

   184 .. method:: Telnet.mt_interact()

   185 

   186    Multithreaded version of :meth:`interact`.

   187 

   188 

   189 .. method:: Telnet.expect(list[, timeout])

   190 

   191    Read until one from a list of a regular expressions matches.

   192 

   193    The first argument is a list of regular expressions, either compiled

   194    (:class:`re.RegexObject` instances) or uncompiled (strings). The optional second

   195    argument is a timeout, in seconds; the default is to block indefinitely.

   196 

   197    Return a tuple of three items: the index in the list of the first regular

   198    expression that matches; the match object returned; and the text read up till

   199    and including the match.

   200 

   201    If end of file is found and no text was read, raise :exc:`EOFError`.  Otherwise,

   202    when nothing matches, return ``(-1, None, text)`` where *text* is the text

   203    received so far (may be the empty string if a timeout happened).

   204 

   205    If a regular expression ends with a greedy match (such as ``.*``) or if more

   206    than one expression can match the same input, the results are indeterministic,

   207    and may depend on the I/O timing.

   208 

   209 

   210 .. method:: Telnet.set_option_negotiation_callback(callback)

   211 

   212    Each time a telnet option is read on the input flow, this *callback* (if set) is

   213    called with the following parameters : callback(telnet socket, command

   214    (DO/DONT/WILL/WONT), option).  No other action is done afterwards by telnetlib.

   215 

   216 

   217 .. _telnet-example:

   218 

   219 Telnet Example

   220 --------------

   221 

   222 .. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>

   223 

   224 

   225 A simple example illustrating typical use::

   226 

   227    import getpass

   228    import sys

   229    import telnetlib

   230 

   231    HOST = "localhost"

   232    user = raw_input("Enter your remote account: ")

   233    password = getpass.getpass()

   234 

   235    tn = telnetlib.Telnet(HOST)

   236 

   237    tn.read_until("login: ")

   238    tn.write(user + "\n")

   239    if password:

   240        tn.read_until("Password: ")

   241        tn.write(password + "\n")

   242 

   243    tn.write("ls\n")

   244    tn.write("exit\n")

   245 

   246    print tn.read_all()

   247