1 :mod:`telnetlib` --- Telnet client 2 ================================== 3 4 .. module:: telnetlib 5 :synopsis: Telnet client class. 6 .. sectionauthor:: Skip Montanaro <skip (a] 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 (a] 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 246
