diff options
Diffstat (limited to 'Doc/lib/libtelnetlib.tex')
-rw-r--r-- | Doc/lib/libtelnetlib.tex | 223 |
1 files changed, 0 insertions, 223 deletions
diff --git a/Doc/lib/libtelnetlib.tex b/Doc/lib/libtelnetlib.tex deleted file mode 100644 index 5b32a5f..0000000 --- a/Doc/lib/libtelnetlib.tex +++ /dev/null @@ -1,223 +0,0 @@ -\section{\module{telnetlib} --- - Telnet client} - -\declaremodule{standard}{telnetlib} -\modulesynopsis{Telnet client class.} -\sectionauthor{Skip Montanaro}{skip@mojam.com} - -\index{protocol!Telnet} - -The \module{telnetlib} module provides a \class{Telnet} class that -implements the Telnet protocol. See \rfc{854} for details about the -protocol. In addition, it provides symbolic constants for the protocol -characters (see below), and for the telnet options. The -symbolic names of the telnet options follow the definitions in -\code{arpa/telnet.h}, with the leading \code{TELOPT_} removed. For -symbolic names of options which are traditionally not included in -\code{arpa/telnet.h}, see the module source itself. - -The symbolic constants for the telnet commands are: IAC, DONT, DO, -WONT, WILL, SE (Subnegotiation End), NOP (No Operation), DM (Data -Mark), BRK (Break), IP (Interrupt process), AO (Abort output), AYT -(Are You There), EC (Erase Character), EL (Erase Line), GA (Go Ahead), -SB (Subnegotiation Begin). - - -\begin{classdesc}{Telnet}{\optional{host\optional{, port\optional{, timeout}}}} -\class{Telnet} represents a connection to a Telnet server. The -instance is initially not connected by default; the \method{open()} -method must be used to establish a connection. Alternatively, the -host name and optional port number can be passed to the constructor, -to, in which case the connection to the server will be established -before the constructor returns. -The optional \var{timeout} parameter specifies a timeout in seconds for the -connection attempt (if not specified, or passed as None, the global default -timeout setting will be used). - -Do not reopen an already connected instance. - -This class has many \method{read_*()} methods. Note that some of them -raise \exception{EOFError} when the end of the connection is read, -because they can return an empty string for other reasons. See the -individual descriptions below. -\versionchanged[\var{timeout} was added]{2.6} -\end{classdesc} - - -\begin{seealso} - \seerfc{854}{Telnet Protocol Specification}{ - Definition of the Telnet protocol.} -\end{seealso} - - - -\subsection{Telnet Objects \label{telnet-objects}} - -\class{Telnet} instances have the following methods: - - -\begin{methoddesc}[Telnet]{read_until}{expected\optional{, timeout}} -Read until a given string, \var{expected}, is encountered or until -\var{timeout} seconds have passed. - -When no match is found, return whatever is available instead, -possibly the empty string. Raise \exception{EOFError} if the connection -is closed and no cooked data is available. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{read_all}{} -Read all data until \EOF; block until connection closed. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{read_some}{} -Read at least one byte of cooked data unless \EOF{} is hit. -Return \code{''} if \EOF{} is hit. Block if no data is immediately -available. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{read_very_eager}{} -Read everything that can be without blocking in I/O (eager). - -Raise \exception{EOFError} if connection closed and no cooked data -available. Return \code{''} if no cooked data available otherwise. -Do not block unless in the midst of an IAC sequence. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{read_eager}{} -Read readily available data. - -Raise \exception{EOFError} if connection closed and no cooked data -available. Return \code{''} if no cooked data available otherwise. -Do not block unless in the midst of an IAC sequence. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{read_lazy}{} -Process and return data already in the queues (lazy). - -Raise \exception{EOFError} if connection closed and no data available. -Return \code{''} if no cooked data available otherwise. Do not block -unless in the midst of an IAC sequence. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{read_very_lazy}{} -Return any data available in the cooked queue (very lazy). - -Raise \exception{EOFError} if connection closed and no data available. -Return \code{''} if no cooked data available otherwise. This method -never blocks. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{read_sb_data}{} -Return the data collected between a SB/SE pair (suboption begin/end). -The callback should access these data when it was invoked with a -\code{SE} command. This method never blocks. - -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[Telnet]{open}{host\optional{, port\optional{, timeout}}} -Connect to a host. -The optional second argument is the port number, which -defaults to the standard Telnet port (23). -The optional \var{timeout} parameter specifies a timeout in seconds for the -connection attempt (if not specified, or passed as None, the global default -timeout setting will be used). - -Do not try to reopen an already connected instance. -\versionchanged[\var{timeout} was added]{2.6} -\end{methoddesc} - -\begin{methoddesc}[Telnet]{msg}{msg\optional{, *args}} -Print a debug message when the debug level is \code{>} 0. -If extra arguments are present, they are substituted in the -message using the standard string formatting operator. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{set_debuglevel}{debuglevel} -Set the debug level. The higher the value of \var{debuglevel}, the -more debug output you get (on \code{sys.stdout}). -\end{methoddesc} - -\begin{methoddesc}[Telnet]{close}{} -Close the connection. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{get_socket}{} -Return the socket object used internally. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{fileno}{} -Return the file descriptor of the socket object used internally. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{write}{buffer} -Write a string to the socket, doubling any IAC characters. -This can block if the connection is blocked. May raise -\exception{socket.error} if the connection is closed. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{interact}{} -Interaction function, emulates a very dumb Telnet client. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{mt_interact}{} -Multithreaded version of \method{interact()}. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{expect}{list\optional{, timeout}} -Read until one from a list of a regular expressions matches. - -The first argument is a list of regular expressions, either -compiled (\class{re.RegexObject} instances) or uncompiled (strings). -The optional second argument is a timeout, in seconds; the default -is to block indefinitely. - -Return a tuple of three items: the index in the list of the -first regular expression that matches; the match object -returned; and the text read up till and including the match. - -If end of file is found and no text was read, raise -\exception{EOFError}. Otherwise, when nothing matches, return -\code{(-1, None, \var{text})} where \var{text} is the text received so -far (may be the empty string if a timeout happened). - -If a regular expression ends with a greedy match (such as \regexp{.*}) -or if more than one expression can match the same input, the -results are indeterministic, and may depend on the I/O timing. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{set_option_negotiation_callback}{callback} -Each time a telnet option is read on the input flow, this -\var{callback} (if set) is called with the following parameters : -callback(telnet socket, command (DO/DONT/WILL/WONT), option). No other -action is done afterwards by telnetlib. -\end{methoddesc} - - -\subsection{Telnet Example \label{telnet-example}} -\sectionauthor{Peter Funk}{pf@artcom-gmbh.de} - -A simple example illustrating typical use: - -\begin{verbatim} -import getpass -import sys -import telnetlib - -HOST = "localhost" -user = raw_input("Enter your remote account: ") -password = getpass.getpass() - -tn = telnetlib.Telnet(HOST) - -tn.read_until("login: ") -tn.write(user + "\n") -if password: - tn.read_until("Password: ") - tn.write(password + "\n") - -tn.write("ls\n") -tn.write("exit\n") - -print tn.read_all() -\end{verbatim} |