1:mod:`telnetlib` --- Telnet client
2==================================
3
4.. module:: telnetlib
5   :synopsis: Telnet client class.
6
7.. sectionauthor:: Skip Montanaro <skip@pobox.com>
8
9**Source code:** :source:`Lib/telnetlib.py`
10
11.. index:: single: protocol; Telnet
12
13--------------
14
15The :mod:`telnetlib` module provides a :class:`Telnet` class that implements the
16Telnet protocol.  See :rfc:`854` for details about the protocol. In addition, it
17provides symbolic constants for the protocol characters (see below), and for the
18telnet options. The symbolic names of the telnet options follow the definitions
19in ``arpa/telnet.h``, with the leading ``TELOPT_`` removed. For symbolic names
20of options which are traditionally not included in ``arpa/telnet.h``, see the
21module source itself.
22
23The symbolic constants for the telnet commands are: IAC, DONT, DO, WONT, WILL,
24SE (Subnegotiation End), NOP (No Operation), DM (Data Mark), BRK (Break), IP
25(Interrupt process), AO (Abort output), AYT (Are You There), EC (Erase
26Character), EL (Erase Line), GA (Go Ahead), SB (Subnegotiation Begin).
27
28
29.. class:: Telnet(host=None, port=0[, timeout])
30
31   :class:`Telnet` represents a connection to a Telnet server. The instance is
32   initially not connected by default; the :meth:`~Telnet.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   like the connection attempt (if not specified, the global default timeout
38   setting will be used).
39
40   Do not reopen an already connected instance.
41
42   This class has many :meth:`read_\*` methods.  Note that some of them  raise
43   :exc:`EOFError` when the end of the connection is read, because they can return
44   an empty string for other reasons.  See the individual descriptions below.
45
46   A :class:`Telnet` object is a context manager and can be used in a
47   :keyword:`with` statement.  When the :keyword:`!with` block ends, the
48   :meth:`close` method is called::
49
50       >>> from telnetlib import Telnet
51       >>> with Telnet('localhost', 23) as tn:
52       ...     tn.interact()
53       ...
54
55   .. versionchanged:: 3.6 Context manager support added
56
57
58.. seealso::
59
60   :rfc:`854` - Telnet Protocol Specification
61      Definition of the Telnet protocol.
62
63
64.. _telnet-objects:
65
66Telnet Objects
67--------------
68
69:class:`Telnet` instances have the following methods:
70
71
72.. method:: Telnet.read_until(expected, timeout=None)
73
74   Read until a given byte string, *expected*, is encountered or until *timeout*
75   seconds have passed.
76
77   When no match is found, return whatever is available instead, possibly empty
78   bytes.  Raise :exc:`EOFError` if the connection is closed and no cooked data
79   is available.
80
81
82.. method:: Telnet.read_all()
83
84   Read all data until EOF as bytes; block until connection closed.
85
86
87.. method:: Telnet.read_some()
88
89   Read at least one byte of cooked data unless EOF is hit. Return ``b''`` if
90   EOF is hit.  Block if no data is immediately available.
91
92
93.. method:: Telnet.read_very_eager()
94
95   Read everything that can be without blocking in I/O (eager).
96
97   Raise :exc:`EOFError` if connection closed and no cooked data available.
98   Return ``b''`` if no cooked data available otherwise. Do not block unless in
99   the midst of an IAC sequence.
100
101
102.. method:: Telnet.read_eager()
103
104   Read readily available data.
105
106   Raise :exc:`EOFError` if connection closed and no cooked data available.
107   Return ``b''`` if no cooked data available otherwise. Do not block unless in
108   the midst of an IAC sequence.
109
110
111.. method:: Telnet.read_lazy()
112
113   Process and return data already in the queues (lazy).
114
115   Raise :exc:`EOFError` if connection closed and no data available. Return
116   ``b''`` if no cooked data available otherwise.  Do not block unless in the
117   midst of an IAC sequence.
118
119
120.. method:: Telnet.read_very_lazy()
121
122   Return any data available in the cooked queue (very lazy).
123
124   Raise :exc:`EOFError` if connection closed and no data available. Return
125   ``b''`` if no cooked data available otherwise.  This method never blocks.
126
127
128.. method:: Telnet.read_sb_data()
129
130   Return the data collected between a SB/SE pair (suboption begin/end). The
131   callback should access these data when it was invoked with a ``SE`` command.
132   This method never blocks.
133
134
135.. method:: Telnet.open(host, port=0[, timeout])
136
137   Connect to a host. The optional second argument is the port number, which
138   defaults to the standard Telnet port (23). The optional *timeout* parameter
139   specifies a timeout in seconds for blocking operations like the connection
140   attempt (if not specified, the global default timeout setting will be used).
141
142   Do not try to reopen an already connected instance.
143
144   .. audit-event:: telnetlib.Telnet.open self,host,port telnetlib.Telnet.open
145
146
147.. method:: Telnet.msg(msg, *args)
148
149   Print a debug message when the debug level is ``>`` 0. If extra arguments are
150   present, they are substituted in the message using the standard string
151   formatting operator.
152
153
154.. method:: Telnet.set_debuglevel(debuglevel)
155
156   Set the debug level.  The higher the value of *debuglevel*, the more debug
157   output you get (on ``sys.stdout``).
158
159
160.. method:: Telnet.close()
161
162   Close the connection.
163
164
165.. method:: Telnet.get_socket()
166
167   Return the socket object used internally.
168
169
170.. method:: Telnet.fileno()
171
172   Return the file descriptor of the socket object used internally.
173
174
175.. method:: Telnet.write(buffer)
176
177   Write a byte string to the socket, doubling any IAC characters. This can
178   block if the connection is blocked.  May raise :exc:`OSError` if the
179   connection is closed.
180
181   .. audit-event:: telnetlib.Telnet.write self,buffer telnetlib.Telnet.write
182
183   .. versionchanged:: 3.3
184      This method used to raise :exc:`socket.error`, which is now an alias
185      of :exc:`OSError`.
186
187
188.. method:: Telnet.interact()
189
190   Interaction function, emulates a very dumb Telnet client.
191
192
193.. method:: Telnet.mt_interact()
194
195   Multithreaded version of :meth:`interact`.
196
197
198.. method:: Telnet.expect(list, timeout=None)
199
200   Read until one from a list of a regular expressions matches.
201
202   The first argument is a list of regular expressions, either compiled
203   (:ref:`regex objects <re-objects>`) or uncompiled (byte strings). The
204   optional second argument is a timeout, in seconds; the default is to block
205   indefinitely.
206
207   Return a tuple of three items: the index in the list of the first regular
208   expression that matches; the match object returned; and the bytes read up
209   till and including the match.
210
211   If end of file is found and no bytes were read, raise :exc:`EOFError`.
212   Otherwise, when nothing matches, return ``(-1, None, data)`` where *data* is
213   the bytes received so far (may be empty bytes if a timeout happened).
214
215   If a regular expression ends with a greedy match (such as ``.*``) or if more
216   than one expression can match the same input, the results are
217   non-deterministic, and may depend on the I/O timing.
218
219
220.. method:: Telnet.set_option_negotiation_callback(callback)
221
222   Each time a telnet option is read on the input flow, this *callback* (if set) is
223   called with the following parameters: callback(telnet socket, command
224   (DO/DONT/WILL/WONT), option).  No other action is done afterwards by telnetlib.
225
226
227.. _telnet-example:
228
229Telnet Example
230--------------
231
232.. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>
233
234
235A simple example illustrating typical use::
236
237   import getpass
238   import telnetlib
239
240   HOST = "localhost"
241   user = input("Enter your remote account: ")
242   password = getpass.getpass()
243
244   tn = telnetlib.Telnet(HOST)
245
246   tn.read_until(b"login: ")
247   tn.write(user.encode('ascii') + b"\n")
248   if password:
249       tn.read_until(b"Password: ")
250       tn.write(password.encode('ascii') + b"\n")
251
252   tn.write(b"ls\n")
253   tn.write(b"exit\n")
254
255   print(tn.read_all().decode('ascii'))
256
257