Doc/library/telnetlib.rst

   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