diff -r ffa851df0825 -r 2fb8b9db1c86 symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/telnetlib.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/telnetlib.rst Fri Jul 31 15:01:17 2009 +0100 @@ -0,0 +1,247 @@ + +:mod:`telnetlib` --- Telnet client +================================== + +.. module:: telnetlib + :synopsis: Telnet client class. +.. sectionauthor:: Skip Montanaro + + +.. index:: single: protocol; Telnet + +The :mod:`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 ``arpa/telnet.h``, with the leading ``TELOPT_`` removed. For symbolic names +of options which are traditionally not included in ``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). + + +.. class:: Telnet([host[, port[, timeout]]]) + + :class:`Telnet` represents a connection to a Telnet server. The instance is + initially not connected by default; the :meth:`open` method must be used to + establish a connection. Alternatively, the host name and optional port + and timeout can be passed to the constructor, in which case the connection to + the server will be established before the constructor returns. The optional + *timeout* parameter specifies a timeout in seconds for the connection attempt (if + not specified, the global default timeout setting will be used). + + 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 + *timeout* parameter specifies a timeout in seconds for blocking operations + like 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 :meth:`read_\*` methods. Note that some of them raise + :exc:`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:: 2.6 + *timeout* was added. + + +.. seealso:: + + :rfc:`854` - Telnet Protocol Specification + Definition of the Telnet protocol. + + +.. _telnet-objects: + +Telnet Objects +-------------- + +:class:`Telnet` instances have the following methods: + + +.. method:: Telnet.read_until(expected[, timeout]) + + Read until a given string, *expected*, is encountered or until *timeout* seconds + have passed. + + When no match is found, return whatever is available instead, possibly the empty + string. Raise :exc:`EOFError` if the connection is closed and no cooked data is + available. + + +.. method:: Telnet.read_all() + + Read all data until EOF; block until connection closed. + + +.. method:: Telnet.read_some() + + Read at least one byte of cooked data unless EOF is hit. Return ``''`` if EOF is + hit. Block if no data is immediately available. + + +.. method:: Telnet.read_very_eager() + + Read everything that can be without blocking in I/O (eager). + + Raise :exc:`EOFError` if connection closed and no cooked data available. Return + ``''`` if no cooked data available otherwise. Do not block unless in the midst + of an IAC sequence. + + +.. method:: Telnet.read_eager() + + Read readily available data. + + Raise :exc:`EOFError` if connection closed and no cooked data available. Return + ``''`` if no cooked data available otherwise. Do not block unless in the midst + of an IAC sequence. + + +.. method:: Telnet.read_lazy() + + Process and return data already in the queues (lazy). + + Raise :exc:`EOFError` if connection closed and no data available. Return ``''`` + if no cooked data available otherwise. Do not block unless in the midst of an + IAC sequence. + + +.. method:: Telnet.read_very_lazy() + + Return any data available in the cooked queue (very lazy). + + Raise :exc:`EOFError` if connection closed and no data available. Return ``''`` + if no cooked data available otherwise. This method never blocks. + + +.. method:: 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 ``SE`` command. + This method never blocks. + + .. versionadded:: 2.3 + + +.. method:: Telnet.open(host[, port[, timeout]]) + + Connect to a host. The optional second argument is the port number, which + defaults to the standard Telnet port (23). The optional *timeout* parameter + specifies a timeout in seconds for blocking operations like the connection + attempt (if not specified, the global default timeout setting will be used). + + Do not try to reopen an already connected instance. + + .. versionchanged:: 2.6 + *timeout* was added. + + +.. method:: Telnet.msg(msg[, *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. + + +.. method:: Telnet.set_debuglevel(debuglevel) + + Set the debug level. The higher the value of *debuglevel*, the more debug + output you get (on ``sys.stdout``). + + +.. method:: Telnet.close() + + Close the connection. + + +.. method:: Telnet.get_socket() + + Return the socket object used internally. + + +.. method:: Telnet.fileno() + + Return the file descriptor of the socket object used internally. + + +.. method:: Telnet.write(buffer) + + Write a string to the socket, doubling any IAC characters. This can block if the + connection is blocked. May raise :exc:`socket.error` if the connection is + closed. + + +.. method:: Telnet.interact() + + Interaction function, emulates a very dumb Telnet client. + + +.. method:: Telnet.mt_interact() + + Multithreaded version of :meth:`interact`. + + +.. method:: Telnet.expect(list[, 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 :exc:`EOFError`. Otherwise, + when nothing matches, return ``(-1, None, text)`` where *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 ``.*``) or if more + than one expression can match the same input, the results are indeterministic, + and may depend on the I/O timing. + + +.. method:: Telnet.set_option_negotiation_callback(callback) + + Each time a telnet option is read on the input flow, this *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. + + +.. _telnet-example: + +Telnet Example +-------------- + +.. sectionauthor:: Peter Funk + + +A simple example illustrating typical use:: + + 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() +