← Back to branch summary

~dkuhlman/python-training-materials/Materials

« back to all changes in this revision

Viewing changes to python-2.7.10-docs-html/_sources/library/telnetlib.txt

  • Committer: Dave Kuhlman
  • Date: 2016-02-11 21:17:09 UTC
  • Revision ID: dkuhlman@davekuhlman.org-20160211211709-03yaen3cjempbi2m
Updated Python 2.7 docs; added Python 3.5 docs

Show diffs side-by-side

added added

removed removed

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