← Back to branch summary

~dkuhlman/python-training-materials/Materials

« back to all changes in this revision

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

  • Committer: Dave Kuhlman
  • Date: 2017-04-15 16:24:56 UTC
  • Revision ID: dkuhlman@davekuhlman.org-20170415162456-iav9vozzg4iwqwv3
Updated docs

Show diffs side-by-side

added added

removed removed

Lines of Context:
python-3.5.1-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=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:`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
 
 
47
 
.. seealso::
48
 
 
49
 
   :rfc:`854` - Telnet Protocol Specification
50
 
      Definition of the Telnet protocol.
51
 
 
52
 
 
53
 
.. _telnet-objects:
54
 
 
55
 
Telnet Objects
56
 
--------------
57
 
 
58
 
:class:`Telnet` instances have the following methods:
59
 
 
60
 
 
61
 
.. method:: Telnet.read_until(expected, timeout=None)
62
 
 
63
 
   Read until a given byte string, *expected*, is encountered or until *timeout*
64
 
   seconds have passed.
65
 
 
66
 
   When no match is found, return whatever is available instead, possibly empty
67
 
   bytes.  Raise :exc:`EOFError` if the connection is closed and no cooked data
68
 
   is available.
69
 
 
70
 
 
71
 
.. method:: Telnet.read_all()
72
 
 
73
 
   Read all data until EOF as bytes; block until connection closed.
74
 
 
75
 
 
76
 
.. method:: Telnet.read_some()
77
 
 
78
 
   Read at least one byte of cooked data unless EOF is hit. Return ``b''`` if
79
 
   EOF is hit.  Block if no data is immediately available.
80
 
 
81
 
 
82
 
.. method:: Telnet.read_very_eager()
83
 
 
84
 
   Read everything that can be without blocking in I/O (eager).
85
 
 
86
 
   Raise :exc:`EOFError` if connection closed and no cooked data available.
87
 
   Return ``b''`` if no cooked data available otherwise. Do not block unless in
88
 
   the midst of an IAC sequence.
89
 
 
90
 
 
91
 
.. method:: Telnet.read_eager()
92
 
 
93
 
   Read readily available data.
94
 
 
95
 
   Raise :exc:`EOFError` if connection closed and no cooked data available.
96
 
   Return ``b''`` if no cooked data available otherwise. Do not block unless in
97
 
   the midst of an IAC sequence.
98
 
 
99
 
 
100
 
.. method:: Telnet.read_lazy()
101
 
 
102
 
   Process and return data already in the queues (lazy).
103
 
 
104
 
   Raise :exc:`EOFError` if connection closed and no data available. Return
105
 
   ``b''`` if no cooked data available otherwise.  Do not block unless in the
106
 
   midst of an IAC sequence.
107
 
 
108
 
 
109
 
.. method:: Telnet.read_very_lazy()
110
 
 
111
 
   Return any data available in the cooked queue (very lazy).
112
 
 
113
 
   Raise :exc:`EOFError` if connection closed and no data available. Return
114
 
   ``b''`` if no cooked data available otherwise.  This method never blocks.
115
 
 
116
 
 
117
 
.. method:: Telnet.read_sb_data()
118
 
 
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.
122
 
 
123
 
 
124
 
.. method:: Telnet.open(host, port=0[, timeout])
125
 
 
126
 
   Connect to a host. The optional second argument is the port number, which
127
 
   defaults to the standard Telnet port (23). The optional *timeout* parameter
128
 
   specifies a timeout in seconds for blocking operations like the connection
129
 
   attempt (if not specified, the global default timeout setting will be used).
130
 
 
131
 
   Do not try to reopen an already connected instance.
132
 
 
133
 
 
134
 
.. method:: Telnet.msg(msg, *args)
135
 
 
136
 
   Print a debug message when the debug level is ``>`` 0. If extra arguments are
137
 
   present, they are substituted in the message using the standard string
138
 
   formatting operator.
139
 
 
140
 
 
141
 
.. method:: Telnet.set_debuglevel(debuglevel)
142
 
 
143
 
   Set the debug level.  The higher the value of *debuglevel*, the more debug
144
 
   output you get (on ``sys.stdout``).
145
 
 
146
 
 
147
 
.. method:: Telnet.close()
148
 
 
149
 
   Close the connection.
150
 
 
151
 
 
152
 
.. method:: Telnet.get_socket()
153
 
 
154
 
   Return the socket object used internally.
155
 
 
156
 
 
157
 
.. method:: Telnet.fileno()
158
 
 
159
 
   Return the file descriptor of the socket object used internally.
160
 
 
161
 
 
162
 
.. method:: Telnet.write(buffer)
163
 
 
164
 
   Write a byte string to the socket, doubling any IAC characters. This can
165
 
   block if the connection is blocked.  May raise :exc:`OSError` if the
166
 
   connection is closed.
167
 
 
168
 
   .. versionchanged:: 3.3
169
 
      This method used to raise :exc:`socket.error`, which is now an alias
170
 
      of :exc:`OSError`.
171
 
 
172
 
 
173
 
.. method:: Telnet.interact()
174
 
 
175
 
   Interaction function, emulates a very dumb Telnet client.
176
 
 
177
 
 
178
 
.. method:: Telnet.mt_interact()
179
 
 
180
 
   Multithreaded version of :meth:`interact`.
181
 
 
182
 
 
183
 
.. method:: Telnet.expect(list, timeout=None)
184
 
 
185
 
   Read until one from a list of a regular expressions matches.
186
 
 
187
 
   The first argument is a list of regular expressions, either compiled
188
 
   (:ref:`regex objects <re-objects>`) or uncompiled (byte strings). The
189
 
   optional second argument is a timeout, in seconds; the default is to block
190
 
   indefinitely.
191
 
 
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 bytes read up
194
 
   till and including the match.
195
 
 
196
 
   If end of file is found and no bytes were read, raise :exc:`EOFError`.
197
 
   Otherwise, when nothing matches, return ``(-1, None, data)`` where *data* is
198
 
   the bytes received so far (may be empty bytes if a timeout happened).
199
 
 
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.
203
 
 
204
 
 
205
 
.. method:: Telnet.set_option_negotiation_callback(callback)
206
 
 
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.
210
 
 
211
 
 
212
 
.. _telnet-example:
213
 
 
214
 
Telnet Example
215
 
--------------
216
 
 
217
 
.. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>
218
 
 
219
 
 
220
 
A simple example illustrating typical use::
221
 
 
222
 
   import getpass
223
 
   import telnetlib
224
 
 
225
 
   HOST = "localhost"
226
 
   user = input("Enter your remote account: ")
227
 
   password = getpass.getpass()
228
 
 
229
 
   tn = telnetlib.Telnet(HOST)
230
 
 
231
 
   tn.read_until(b"login: ")
232
 
   tn.write(user.encode('ascii') + b"\n")
233
 
   if password:
234
 
       tn.read_until(b"Password: ")
235
 
       tn.write(password.encode('ascii') + b"\n")
236
 
 
237
 
   tn.write(b"ls\n")
238
 
   tn.write(b"exit\n")
239
 
 
240
 
   print(tn.read_all().decode('ascii'))
241