Doc/lib/libtelnetlib.tex

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