|
| def | __getattr__ (self, name) |
| |
| def | __init__ (self, timeout='3 seconds', newline='CRLF', prompt=None, prompt_is_regexp=False, encoding='UTF-8', encoding_errors='ignore', default_log_level='INFO', window_size=None, environ_user=None, terminal_emulation=False, terminal_type=None, telnetlib_log_level='TRACE', connection_timeout=None) |
| | Telnet library can be imported with optional configuration parameters. More...
|
| |
| def | close_all_connections (self) |
| | Closes all open connections and empties the connection cache. More...
|
| |
| def | get_keyword_names (self) |
| |
| def | open_connection (self, host, alias=None, port=23, timeout=None, newline=None, prompt=None, prompt_is_regexp=False, encoding=None, encoding_errors=None, default_log_level=None, window_size=None, environ_user=None, terminal_emulation=None, terminal_type=None, telnetlib_log_level=None, connection_timeout=None) |
| | Opens a new Telnet connection to the given host and port. More...
|
| |
| def | switch_connection (self, index_or_alias) |
| | Switches between active connections using an index or an alias. More...
|
| |
A library providing communication over Telnet connections.
``Telnet`` is Robot Framework's standard library that makes it possible to
connect to Telnet servers and execute commands on the opened connections.
== Table of contents ==
%TOC%
= Connections =
The first step of using ``Telnet`` is opening a connection with `Open
Connection` keyword. Typically the next step is logging in with `Login`
keyword, and in the end the opened connection can be closed with `Close
Connection`.
It is possible to open multiple connections and switch the active one
using `Switch Connection`. `Close All Connections` can be used to close
all the connections, which is especially useful in suite teardowns to
guarantee that all connections are always closed.
= Writing and reading =
After opening a connection and possibly logging in, commands can be
executed or text written to the connection for other reasons using `Write`
and `Write Bare` keywords. The main difference between these two is that
the former adds a [#Configuration|configurable newline] after the text
automatically.
After writing something to the connection, the resulting output can be
read using `Read`, `Read Until`, `Read Until Regexp`, and `Read Until
Prompt` keywords. Which one to use depends on the context, but the latest
one is often the most convenient.
As a convenience when running a command, it is possible to use `Execute
Command` that simply uses `Write` and `Read Until Prompt` internally.
`Write Until Expected Output` is useful if you need to wait until writing
something produces a desired output.
Written and read text is automatically encoded/decoded using a
[#Configuration|configured encoding].
The ANSI escape codes, like cursor movement and color codes, are
normally returned as part of the read operation. If an escape code occurs
in middle of a search pattern it may also prevent finding the searched
string. `Terminal emulation` can be used to process these
escape codes as they would be if a real terminal would be in use.
= Configuration =
Many aspects related the connections can be easily configured either
globally or per connection basis. Global configuration is done when
[#Importing|library is imported], and these values can be overridden per
connection by `Open Connection` or with setting specific keywords
`Set Timeout`, `Set Newline`, `Set Prompt`, `Set Encoding`,
`Set Default Log Level` and `Set Telnetlib Log Level`.
Values of ``environ_user``, ``window_size``, ``terminal_emulation``, and
``terminal_type`` can not be changed after opening the connection.
== Timeout ==
Timeout defines how long is the maximum time to wait when reading
output. It is used internally by `Read Until`, `Read Until Regexp`,
`Read Until Prompt`, and `Login` keywords. The default value is 3 seconds.
== Connection Timeout ==
Connection Timeout defines how long is the maximum time to wait when
opening the telnet connection. It is used internally by `Open Connection`.
The default value is the system global default timeout.
== Newline ==
Newline defines which line separator `Write` keyword should use. The
default value is ``CRLF`` that is typically used by Telnet connections.
Newline can be given either in escaped format using ``\\n`` and ``\\r`` or
with special ``LF`` and ``CR`` syntax.
Examples:
| `Set Newline` | \\n |
| `Set Newline` | CRLF |
== Prompt ==
Often the easiest way to read the output of a command is reading all
the output until the next prompt with `Read Until Prompt`. It also makes
it easier, and faster, to verify did `Login` succeed.
Prompt can be specified either as a normal string or a regular expression.
The latter is especially useful if the prompt changes as a result of
the executed commands. Prompt can be set to be a regular expression
by giving ``prompt_is_regexp`` argument a true value (see `Boolean
arguments`).
Examples:
| `Open Connection` | lolcathost | prompt=$ |
| `Set Prompt` | (> |# ) | prompt_is_regexp=true |
== Encoding ==
To ease handling text containing non-ASCII characters, all written text is
encoded and read text decoded by default. The default encoding is UTF-8
that works also with ASCII. Encoding can be disabled by using a special
encoding value ``NONE``. This is mainly useful if you need to get the bytes
received from the connection as-is.
Notice that when writing to the connection, only Unicode strings are
encoded using the defined encoding. Byte strings are expected to be already
encoded correctly. Notice also that normal text in data is passed to
the library as Unicode and you need to use variables to use bytes.
It is also possible to configure the error handler to use if encoding or
decoding characters fails. Accepted values are the same that encode/decode
functions in Python strings accept. In practice the following values are
the most useful:
- ``ignore``: ignore characters that cannot be encoded (default)
- ``strict``: fail if characters cannot be encoded
- ``replace``: replace characters that cannot be encoded with a replacement
character
Examples:
| `Open Connection` | lolcathost | encoding=Latin1 | encoding_errors=strict |
| `Set Encoding` | ISO-8859-15 |
| `Set Encoding` | errors=ignore |
== Default log level ==
Default log level specifies the log level keywords use for `logging` unless
they are given an explicit log level. The default value is ``INFO``, and
changing it, for example, to ``DEBUG`` can be a good idea if there is lot
of unnecessary output that makes log files big.
== Terminal type ==
By default the Telnet library does not negotiate any specific terminal type
with the server. If a specific terminal type, for example ``vt100``, is
desired, the terminal type can be configured in `importing` and with
`Open Connection`.
== Window size ==
Window size for negotiation with the server can be configured when
`importing` the library and with `Open Connection`.
== USER environment variable ==
Telnet protocol allows the ``USER`` environment variable to be sent when
connecting to the server. On some servers it may happen that there is no
login prompt, and on those cases this configuration option will allow still
to define the desired username. The option ``environ_user`` can be used in
`importing` and with `Open Connection`.
= Terminal emulation =
Telnet library supports terminal
emulation with [http://pyte.readthedocs.io|Pyte]. Terminal emulation
will process the output in a virtual screen. This means that ANSI escape
codes, like cursor movements, and also control characters, like
carriage returns and backspaces, have the same effect on the result as they
would have on a normal terminal screen. For example the sequence
``acdc\\x1b[3Dbba`` will result in output ``abba``.
Terminal emulation is taken into use by giving ``terminal_emulation``
argument a true value (see `Boolean arguments`) either in the library
initialization or with `Open Connection`.
As Pyte approximates vt-style terminal, you may also want to set the
terminal type as ``vt100``. We also recommend that you increase the window
size, as the terminal emulation will break all lines that are longer than
the window row length.
When terminal emulation is used, the `newline` and `encoding` can not be
changed anymore after opening the connection.
Examples:
| `Open Connection` | lolcathost | terminal_emulation=True | terminal_type=vt100 | window_size=400x100 |
As a prerequisite for using terminal emulation, you need to have Pyte
installed. Due to backwards incompatible changes in Pyte, different
Robot Framework versions support different Pyte versions:
- Pyte 0.6 and newer are supported by Robot Framework 3.0.3.
Latest Pyte version can be installed (or upgraded) with
``pip install --upgrade pyte``.
- Pyte 0.5.2 and older are supported by Robot Framework 3.0.2 and earlier.
Pyte 0.5.2 can be installed with ``pip install pyte==0.5.2``.
= Logging =
All keywords that read something log the output. These keywords take the
log level to use as an optional argument, and if no log level is specified
they use the [#Configuration|configured] default value.
The valid log levels to use are ``TRACE``, ``DEBUG``, ``INFO`` (default),
and ``WARN``. Levels below ``INFO`` are not shown in log files by default
whereas warnings are shown more prominently.
The [http://docs.python.org/library/telnetlib.html|telnetlib module]
used by this library has a custom logging system for logging content it
sends and receives. By default these messages are written using ``TRACE``
level, but the level is configurable with the ``telnetlib_log_level``
option either in the library initialization, to the `Open Connection`
or by using the `Set Telnetlib Log Level` keyword to the active
connection. Special level ``NONE`` con be used to disable the logging
altogether.
= Time string format =
Timeouts and other times used must be given as a time string using format
like ``15 seconds`` or ``1min 10s``. If the timeout is given as just
a number, for example, ``10`` or ``1.5``, it is considered to be seconds.
The time string format is described in more detail in an appendix of
[http://robotframework.org/robotframework/#user-guide|Robot Framework User Guide].
= Boolean arguments =
Some keywords accept arguments that are handled as Boolean values true or
false. If such an argument is given as a string, it is considered false if
it is an empty string or equal to ``FALSE``, ``NONE``, ``NO``, ``OFF`` or
``0``, case-insensitively. Other strings are considered true regardless
their value, and other argument types are tested using the same
[http://docs.python.org/library/stdtypes.html#truth|rules as in Python].
True examples:
| `Open Connection` | lolcathost | terminal_emulation=True | # Strings are generally true. |
| `Open Connection` | lolcathost | terminal_emulation=yes | # Same as the above. |
| `Open Connection` | lolcathost | terminal_emulation=${TRUE} | # Python ``True`` is true. |
| `Open Connection` | lolcathost | terminal_emulation=${42} | # Numbers other than 0 are true. |
False examples:
| `Open Connection` | lolcathost | terminal_emulation=False | # String ``false`` is false. |
| `Open Connection` | lolcathost | terminal_emulation=no | # Also string ``no`` is false. |
| `Open Connection` | lolcathost | terminal_emulation=${EMPTY} | # Empty string is false. |
| `Open Connection` | lolcathost | terminal_emulation=${FALSE} | # Python ``False`` is false. |
Considering string ``NONE`` false is new in Robot Framework 3.0.3 and
considering also ``OFF`` and ``0`` false is new in Robot Framework 3.1.
Definition at line 277 of file Telnet.py.
1.9.1