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