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