2 :mod:`telnetlib` --- Telnet client
3 ==================================
6 :synopsis: Telnet client class.
7 .. sectionauthor:: Skip Montanaro <skip@pobox.com>
10 .. index:: single: protocol; Telnet
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
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).
26 .. class:: Telnet([host[, port[, timeout]]])
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 number can be passed to the constructor, to, 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 blocking operations
34 like the connection attempt (if not specified, the global default timeout
35 setting will be used).
37 Do not reopen an already connected instance.
39 This class has many :meth:`read_\*` methods. Note that some of them raise
40 :exc:`EOFError` when the end of the connection is read, because they can return
41 an empty string for other reasons. See the individual descriptions below.
43 .. versionchanged:: 2.6
49 :rfc:`854` - Telnet Protocol Specification
50 Definition of the Telnet protocol.
58 :class:`Telnet` instances have the following methods:
61 .. method:: Telnet.read_until(expected[, timeout])
63 Read until a given string, *expected*, is encountered or until *timeout* seconds
66 When no match is found, return whatever is available instead, possibly the empty
67 string. Raise :exc:`EOFError` if the connection is closed and no cooked data is
71 .. method:: Telnet.read_all()
73 Read all data until EOF; block until connection closed.
76 .. method:: Telnet.read_some()
78 Read at least one byte of cooked data unless EOF is hit. Return ``''`` if EOF is
79 hit. Block if no data is immediately available.
82 .. method:: Telnet.read_very_eager()
84 Read everything that can be without blocking in I/O (eager).
86 Raise :exc:`EOFError` if connection closed and no cooked data available. Return
87 ``''`` if no cooked data available otherwise. Do not block unless in the midst
91 .. method:: Telnet.read_eager()
93 Read readily available data.
95 Raise :exc:`EOFError` if connection closed and no cooked data available. Return
96 ``''`` if no cooked data available otherwise. Do not block unless in the midst
100 .. method:: Telnet.read_lazy()
102 Process and return data already in the queues (lazy).
104 Raise :exc:`EOFError` if connection closed and no data available. Return ``''``
105 if no cooked data available otherwise. Do not block unless in the midst of an
109 .. method:: Telnet.read_very_lazy()
111 Return any data available in the cooked queue (very lazy).
113 Raise :exc:`EOFError` if connection closed and no data available. Return ``''``
114 if no cooked data available otherwise. This method never blocks.
117 .. method:: Telnet.read_sb_data()
119 Return the data collected between a SB/SE pair (suboption begin/end). The
120 callback should access these data when it was invoked with a ``SE`` command.
121 This method never blocks.
123 .. versionadded:: 2.3
126 .. method:: Telnet.open(host[, port[, timeout]])
128 Connect to a host. The optional second argument is the port number, which
129 defaults to the standard Telnet port (23). The optional *timeout* parameter
130 specifies a timeout in seconds for blocking operations like the connection
131 attempt (if not specified, the global default timeout setting will be used).
133 Do not try to reopen an already connected instance.
135 .. versionchanged:: 2.6
139 .. method:: Telnet.msg(msg[, *args])
141 Print a debug message when the debug level is ``>`` 0. If extra arguments are
142 present, they are substituted in the message using the standard string
146 .. method:: Telnet.set_debuglevel(debuglevel)
148 Set the debug level. The higher the value of *debuglevel*, the more debug
149 output you get (on ``sys.stdout``).
152 .. method:: Telnet.close()
154 Close the connection.
157 .. method:: Telnet.get_socket()
159 Return the socket object used internally.
162 .. method:: Telnet.fileno()
164 Return the file descriptor of the socket object used internally.
167 .. method:: Telnet.write(buffer)
169 Write a string to the socket, doubling any IAC characters. This can block if the
170 connection is blocked. May raise :exc:`socket.error` if the connection is
174 .. method:: Telnet.interact()
176 Interaction function, emulates a very dumb Telnet client.
179 .. method:: Telnet.mt_interact()
181 Multithreaded version of :meth:`interact`.
184 .. method:: Telnet.expect(list[, timeout])
186 Read until one from a list of a regular expressions matches.
188 The first argument is a list of regular expressions, either compiled
189 (:class:`re.RegexObject` instances) or uncompiled (strings). The optional second
190 argument is a timeout, in seconds; the default is to block indefinitely.
192 Return a tuple of three items: the index in the list of the first regular
193 expression that matches; the match object returned; and the text read up till
194 and including the match.
196 If end of file is found and no text was read, raise :exc:`EOFError`. Otherwise,
197 when nothing matches, return ``(-1, None, text)`` where *text* is the text
198 received so far (may be the empty string if a timeout happened).
200 If a regular expression ends with a greedy match (such as ``.*``) or if more
201 than one expression can match the same input, the results are
202 non-deterministic, and may depend on the I/O timing.
205 .. method:: Telnet.set_option_negotiation_callback(callback)
207 Each time a telnet option is read on the input flow, this *callback* (if set) is
208 called with the following parameters : callback(telnet socket, command
209 (DO/DONT/WILL/WONT), option). No other action is done afterwards by telnetlib.
217 .. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>
220 A simple example illustrating typical use::
227 user = raw_input("Enter your remote account: ")
228 password = getpass.getpass()
230 tn = telnetlib.Telnet(HOST)
232 tn.read_until("login: ")
233 tn.write(user + "\n")
235 tn.read_until("Password: ")
236 tn.write(password + "\n")