/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
 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
 16in ``arpa/telnet.h``, with the leading ``TELOPT_`` removed. For symbolic names
 17of options which are traditionally not included in ``arpa/telnet.h``, see the
 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
 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
 60Telnet 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
219Telnet Example
220--------------
221
222.. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>
223
224
225A 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