Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 1 | \section{\module{telnetlib} --- |
| 2 | Telnet client} |
| 3 | |
| 4 | \declaremodule{standard}{telnetlib} |
| 5 | \modulesynopsis{Telnet client class.} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 6 | \sectionauthor{Skip Montanaro}{skip@mojam.com} |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 7 | |
| 8 | The \module{telnetlib} module provides a \class{Telnet} class that |
| 9 | implements the Telnet protocol. See \rfc{854} for details about the |
| 10 | protocol. |
| 11 | |
| 12 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 13 | \begin{classdesc}{Telnet}{\optional{host\optional{, port}}} |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 14 | \class{Telnet} represents a connection to a telnet server. The |
| 15 | instance is initially not connected; the \method{open()} method must |
| 16 | be used to establish a connection. Alternatively, the host name and |
| 17 | optional port number can be passed to the constructor, too. |
| 18 | |
| 19 | Do not reopen an already connected instance. |
| 20 | |
| 21 | This class has many \method{read_*()} methods. Note that some of them |
| 22 | raise \exception{EOFError} when the end of the connection is read, |
| 23 | because they can return an empty string for other reasons. See the |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 24 | individual descriptions below. |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 25 | \end{classdesc} |
| 26 | |
| 27 | |
Fred Drake | ac308d0 | 2000-04-26 18:20:04 +0000 | [diff] [blame^] | 28 | \begin{seealso} |
| 29 | \seerfc{854}{Telnet Protocol Specification}{ |
| 30 | Definition of the Telnet protocol.} |
| 31 | \end{seealso} |
| 32 | |
| 33 | |
| 34 | |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 35 | \subsection{Telnet Objects \label{telnet-objects}} |
| 36 | |
| 37 | \class{Telnet} instances have the following methods: |
| 38 | |
| 39 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 40 | \begin{methoddesc}{read_until}{expected\optional{, timeout}} |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 41 | Read until a given string is encountered or until timeout. |
| 42 | |
| 43 | When no match is found, return whatever is available instead, |
| 44 | possibly the empty string. Raise \exception{EOFError} if the connection |
| 45 | is closed and no cooked data is available. |
| 46 | \end{methoddesc} |
| 47 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 48 | \begin{methoddesc}{read_all}{} |
| 49 | Read all data until \EOF{}; block until connection closed. |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 50 | \end{methoddesc} |
| 51 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 52 | \begin{methoddesc}{read_some}{} |
| 53 | Read at least one byte of cooked data unless \EOF{} is hit. |
| 54 | Return \code{''} if \EOF{} is hit. Block if no data is immediately |
| 55 | available. |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 56 | \end{methoddesc} |
| 57 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 58 | \begin{methoddesc}{read_very_eager}{} |
| 59 | Read everything that can be without blocking in I/O (eager). |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 60 | |
| 61 | Raise \exception{EOFError} if connection closed and no cooked data |
| 62 | available. Return \code{''} if no cooked data available otherwise. |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 63 | Do not block unless in the midst of an IAC sequence. |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 64 | \end{methoddesc} |
| 65 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 66 | \begin{methoddesc}{read_eager}{} |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 67 | Read readily available data. |
| 68 | |
| 69 | Raise \exception{EOFError} if connection closed and no cooked data |
| 70 | available. Return \code{''} if no cooked data available otherwise. |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 71 | Do not block unless in the midst of an IAC sequence. |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 72 | \end{methoddesc} |
| 73 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 74 | \begin{methoddesc}{read_lazy}{} |
| 75 | Process and return data already in the queues (lazy). |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 76 | |
| 77 | Raise \exception{EOFError} if connection closed and no data available. |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 78 | Return \code{''} if no cooked data available otherwise. Do not block |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 79 | unless in the midst of an IAC sequence. |
| 80 | \end{methoddesc} |
| 81 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 82 | \begin{methoddesc}{read_very_lazy}{} |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 83 | Return any data available in the cooked queue (very lazy). |
| 84 | |
| 85 | Raise \exception{EOFError} if connection closed and no data available. |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 86 | Return \code{''} if no cooked data available otherwise. This method |
| 87 | never blocks. |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 88 | \end{methoddesc} |
| 89 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 90 | \begin{methoddesc}{open}{host\optional{, port}} |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 91 | Connect to a host. |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 92 | The optional second argument is the port number, which |
| 93 | defaults to the standard telnet port (23). |
| 94 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 95 | Do not try to reopen an already connected instance. |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 96 | \end{methoddesc} |
| 97 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 98 | \begin{methoddesc}{msg}{msg\optional{, *args}} |
| 99 | Print a debug message when the debug level is \code{>} 0. |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 100 | If extra arguments are present, they are substituted in the |
| 101 | message using the standard string formatting operator. |
| 102 | \end{methoddesc} |
| 103 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 104 | \begin{methoddesc}{set_debuglevel}{debuglevel} |
| 105 | Set the debug level. The higher the value of \var{debuglevel}, the |
| 106 | more debug output you get (on \code{sys.stdout}). |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 107 | \end{methoddesc} |
| 108 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 109 | \begin{methoddesc}{close}{} |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 110 | Close the connection. |
| 111 | \end{methoddesc} |
| 112 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 113 | \begin{methoddesc}{get_socket}{} |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 114 | Return the socket object used internally. |
| 115 | \end{methoddesc} |
| 116 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 117 | \begin{methoddesc}{fileno}{} |
| 118 | Return the file descriptor of the socket object used internally. |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 119 | \end{methoddesc} |
| 120 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 121 | \begin{methoddesc}{write}{buffer} |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 122 | Write a string to the socket, doubling any IAC characters. |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 123 | This can block if the connection is blocked. May raise |
| 124 | \exception{socket.error} if the connection is closed. |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 125 | \end{methoddesc} |
| 126 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 127 | \begin{methoddesc}{interact}{} |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 128 | Interaction function, emulates a very dumb telnet client. |
| 129 | \end{methoddesc} |
| 130 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 131 | \begin{methoddesc}{mt_interact}{} |
| 132 | Multithreaded version of \method{interact()}. |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 133 | \end{methoddesc} |
| 134 | |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 135 | \begin{methoddesc}{expect}{list\optional{, timeout}} |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 136 | Read until one from a list of a regular expressions matches. |
| 137 | |
| 138 | The first argument is a list of regular expressions, either |
| 139 | compiled (\class{re.RegexObject} instances) or uncompiled (strings). |
Fred Drake | b7168c3 | 1999-04-22 17:53:37 +0000 | [diff] [blame] | 140 | The optional second argument is a timeout, in seconds; the default |
| 141 | is to block indefinately. |
Fred Drake | 658cef0 | 1999-03-15 15:44:18 +0000 | [diff] [blame] | 142 | |
| 143 | Return a tuple of three items: the index in the list of the |
| 144 | first regular expression that matches; the match object |
| 145 | returned; and the text read up till and including the match. |
| 146 | |
| 147 | If end of file is found and no text was read, raise |
| 148 | \exception{EOFError}. Otherwise, when nothing matches, return |
| 149 | \code{(-1, None, \var{text})} where \var{text} is the text received so |
| 150 | far (may be the empty string if a timeout happened). |
| 151 | |
| 152 | If a regular expression ends with a greedy match (e.g. \regexp{.*}) |
| 153 | or if more than one expression can match the same input, the |
| 154 | results are undeterministic, and may depend on the I/O timing. |
| 155 | \end{methoddesc} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 156 | |
| 157 | |
| 158 | \subsection{Telnet Example \label{telnet-example}} |
| 159 | \sectionauthor{Peter Funk}{pf@artcom-gmbh.de} |
| 160 | |
| 161 | A simple example illustrating typical use: |
| 162 | |
| 163 | \begin{verbatim} |
| 164 | import getpass |
| 165 | import sys |
| 166 | import telnetlib |
| 167 | |
| 168 | HOST = "localhost" |
| 169 | user = raw_input("Enter your remote account: ") |
| 170 | password = getpass.getpass() |
| 171 | |
| 172 | tn = telnetlib.Telnet(HOST) |
| 173 | |
| 174 | tn.read_until("login: ") |
| 175 | tn.write(user + "\n") |
| 176 | if password: |
| 177 | tn.read_until("Password: ") |
| 178 | tn.write(password + "\n") |
| 179 | |
| 180 | tn.write("ls\n") |
| 181 | tn.write("exit\n") |
| 182 | |
| 183 | print tn.read_all() |
| 184 | \end{verbatim} |