rest25/library/telnetlib.rst => rest262/library/telnetlib.rst
f1
2:mod:`telnetlib` --- Telnet client
3==================================
4
5.. module:: telnetlib
6   :synopsis: Telnet client class.
n7-.. sectionauthor:: Skip Montanaro <skip@mojam.com>
n7+.. sectionauthor:: Skip Montanaro <skip@pobox.com>
8
9
10.. index:: single: protocol; Telnet
11
12The :mod:`telnetlib` module provides a :class:`Telnet` class that implements the
13Telnet protocol.  See :rfc:`854` for details about the protocol. In addition, it
14provides symbolic constants for the protocol characters (see below), and for the
15telnet options. The symbolic names of the telnet options follow the definitions
18module source itself.
19
20The symbolic constants for the telnet commands are: IAC, DONT, DO, WONT, WILL,
21SE (Subnegotiation End), NOP (No Operation), DM (Data Mark), BRK (Break), IP
22(Interrupt process), AO (Abort output), AYT (Are You There), EC (Erase
23Character), EL (Erase Line), GA (Go Ahead), SB (Subnegotiation Begin).
24
25
n26-.. class:: Telnet([host[, port]])
n26+.. 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
n30-   establish a connection.  Alternatively, the host name and optional port number
n30+   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+ 
31-   can be passed to the constructor, to, in which case the connection to the server
36+   number can be passed to the constructor, to, in which case the connection to
32-   will be established before the constructor returns.
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).
33
34   Do not reopen an already connected instance.
35
36   This class has many :meth:`read_\*` methods.  Note that some of them  raise
37   :exc:`EOFError` when the end of the connection is read, because they can return
38   an empty string for other reasons.  See the individual descriptions below.
39
n48+   .. versionchanged:: 2.6
49+      *timeout* was added.
50+ 
40
41.. seealso::
42
43   :rfc:`854` - Telnet Protocol Specification
44      Definition of the Telnet protocol.
45
46
47.. _telnet-objects:
48
49Telnet Objects
50--------------
51
52:class:`Telnet` instances have the following methods:
53
54
n55-.. method:: XXX Class.read_until(expected[, timeout])
n66+.. method:: Telnet.read_until(expected[, timeout])
56
57   Read until a given string, *expected*, is encountered or until *timeout* seconds
58   have passed.
59
60   When no match is found, return whatever is available instead, possibly the empty
61   string.  Raise :exc:`EOFError` if the connection is closed and no cooked data is
62   available.
63
64
n65-.. method:: XXX Class.read_all()
n76+.. method:: Telnet.read_all()
66
67   Read all data until EOF; block until connection closed.
68
69
n70-.. method:: XXX Class.read_some()
n81+.. method:: Telnet.read_some()
71
72   Read at least one byte of cooked data unless EOF is hit. Return ``''`` if EOF is
73   hit.  Block if no data is immediately available.
74
75
n76-.. method:: XXX Class.read_very_eager()
n87+.. method:: Telnet.read_very_eager()
77
78   Read everything that can be without blocking in I/O (eager).
79
80   Raise :exc:`EOFError` if connection closed and no cooked data available.  Return
81   ``''`` if no cooked data available otherwise. Do not block unless in the midst
82   of an IAC sequence.
83
84
n85-.. method:: XXX Class.read_eager()
n96+.. method:: Telnet.read_eager()
86
87   Read readily available data.
88
89   Raise :exc:`EOFError` if connection closed and no cooked data available.  Return
90   ``''`` if no cooked data available otherwise. Do not block unless in the midst
91   of an IAC sequence.
92
93
n94-.. method:: XXX Class.read_lazy()
n105+.. method:: Telnet.read_lazy()
95
96   Process and return data already in the queues (lazy).
97
98   Raise :exc:`EOFError` if connection closed and no data available. Return ``''``
99   if no cooked data available otherwise.  Do not block unless in the midst of an
100   IAC sequence.
101
102
n103-.. method:: XXX Class.read_very_lazy()
n114+.. method:: Telnet.read_very_lazy()
104
105   Return any data available in the cooked queue (very lazy).
106
107   Raise :exc:`EOFError` if connection closed and no data available. Return ``''``
108   if no cooked data available otherwise.  This method never blocks.
109
110
n111-.. method:: XXX Class.read_sb_data()
n122+.. method:: Telnet.read_sb_data()
112
113   Return the data collected between a SB/SE pair (suboption begin/end). The
114   callback should access these data when it was invoked with a ``SE`` command.
115   This method never blocks.
116
117   .. versionadded:: 2.3
118
119
n120-.. method:: XXX Class.open(host[, port])
n131+.. method:: Telnet.open(host[, port[, timeout]])
121
122   Connect to a host. The optional second argument is the port number, which
n123-   defaults to the standard Telnet port (23).
n134+   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).
124
125   Do not try to reopen an already connected instance.
126
n140+   .. versionchanged:: 2.6
141+      *timeout* was added.
127
n143+ 
128-.. method:: XXX Class.msg(msg[, *args])
144+.. method:: Telnet.msg(msg[, *args])
129
130   Print a debug message when the debug level is ``>`` 0. If extra arguments are
131   present, they are substituted in the message using the standard string
132   formatting operator.
133
134
n135-.. method:: XXX Class.set_debuglevel(debuglevel)
n151+.. method:: Telnet.set_debuglevel(debuglevel)
136
137   Set the debug level.  The higher the value of *debuglevel*, the more debug
138   output you get (on ``sys.stdout``).
139
140
n141-.. method:: XXX Class.close()
n157+.. method:: Telnet.close()
142
143   Close the connection.
144
145
n146-.. method:: XXX Class.get_socket()
n162+.. method:: Telnet.get_socket()
147
148   Return the socket object used internally.
149
150
n151-.. method:: XXX Class.fileno()
n167+.. method:: Telnet.fileno()
152
153   Return the file descriptor of the socket object used internally.
154
155
n156-.. method:: XXX Class.write(buffer)
n172+.. method:: Telnet.write(buffer)
157
158   Write a string to the socket, doubling any IAC characters. This can block if the
159   connection is blocked.  May raise :exc:`socket.error` if the connection is
160   closed.
161
162
n163-.. method:: XXX Class.interact()
n179+.. method:: Telnet.interact()
164
165   Interaction function, emulates a very dumb Telnet client.
166
167
n168-.. method:: XXX Class.mt_interact()
n184+.. method:: Telnet.mt_interact()
169
170   Multithreaded version of :meth:`interact`.
171
172
n173-.. method:: XXX Class.expect(list[, timeout])
n189+.. method:: Telnet.expect(list[, timeout])
174
175   Read until one from a list of a regular expressions matches.
176
177   The first argument is a list of regular expressions, either compiled
178   (:class:`re.RegexObject` instances) or uncompiled (strings). The optional second
179   argument is a timeout, in seconds; the default is to block indefinitely.
180
181   Return a tuple of three items: the index in the list of the first regular
186   when nothing matches, return ``(-1, None, text)`` where *text* is the text
187   received so far (may be the empty string if a timeout happened).
188
189   If a regular expression ends with a greedy match (such as ``.*``) or if more
190   than one expression can match the same input, the results are indeterministic,
191   and may depend on the I/O timing.
192
193
t194-.. method:: XXX Class.set_option_negotiation_callback(callback)
t210+.. method:: Telnet.set_option_negotiation_callback(callback)
195
196   Each time a telnet option is read on the input flow, this *callback* (if set) is
197   called with the following parameters : callback(telnet socket, command
198   (DO/DONT/WILL/WONT), option).  No other action is done afterwards by telnetlib.
199
200
201.. _telnet-example:
202
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op