cpython/Doc/lib/libtelnetlib.tex

155 lines
5.1 KiB
TeX

% LaTeX'ized from the comments in the module by Skip Montanaro
% <skip@mojam.com>.
\section{\module{telnetlib} ---
Telnet client}
\declaremodule{standard}{telnetlib}
\modulesynopsis{Telnet client class.}
The \module{telnetlib} module provides a \class{Telnet} class that
implements the Telnet protocol. See \rfc{854} for details about the
protocol.
\begin{classdesc}{Telnet}{\optional{host\optional{, port=0}}}
\class{Telnet} represents a connection to a telnet server. The
instance is initially not connected; 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, too.
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 doc strings.
\end{classdesc}
\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 is encountered or until timeout.
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's possible 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.
Don't 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.
Don't block unless in the midst of an IAC sequence.
\end{methoddesc}
\begin{methoddesc}[Telnet]{read_lazy}{}
Process and return data that's already in the queues (lazy).
Raise \exception{EOFError} if connection closed and no data available.
Return \code{''} if no cooked data available otherwise. Don't 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. Don't block.
\end{methoddesc}
\begin{methoddesc}[Telnet]{open}{host\optional{, port=0}}
Connect to a host.
The optional second argument is the port number, which
defaults to the standard telnet port (23).
Don't try to reopen an already connected instance.
\end{methoddesc}
\begin{methoddesc}[Telnet]{msg}{msg\optional{, *args}}
Print a debug message, when the debug level is > 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 it is, the more debug output you get (on 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 fileno() of the socket object used internally.
\end{methoddesc}
\begin{methoddesc}[Telnet]{write}{buffer}
Write a string to the socket, doubling any IAC characters.
Can block if the connection is blocked. May raise
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, timeout=None}
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; default
is no timeout.
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 (e.g. \regexp{.*})
or if more than one expression can match the same input, the
results are undeterministic, and may depend on the I/O timing.
\end{methoddesc}