telnetlib.rst 7.71 KB
Newer Older
1 2 3 4 5
:mod:`telnetlib` --- Telnet client
==================================

.. module:: telnetlib
   :synopsis: Telnet client class.
6

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

9
**Source code:** :source:`Lib/telnetlib.py`
10 11 12

.. index:: single: protocol; Telnet

Raymond Hettinger's avatar
Raymond Hettinger committed
13 14
--------------

15 16 17 18 19 20 21 22 23 24 25 26 27 28
The :mod:`telnetlib` module provides a :class:`Telnet` class that implements the
Telnet protocol.  See :rfc:`854` for details about the protocol. In addition, it
provides symbolic constants for the protocol characters (see below), and for the
telnet options. The symbolic names of the telnet options follow the definitions
in ``arpa/telnet.h``, with the leading ``TELOPT_`` removed. For symbolic names
of options which are traditionally not included in ``arpa/telnet.h``, see the
module source itself.

The symbolic constants for the telnet commands are: IAC, DONT, DO, WONT, WILL,
SE (Subnegotiation End), NOP (No Operation), DM (Data Mark), BRK (Break), IP
(Interrupt process), AO (Abort output), AYT (Are You There), EC (Erase
Character), EL (Erase Line), GA (Go Ahead), SB (Subnegotiation Begin).


29
.. class:: Telnet(host=None, port=0[, timeout])
30 31 32

   :class:`Telnet` represents a connection to a Telnet server. The instance is
   initially not connected by default; the :meth:`open` method must be used to
33
   establish a connection.  Alternatively, the host name and optional port
34
   number can be passed to the constructor too, in which case the connection to
35
   the server will be established before the constructor returns.  The optional
36
   *timeout* parameter specifies a timeout in seconds for blocking operations
37 38
   like the connection attempt (if not specified, the global default timeout
   setting will be used).
39 40 41 42 43 44 45

   Do not reopen an already connected instance.

   This class has many :meth:`read_\*` methods.  Note that some of them  raise
   :exc:`EOFError` when the end of the connection is read, because they can return
   an empty string for other reasons.  See the individual descriptions below.

46 47 48 49 50 51 52 53 54 55 56
   A :class:`Telnet` object is a context manager and can be used in a
   :keyword:`with` statement.  When the :keyword:`with` block ends, the
   :meth:`close` method is called::

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

   .. versionchanged:: 3.6 Context manager support added

57 58 59 60 61 62 63 64 65 66 67 68 69 70 71

.. seealso::

   :rfc:`854` - Telnet Protocol Specification
      Definition of the Telnet protocol.


.. _telnet-objects:

Telnet Objects
--------------

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


72
.. method:: Telnet.read_until(expected, timeout=None)
73

74 75
   Read until a given byte string, *expected*, is encountered or until *timeout*
   seconds have passed.
76

77 78 79
   When no match is found, return whatever is available instead, possibly empty
   bytes.  Raise :exc:`EOFError` if the connection is closed and no cooked data
   is available.
80 81 82 83


.. method:: Telnet.read_all()

84
   Read all data until EOF as bytes; block until connection closed.
85 86 87 88


.. method:: Telnet.read_some()

89 90
   Read at least one byte of cooked data unless EOF is hit. Return ``b''`` if
   EOF is hit.  Block if no data is immediately available.
91 92 93 94 95 96


.. method:: Telnet.read_very_eager()

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

97 98 99
   Raise :exc:`EOFError` if connection closed and no cooked data available.
   Return ``b''`` if no cooked data available otherwise. Do not block unless in
   the midst of an IAC sequence.
100 101 102 103 104 105


.. method:: Telnet.read_eager()

   Read readily available data.

106 107 108
   Raise :exc:`EOFError` if connection closed and no cooked data available.
   Return ``b''`` if no cooked data available otherwise. Do not block unless in
   the midst of an IAC sequence.
109 110 111 112 113 114


.. method:: Telnet.read_lazy()

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

115 116 117
   Raise :exc:`EOFError` if connection closed and no data available. Return
   ``b''`` if no cooked data available otherwise.  Do not block unless in the
   midst of an IAC sequence.
118 119 120 121 122 123


.. method:: Telnet.read_very_lazy()

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

124 125
   Raise :exc:`EOFError` if connection closed and no data available. Return
   ``b''`` if no cooked data available otherwise.  This method never blocks.
126 127 128 129 130 131 132 133 134


.. method:: Telnet.read_sb_data()

   Return the data collected between a SB/SE pair (suboption begin/end). The
   callback should access these data when it was invoked with a ``SE`` command.
   This method never blocks.


135
.. method:: Telnet.open(host, port=0[, timeout])
136 137 138

   Connect to a host. The optional second argument is the port number, which
   defaults to the standard Telnet port (23). The optional *timeout* parameter
139
   specifies a timeout in seconds for blocking operations like the connection
Georg Brandl's avatar
Georg Brandl committed
140
   attempt (if not specified, the global default timeout setting will be used).
141 142 143 144

   Do not try to reopen an already connected instance.


145
.. method:: Telnet.msg(msg, *args)
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174

   Print a debug message when the debug level is ``>`` 0. If extra arguments are
   present, they are substituted in the message using the standard string
   formatting operator.


.. method:: Telnet.set_debuglevel(debuglevel)

   Set the debug level.  The higher the value of *debuglevel*, the more debug
   output you get (on ``sys.stdout``).


.. method:: Telnet.close()

   Close the connection.


.. method:: Telnet.get_socket()

   Return the socket object used internally.


.. method:: Telnet.fileno()

   Return the file descriptor of the socket object used internally.


.. method:: Telnet.write(buffer)

175
   Write a byte string to the socket, doubling any IAC characters. This can
176
   block if the connection is blocked.  May raise :exc:`OSError` if the
177
   connection is closed.
178

179 180 181 182
   .. versionchanged:: 3.3
      This method used to raise :exc:`socket.error`, which is now an alias
      of :exc:`OSError`.

183 184 185 186 187 188 189 190 191 192 193

.. method:: Telnet.interact()

   Interaction function, emulates a very dumb Telnet client.


.. method:: Telnet.mt_interact()

   Multithreaded version of :meth:`interact`.


194
.. method:: Telnet.expect(list, timeout=None)
195 196 197 198

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

   The first argument is a list of regular expressions, either compiled
199
   (:ref:`regex objects <re-objects>`) or uncompiled (byte strings). The
200 201
   optional second argument is a timeout, in seconds; the default is to block
   indefinitely.
202 203

   Return a tuple of three items: the index in the list of the first regular
204 205
   expression that matches; the match object returned; and the bytes read up
   till and including the match.
206

207 208 209
   If end of file is found and no bytes were read, raise :exc:`EOFError`.
   Otherwise, when nothing matches, return ``(-1, None, data)`` where *data* is
   the bytes received so far (may be empty bytes if a timeout happened).
210 211

   If a regular expression ends with a greedy match (such as ``.*``) or if more
212
   than one expression can match the same input, the results are
Georg Brandl's avatar
Georg Brandl committed
213
   non-deterministic, and may depend on the I/O timing.
214 215 216 217 218


.. method:: Telnet.set_option_negotiation_callback(callback)

   Each time a telnet option is read on the input flow, this *callback* (if set) is
219
   called with the following parameters: callback(telnet socket, command
220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236
   (DO/DONT/WILL/WONT), option).  No other action is done afterwards by telnetlib.


.. _telnet-example:

Telnet Example
--------------

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


A simple example illustrating typical use::

   import getpass
   import telnetlib

   HOST = "localhost"
237
   user = input("Enter your remote account: ")
238 239 240 241
   password = getpass.getpass()

   tn = telnetlib.Telnet(HOST)

242 243
   tn.read_until(b"login: ")
   tn.write(user.encode('ascii') + b"\n")
244
   if password:
245 246
       tn.read_until(b"Password: ")
       tn.write(password.encode('ascii') + b"\n")
247

248 249
   tn.write(b"ls\n")
   tn.write(b"exit\n")
250

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