telnetlib3¶

Python 3 asyncio Telnet server and client Protocol library.

Contents:

Introduction¶

telnetlib3 is a Telnet Client and Server library for python. This project requires python 3.3 and later, using the asyncio module.

Quick Example¶

Authoring a Telnet Server using Streams interface that offers a basic war game:

import asyncio, telnetlib3

@asyncio.coroutine
def shell(reader, writer):
    writer.write('\r\nWould you like to play a game? ')
    inp = yield from reader.read(1)
    if inp:
        writer.echo(inp)
        writer.write('\r\nThey say the only way to win '
                     'is to not play at all.\r\n')
        yield from writer.drain()
    writer.close()

loop = asyncio.get_event_loop()
coro = telnetlib3.create_server(port=6023, shell=shell)
server = loop.run_until_complete(coro)
loop.run_until_complete(server.wait_closed())

Authoring a Telnet Client that plays the war game with this server:

import asyncio, telnetlib3

@asyncio.coroutine
def shell(reader, writer):
    while True:
        # read stream until '?' mark is found
        outp = yield from reader.read(1024)
        if not outp:
            # End of File
            break
        elif '?' in outp:
            # reply all questions with 'y'.
            writer.write('y')

        # display all server output
        print(outp, flush=True)

    # EOF
    print()

loop = asyncio.get_event_loop()
coro = telnetlib3.open_connection('localhost', 6023, shell=shell)
reader, writer = loop.run_until_complete(coro)
loop.run_until_complete(writer.protocol.waiter_closed)

Command-line¶

Two command-line scripts are distributed with this package.

telnetlib3-client

Small terminal telnet client. Some example destinations and options:
telnetlib3-client nethack.alt.org
telnetlib3-client --encoding=cp437 --force-binary blackflag.acid.org
telnetlib3-client htc.zapto.org

telnetlib3-server

Telnet server providing the default debugging shell. This provides a simple shell server that allows introspection of the session’s values, for example:

tel:sh> help
quit, writer, slc, toggle [option|all], reader, proto

tel:sh> writer
<TelnetWriter server mode:kludge +lineflow -xon_any +slc_sim server-will:BINARY,ECHO,SGA client-will:BINARY,NAWS,NEW_ENVIRON,TTYPE>

tel:sh> reader
<TelnetReaderUnicode encoding='utf8' limit=65536 buflen=0 eof=False>

tel:sh> toggle all
wont echo.
wont suppress go-ahead.
wont outbinary.
dont inbinary.
xon-any enabled.
lineflow disabled.

tel:sh> reader
<TelnetReaderUnicode encoding='US-ASCII' limit=65536 buflen=1 eof=False>

tel:sh> writer
<TelnetWriter server mode:local -lineflow +xon_any +slc_sim client-will:NAWS,NEW_ENVIRON,TTYPE>

Both command-line scripts accept argument --shell=my_module.fn_shell describing a python module path to a coroutine of signature shell(reader, writer), just as the above examples.

Features¶

The following RFC specifications are implemented:

rfc-727, “Telnet Logout Option,” Apr 1977.
rfc-779, “Telnet Send-Location Option”, Apr 1981.
rfc-854, “Telnet Protocol Specification”, May 1983.
rfc-855, “Telnet Option Specifications”, May 1983.
rfc-856, “Telnet Binary Transmission”, May 1983.
rfc-857, “Telnet Echo Option”, May 1983.
rfc-858, “Telnet Suppress Go Ahead Option”, May 1983.
rfc-859, “Telnet Status Option”, May 1983.
rfc-860, “Telnet Timing mark Option”, May 1983.
rfc-885, “Telnet End of Record Option”, Dec 1983.
rfc-1073, “Telnet Window Size Option”, Oct 1988.
rfc-1079, “Telnet Terminal Speed Option”, Dec 1988.
rfc-1091, “Telnet Terminal-Type Option”, Feb 1989.
rfc-1096, “Telnet X Display Location Option”, Mar 1989.
rfc-1123, “Requirements for Internet Hosts”, Oct 1989.
rfc-1184, “Telnet Linemode Option (extended options)”, Oct 1990.
rfc-1372, “Telnet Remote Flow Control Option”, Oct 1992.
rfc-1408, “Telnet Environment Option”, Jan 1993.
rfc-1571, “Telnet Environment Option Interoperability Issues”, Jan 1994.
rfc-1572, “Telnet Environment Option”, Jan 1994.
rfc-2066, “Telnet Charset Option”, Jan 1997.

API¶

accessories¶

Accessory functions.

encoding_from_lang(lang)[source]¶

Parse encoding from LANG environment value.

Example:

>>> encoding_from_lang('en_US.UTF-8@misc')
'UTF-8'

name_unicode(ucs)[source]¶: Return 7-bit ascii printable of any string.

eightbits(number)[source]¶

Binary representation of number padded to 8 bits.

Example:

>>> eightbits(ord('a'))
'0b01100001'

make_logger(name, loglevel='info', logfile=None, logfmt='%(asctime)s %(levelname)s %(filename)s:%(lineno)d %(message)s')[source]¶: Create and return simple logger for given arguments.

repr_mapping(mapping)[source]¶: Return printable string, ‘key=value [key=value …]’ for mapping.

function_lookup(pymod_path)[source]¶: Return callable function target from standard module.function path.

make_reader_task(reader, size=4096)[source]¶: Return asyncio task wrapping coroutine of reader.read(size).

client¶

Telnet Client API for the ‘telnetlib3’ python package.

class TelnetClient(term='unknown', cols=80, rows=25, tspeed=38400, 38400, xdisploc='', *args, **kwargs)[source]¶

Telnet client that supports all common options.

This class is useful for automation, it appears to be a virtual terminal to the remote end, but does not require an interactive terminal to run.

Class initializer.

DEFAULT_LOCALE = 'en_US'¶: On send_env(), the value of ‘LANG’ will be ‘C’ for binary transmission. When encoding is specified (utf8 by default), the LANG variable must also contain a locale, this value is used, providing a full default LANG value of ‘en_US.utf8’

connection_made(transport)[source]¶: Callback for connection made to server.

send_ttype()[source]¶: Callback for responding to TTYPE requests.

send_tspeed()[source]¶: Callback for responding to TSPEED requests.

send_xdisploc()[source]¶: Callback for responding to XDISPLOC requests.

send_env(keys)[source]¶

Callback for responding to NEW_ENVIRON requests.

Parameters: keys (dict) – Values are requested for the keys specified. When empty, all environment values that wish to be volunteered should be returned.
Returns: dictionary of environment values requested, or an empty string for keys not available. A return value must be given for each key requested.
Return type: dict

send_charset(offered)[source]¶

Callback for responding to CHARSET requests.

Receives a list of character encodings offered by the server as offered such as ('LATIN-1', 'UTF-8'), for which the client may return a value agreed to use, or None to disagree to any available offers. Server offerings may be encodings or codepages.

The default implementation selects any matching encoding that python is capable of using, preferring any that matches encoding if matched in the offered list.

Parameters: offered (list) – list of CHARSET options offered by server.
Returns: character encoding agreed to be used.
Return type: Union[str, None]

send_naws()[source]¶

Callback for responding to NAWS requests.

Return type: (int, int)
Returns: client window size as (rows, columns).

encoding(outgoing=None, incoming=None)[source]¶

Return encoding for the given stream direction.

Parameters

outgoing (bool) – Whether the return value is suitable for encoding bytes for transmission to server.
incoming (bool) – Whether the return value is suitable for decoding bytes received by the client.

Raises

TypeError – when a direction argument, either outgoing or incoming, was not set True.

Returns

'US-ASCII' for the directions indicated, unless BINARY RFC 856 has been negotiated for the direction indicated or :attr`force_binary` is set True.

Return type

str

class TelnetTerminalClient(term='unknown', cols=80, rows=25, tspeed=38400, 38400, xdisploc='', *args, **kwargs)[source]¶

Telnet client for sessions with a network virtual terminal (NVT).

Class initializer.

send_naws()[source]¶

Callback replies to request for window size, NAWS RFC 1073.

Return type: (int, int)
Returns: window dimensions by lines and columns

send_env(keys)[source]¶

Callback replies to request for env values, NEW_ENVIRON RFC 1572.

Return type: dict
Returns: super class value updated with window LINES and COLUMNS.

open_connection(host=None, port=23, *, client_factory=None, loop=None, family=0, flags=0, local_addr=None, log=None, encoding='utf8', encoding_errors='replace', force_binary=False, term='unknown', cols=80, rows=25, tspeed=38400, 38400, xdisploc='', shell=None, connect_minwait=2.0, connect_maxwait=3.0, waiter_closed=None, _waiter_connected=None, limit=None)[source]¶

Connect to a TCP Telnet server as a Telnet client.

Parameters

host (str) – Remote Internet TCP Server host.
port (int) – Remote Internet host TCP port.
client_factory (client_base.BaseClient) – Client connection class factory. When None, TelnetTerminalClient is used when stdin is attached to a terminal, TelnetClient otherwise.
loop (asyncio.AbstractEventLoop) – set the event loop to use. The return value of asyncio.get_event_loop() is used when unset.
family (int) – Same meaning as asyncio.loop.create_connection().
flags (int) – Same meaning as asyncio.loop.create_connection().
local_addr (tuple) – Same meaning as asyncio.loop.create_connection().
log (logging.Logger) – target logger, if None is given, one is created using the namespace 'telnetlib3.server'.
encoding (str) –
The default assumed encoding, or False to disable unicode support. This value is used for decoding bytes received by and encoding bytes transmitted to the Server. These values are preferred in response to NEW_ENVIRON RFC 1572 as environment value LANG, and by CHARSET RFC 2066 negotiation.

The server’s attached reader, writer streams accept and return unicode, unless this value explicitly set False. In that case, the attached streams interfaces are bytes-only.
term (str) – Terminal type sent for requests of TTYPE, RFC 930 or as Environment value TERM by NEW_ENVIRON negotiation, RFC 1672.
cols (int) – Client window dimension sent as Environment value COLUMNS by NEW_ENVIRON negotiation, RFC 1672 or NAWS RFC 1073.
rows (int) – Client window dimension sent as Environment value LINES by NEW_ENVIRON negotiation, RFC 1672 or NAWS RFC 1073.
tspeed (tuple) – Tuple of client BPS line speed in form (rx, tx) for receive and transmit, respectively. Sent when requested by TSPEED, RFC 1079.
xdisploc (str) – String transmitted in response for request of XDISPLOC, RFC 1086 by server (X11).
shell (Callable) – A asyncio.coroutine() that is called after negotiation completes, receiving arguments (reader, writer). The reader is a TelnetReader instance, the writer is a TelnetWriter instance.
connect_minwait (float) –
The client allows any additional telnet negotiations to be demanded by the server within this period of time before launching the shell. Servers should assert desired negotiation on-connect and in response to 1 or 2 round trips.

A server that does not make any telnet demands, such as a TCP server that is not a telnet server will delay the execution of shell for exactly this amount of time.
connect_maxwait (float) – If the remote end is not complaint, or otherwise confused by our demands and failing to reply to pending negotiations, the shell continues anyway after the greater of this value or connect_minwait elapsed.
force_binary (bool) – When True, the encoding specified is used for both directions even when failing BINARY negotiation, RFC 856. This parameter has no effect when encoding=False.
encoding_errors (str) – Same meaning as codecs.Codec.encode().
connect_minwait – XXX
connect_maxwait – If the remote end is not complaint, or otherwise confused by our demands, the shell continues anyway after the greater of this value has elapsed. A client that is not answering option negotiation will delay the start of the shell by this amount.
limit (int) – The buffer limit for reader stream.

Return (reader, writer)

The reader is a TelnetReader instance, the writer is a TelnetWriter instance.

This function is a coroutine().

client_base¶

Module provides class BaseClient.

class BaseClient(shell=None, log=None, loop=None, encoding='utf8', encoding_errors='strict', force_binary=False, connect_minwait=1.0, connect_maxwait=4.0, limit=None, waiter_closed=None, _waiter_connected=None)[source]¶

Base Telnet Client Protocol.

Class initializer.

default_encoding¶: encoding for new connections

connect_minwait¶: minimum duration for check_negotiation().

connect_maxwait¶: maximum duration for check_negotiation().

eof_received()[source]¶: Called when the other end calls write_eof() or equivalent.

connection_lost(exc)[source]¶

Called when the connection is lost or closed.

Parameters: exc (Exception) – exception. None indicates a closing EOF sent by this end.

connection_made(transport)[source]¶

Called when a connection is made.

Ensure super().connection_made(transport) is called when derived.

data_received(data)[source]¶: Process bytes received by transport.

property duration¶: Time elapsed since client connected, in seconds as float.

property idle¶: Time elapsed since data last received, in seconds as float.

get_extra_info(name, default=None)[source]¶: Get optional client protocol or transport information.

begin_negotiation()[source]¶

Begin on-connect negotiation.

A Telnet client is expected to send only a minimal amount of client session options immediately after connection, it is generally the server which dictates server option support.

Deriving implementations should always call super().begin_negotiation().

encoding(outgoing=False, incoming=False)[source]¶

Encoding that should be used for the direction indicated.

The base implementation always returns encoding argument given to class initializer or, when unset (None), US-ASCII.

check_negotiation(final=False)[source]¶

Callback, return whether negotiation is complete.

Parameters: final (bool) – Whether this is the final time this callback will be requested to answer regarding protocol negotiation.
Returns: Whether negotiation is over (client end is satisfied).
Return type: bool

Method is called on each new command byte processed until negotiation is considered final, or after connect_maxwait has elapsed, setting the _waiter_connected attribute to value self when complete.

This method returns False until connect_minwait has elapsed, ensuring the server may batch telnet negotiation demands without prematurely entering the callback shell.

Ensure super().check_negotiation() is called and conditionally combined when derived.

client_shell¶

telnet_client_shell(telnet_reader, telnet_writer)[source]¶

Minimal telnet client shell for POSIX terminals.

This shell performs minimal tty mode handling when a terminal is attached to standard in (keyboard), notably raw mode is often set and this shell may exit only by disconnect from server, or the escape character, ^].

stdin or stdout may also be a pipe or file, behaving much like nc(1).

This function is a coroutine().

server¶

The main function here is wired to the command line tool by name telnetlib3-server. If this server’s PID receives the SIGTERM signal, it attempts to shutdown gracefully.

The TelnetServer class negotiates a character-at-a-time (WILL-SGA, WILL-ECHO) session with support for negotiation about window size, environment variables, terminal type name, and to automatically close connections clients after an idle period.

class TelnetServer(term='unknown', cols=80, rows=25, timeout=300, *args, **kwargs)[source]¶

Telnet Server protocol performing common negotiation.

Class initializer.

TTYPE_LOOPMAX = 8¶: Maximum number of cycles to seek for all terminal types. We are seeking the repeat or cycle of a terminal table, choosing the first – but when negotiated by MUD clients, we chose the must Unix TERM appropriate,

connection_made(transport)[source]¶

Called when a connection is made.

Sets attributes _transport, _when_connected, _last_received, reader and writer.

Ensure super().connection_made(transport) is called when derived.

data_received(data)[source]¶: Process bytes received by transport.

begin_negotiation()[source]¶

Begin on-connect negotiation.

A Telnet server is expected to demand preferred session options immediately after connection. Deriving implementations should always call super().begin_negotiation().

begin_advanced_negotiation()[source]¶

Begin advanced negotiation.

Callback method further requests advanced telnet options. Called once on receipt of any DO or WILL acknowledgments received, indicating that the remote end is capable of negotiating further.

Only called if sub-classing begin_negotiation() causes at least one negotiation option to be affirmatively acknowledged.

check_negotiation(final=False)[source]¶

Callback, return whether negotiation is complete.

Parameters: final (bool) – Whether this is the final time this callback will be requested to answer regarding protocol negotiation.
Returns: Whether negotiation is over (server end is satisfied).
Return type: bool

Method is called on each new command byte processed until negotiation is considered final, or after connect_maxwait has elapsed, setting attribute _waiter_connected to value self when complete.

Ensure super().check_negotiation() is called and conditionally combined when derived.

encoding(outgoing=None, incoming=None)[source]¶

Return encoding for the given stream direction.

Parameters

outgoing (bool) – Whether the return value is suitable for encoding bytes for transmission to client end.
incoming (bool) – Whether the return value is suitable for decoding bytes received from the client.

Raises

TypeError – when a direction argument, either outgoing or incoming, was not set True.

Returns

'US-ASCII' for the directions indicated, unless BINARY RFC 856 has been negotiated for the direction indicated or :attr`force_binary` is set True.

Return type

str

set_timeout(duration=- 1)[source]¶

Restart or unset timeout for client.

Parameters: duration (int) – When specified as a positive integer, schedules Future for callback of on_timeout(). When -1, the value of self.get_extra_info('timeout') is used. When non-True, it is canceled.

on_timeout()[source]¶

Callback received on session timeout.

Default implementation writes “Timeout.” bound by CRLF and closes.

This can be disabled by calling set_timeout() with duration value of 0 or value of the same for keyword argument timeout.

on_naws(rows, cols)[source]¶

Callback receives NAWS response, RFC 1073.

Parameters

rows (int) – screen size, by number of cells in height.
cols (int) – screen size, by number of cells in width.

on_request_environ()[source]¶

Definition for NEW_ENVIRON request of client, RFC 1572.

This method is a callback from request_environ(), first entered on receipt of (WILL, NEW_ENVIRON) by server. The return value defines the request made to the client for environment values.

Rtype list

a list of unicode character strings of US-ASCII characters, indicating the environment keys the server requests of the client. If this list contains the special byte constants, USERVAR or VAR, the client is allowed to volunteer any other additional user or system values.

Any empty return value indicates that no request should be made.

The default return value is:

['LANG', 'TERM', 'COLUMNS', 'LINES', 'DISPLAY', 'COLORTERM',
 VAR, USERVAR, 'COLORTERM']

on_environ(mapping)[source]¶: Callback receives NEW_ENVIRON response, RFC 1572.

on_request_charset()[source]¶

Definition for CHARSET request by client, RFC 2066.

This method is a callback from request_charset(), first entered on receipt of (WILL, CHARSET) by server. The return value defines the request made to the client for encodings.

Rtype list

a list of unicode character strings of US-ASCII characters, indicating the encodings offered by the server in its preferred order.

Any empty return value indicates that no encodings are offered.

The default return value begins:

['UTF-8', 'UTF-16', 'LATIN1', 'US-ASCII', 'BIG5', 'GBK', ...]

on_charset(charset)[source]¶: Callback for CHARSET response, RFC 2066.

on_tspeed(rx, tx)[source]¶: Callback for TSPEED response, RFC 1079.

on_ttype(ttype)[source]¶: Callback for TTYPE response, RFC 930.

on_xdisploc(xdisploc)[source]¶: Callback for XDISPLOC response, RFC 1096.

create_server(host=None, port=23, protocol_factory=<class 'telnetlib3.server.TelnetServer'>, **kwds)[source]¶

Create a TCP Telnet server.

Parameters

host (str) – The host parameter can be a string, in that case the TCP server is bound to host and port. The host parameter can also be a sequence of strings, and in that case the TCP server is bound to all hosts of the sequence.
port (int) – listen port for TCP Server.
protocol_factory (server_base.BaseServer) – An alternate protocol factory for the server, when unspecified, TelnetServer is used.
shell (Callable) – A asyncio.coroutine() that is called after negotiation completes, receiving arguments (reader, writer). The reader is a TelnetReader instance, the writer is a TelnetWriter instance.
log (logging.Logger) – target logger, if None is given, one is created using the namespace 'telnetlib3.server'.
encoding (str) –
The default assumed encoding, or False to disable unicode support. Encoding may be negotiation to another value by the client through NEW_ENVIRON RFC 1572 by sending environment value of LANG, or by any legal value for CHARSET RFC 2066 negotiation.

The server’s attached reader, writer streams accept and return unicode, unless this value explicitly set False. In that case, the attached streams interfaces are bytes-only.
encoding_errors (str) – Same meaning as codecs.Codec.encode(). Default value is strict.
force_binary (bool) – When True, the encoding specified is used for both directions even when BINARY mode, RFC 856, is not negotiated for the direction specified. This parameter has no effect when encoding=False.
term (str) – Value returned for writer.get_extra_info('term') until negotiated by TTYPE RFC 930, or NAWS RFC 1572. Default value is 'unknown'.
cols (int) – Value returned for writer.get_extra_info('cols') until negotiated by NAWS RFC 1572. Default value is 80 columns.
rows (int) – Value returned for writer.get_extra_info('rows') until negotiated by NAWS RFC 1572. Default value is 25 rows.
timeout (int) – Causes clients to disconnect if idle for this duration, in seconds. This ensures resources are freed on busy servers. When explicitly set to False, clients will not be disconnected for timeout. Default value is 300 seconds (5 minutes).
connect_maxwait (float) – If the remote end is not complaint, or otherwise confused by our demands, the shell continues anyway after the greater of this value has elapsed. A client that is not answering option negotiation will delay the start of the shell by this amount.
limit (int) – The buffer limit for the reader stream.

Return asyncio.Server

The return value is the same as asyncio.loop.create_server(), An object which can be used to stop the service.

This function is a coroutine().

run_server(host='localhost', port=6023, loglevel='info', logfile=None, logfmt='%(asctime)s %(levelname)s %(filename)s:%(lineno)d %(message)s', shell=<function telnet_server_shell>, encoding='utf8', force_binary=False, timeout=300, connect_maxwait=4.0)[source]¶

Program entry point for server daemon.

This function configures a logger and creates a telnet server for the given keyword arguments, serving forever, completing only upon receipt of SIGTERM.

server_base¶

Module provides class BaseServer.

class BaseServer(shell=None, log=None, loop=None, _waiter_connected=None, _waiter_closed=None, encoding='utf8', encoding_errors='strict', force_binary=False, connect_maxwait=4.0, limit=None)[source]¶

Base Telnet Server Protocol.

Class initializer.

connect_maxwait¶: maximum duration for check_negotiation().

eof_received()[source]¶

Called when the other end calls write_eof() or equivalent.

This callback may be exercised by the nc(1) client argument -z.

connection_lost(exc)[source]¶

Called when the connection is lost or closed.

Parameters: exc (Exception) – exception. None indicates close by EOF.

connection_made(transport)[source]¶

Called when a connection is made.

Sets attributes _transport, _when_connected, _last_received, reader and writer.

Ensure super().connection_made(transport) is called when derived.

data_received(data)[source]¶: Process bytes received by transport.

property duration¶: Time elapsed since client connected, in seconds as float.

property idle¶: Time elapsed since data last received, in seconds as float.

get_extra_info(name, default=None)[source]¶: Get optional server protocol or transport information.

begin_negotiation()[source]¶

Begin on-connect negotiation.

A Telnet server is expected to demand preferred session options immediately after connection. Deriving implementations should always call super().begin_negotiation().

begin_advanced_negotiation()[source]¶

Begin advanced negotiation.

Callback method further requests advanced telnet options. Called once on receipt of any DO or WILL acknowledgments received, indicating that the remote end is capable of negotiating further.

Only called if sub-classing begin_negotiation() causes at least one negotiation option to be affirmatively acknowledged.

encoding(outgoing=False, incoming=False)[source]¶

Encoding that should be used for the direction indicated.

The base implementation always returns the encoding given to class initializer, or, when unset (None), US-ASCII.

negotiation_should_advance()[source]¶

Whether advanced negotiation should commence.

Return type: bool
Returns: True if advanced negotiation should be permitted.

The base implementation returns True if any negotiation options were affirmatively acknowledged by client, more than likely options requested in callback begin_negotiation().

check_negotiation(final=False)[source]¶

Callback, return whether negotiation is complete.

Parameters: final (bool) – Whether this is the final time this callback will be requested to answer regarding protocol negotiation.
Returns: Whether negotiation is over (server end is satisfied).
Return type: bool

Method is called on each new command byte processed until negotiation is considered final, or after connect_maxwait has elapsed, setting attribute _waiter_connected to value self when complete.

Ensure super().check_negotiation() is called and conditionally combined when derived.

server_shell¶

telnet_server_shell(reader, writer)[source]¶

A default telnet shell, appropriate for use with telnetlib3.create_server.

This shell provides a very simple REPL, allowing introspection and state toggling of the connected client session.

This function is a coroutine().

slc¶

Special Line Character support for Telnet Linemode Option (RFC 1184).

generate_slctab(tabset={b'\x01': <telnetlib3.slc.SLC object>, b'\x02': <telnetlib3.slc.SLC object>, b'\x03': <telnetlib3.slc.SLC object>, b'\x04': <telnetlib3.slc.SLC object>, b'\x05': <telnetlib3.slc.SLC object>, b'\x06': <telnetlib3.slc.SLC object>, b'\x07': <telnetlib3.slc.SLC object>, b'\x08': <telnetlib3.slc.SLC object>, b'\t': <telnetlib3.slc.SLC object>, b'\n': <telnetlib3.slc.SLC object>, b'\x0b': <telnetlib3.slc.SLC object>, b'\x0c': <telnetlib3.slc.SLC object>, b'\r': <telnetlib3.slc.SLC object>, b'\x0e': <telnetlib3.slc.SLC object>, b'\x0f': <telnetlib3.slc.SLC object>, b'\x10': <telnetlib3.slc.SLC object>, b'\x11': <telnetlib3.slc.SLC_nosupport object>, b'\x12': <telnetlib3.slc.SLC_nosupport object>})[source]¶: Returns full ‘SLC Tab’ for definitions found using tabset. Functions not listed in tabset are set as SLC_NOSUPPORT.

class Linemode(mask=b'\x00')[source]¶

A mask of LMODE_MODE_LOCAL means that all line editing is performed on the client side (default). A mask of theNULL () indicates that editing is performed on the remote side. Valid bit flags of mask are: LMODE_MODE_TRAPSIG, LMODE_MODE_ACK, LMODE_MODE_SOFT_TAB, and LMODE_MODE_LIT_ECHO.

property local¶: True if linemode is local.

property remote¶: True if linemode is remote.

property trapsig¶: True if signals are trapped by client.

property ack¶: Returns True if mode has been acknowledged.

property soft_tab¶: Returns True if client will expand horizontal tab ( ).

property lit_echo¶: Returns True if non-printable characters are displayed as-is.

snoop(byte, slctab, slc_callbacks)[source]¶

Scan slctab for matching byte values.

Returns (callback, func_byte, slc_definition) on match. Otherwise, (None, None, None). If no callback is assigned, the value of callback is always None.

generate_forwardmask(binary_mode, tabset, ack=False)[source]¶

Generate a Forwardmask instance.

Generate a 32-byte (binary_mode is True) or 16-byte (False) Forwardmask instance appropriate for the specified slctab. A Forwardmask is formed by a bitmask of all 256 possible 8-bit keyboard ascii input, or, when not ‘outbinary’, a 16-byte 7-bit representation of each value, and whether or not they should be “forwarded” by the client on the transport stream

class Forwardmask(value, ack=False)[source]¶

Forwardmask object using the bytemask value received by server.

Parameters: value (bytes) – bytemask value received by server after IAC SB LINEMODE DO FORWARDMASK. It must be a bytearray of length 16 or 32.

description_table()[source]¶: Returns list of strings describing obj as a tabular ASCII map.

name_slc_command(byte)[source]¶: Given an SLC byte, return global mnemonic as string.

stream_reader¶

Module provides class TelnetReader and TelnetReaderUnicode.

class TelnetReader(*args, **kwargs)[source]¶

A reader interface for the telnet protocol.

readline()[source]¶

Read one line.

Where “line” is a sequence of characters ending with CR LF, LF, or CR NUL. This readline function is a strict interpretation of Telnet Protocol RFC 854.

The sequence “CR LF” must be treated as a single “new line” character and used whenever their combined action is intended; The sequence “CR NUL” must be used where a carriage return alone is actually desired; and the CR character must be avoided in other contexts.

And therefor, a line does not yield for a stream containing a CR if it is not succeeded by NUL or LF.

Given stream	readline() yields
`--\r\x00---`	`--\r`, `---` …
`--\r\n---`	`--\r\n`, `---` …
`--\n---`	`--\n`, `---` …
`--\r---`	`--\r`, `---` …

If EOF is received before the termination of a line, the method will yield the partially read string.

This method is a coroutine().

class TelnetReaderUnicode(fn_encoding, *, limit=65536, loop=None, encoding_errors='replace')[source]¶

A Unicode StreamReader interface for Telnet protocol.

Parameters: fn_encoding (Callable) – function callback, receiving boolean keyword argument, incoming=True, which is used by the callback to determine what encoding should be used to decode the value in the direction specified.

decode(buf, final=False)[source]¶: Decode bytes buf using preferred encoding.

readline()[source]¶

Read one line.

See ancestor method, readline() for details.

This method is a coroutine().

read(n=- 1)[source]¶

Read up to n bytes.

If the EOF was received and the internal buffer is empty, return an empty string.

Parameters: n (int) – If n is not provided, or set to -1, read until EOF and return all characters as one large string.
Return type: str

This method is a coroutine().

readexactly(n)[source]¶

Read exactly n unicode characters.

Raises: asyncio.IncompleteReadError – if the end of the stream is reached before n can be read. the asyncio.IncompleteReadError.partial attribute of the exception contains the partial read characters.
Return type: str

This method is a coroutine().

stream_writer¶

Module provides TelnetWriter and TelnetWriterUnicode.

class TelnetWriter(transport, protocol, *, client=False, server=False, reader=None, loop=None, log=None)[source]¶

A writer interface for the telnet protocol.

Telnet IAC Interpreter.

Almost all negotiation actions are performed through the writer interface, as any action requires writing bytes to the underling stream. This class implements feed_byte(), which acts as a Telnet Is-A-Command (IAC) interpreter.

The significance of the last byte passed to this method is tested by instance attribute is_oob, following the call to feed_byte() to determine whether the given byte is in or out of band.

A minimal Telnet Protocol method, asyncio.Protocol.data_received(), should forward each byte to feed_byte(), which returns True to indicate the given byte should be forwarded to a Protocol reader method.

Parameters

client (bool) – Whether the IAC interpreter should react from the client point of view.
server (bool) – Whether the IAC interpreter should react from the server point of view.
log (logging.Logger) – target logger, if None is given, one is created using the namespace 'telnetlib3.stream_writer'.
loop (asyncio.AbstractEventLoop) – set the event loop to use. The return value of asyncio.get_event_loop() is used when unset.

byte_count = 0¶: Total bytes sent to feed_byte()

lflow = True¶: Whether flow control is enabled.

xon_any = False¶: Whether flow control enabled by Transmit-Off (XOFF) (Ctrl-s), should re-enable Transmit-On (XON) only on receipt of XON (Ctrl-q). When False, any keypress from client re-enables transmission.

iac_received = None¶: Whether the last byte received by feed_byte() is the beginning of an IAC command.

cmd_received = None¶: Whether the last byte received by feed_byte() begins an IAC command sequence.

slc_received = None¶: Whether the last byte received by feed_byte() is a matching special line character value, if negotiated.

slc_simulated = True¶: SLC function values and callbacks are fired for clients in Kludge mode not otherwise capable of negotiating LINEMODE, providing transport remote editing function callbacks for dumb clients.

default_linemode = <b'\x10': lit_echo:True, soft_tab:False, ack:False, trapsig:False, remote:True, local:False>¶: Initial line mode requested by server if client supports LINEMODE negotiation (remote line editing and literal echo of control chars)

pending_option¶: Dictionary of telnet option byte(s) that follow an IAC-DO or IAC-DONT command, and contains a value of True until IAC-WILL or IAC-WONT has been received by remote end.

local_option¶: Dictionary of telnet option byte(s) that follow an IAC-WILL or IAC-WONT command, sent by our end, indicating state of local capabilities.

remote_option¶: Dictionary of telnet option byte(s) that follow an IAC-WILL or IAC-WONT command received by remote end, indicating state of remote capabilities.

slctab¶: SLC Tab (SLC Functions and their support level, and ascii value)

write(data)[source]¶

Write a bytes object to the protocol transport.

Return type: None

writelines(lines)[source]¶

Write unicode strings to transport.

Note that newlines are not added. The sequence can be any iterable object producing strings. This is equivalent to calling write() for each string.

feed_byte(byte)[source]¶

Feed a single byte into Telnet option state machine.

Parameters: byte (int) – an 8-bit byte value as integer (0-255), or a bytes array. When a bytes array, it must be of length 1.
Rtype bool: Whether the given byte is “in band”, that is, should be duplicated to a connected terminal or device. False is returned for an IAC command for each byte until its completion.

get_extra_info(name, default=None)[source]¶: Get optional server protocol information.

property protocol¶: The protocol attached to this stream.

property server¶: Whether this stream is of the server’s point of view.

property client¶: Whether this stream is of the client’s point of view.

property inbinary¶: Whether binary data is expected to be received on reader, RFC 856.

property outbinary¶: Whether binary data may be written to the writer, RFC 856.

echo(data)[source]¶

Conditionally write data to transport when “remote echo” enabled.

Parameters: data (bytes) – string received as input, conditionally written.
Return type: None

The default implementation depends on telnet negotiation willingness for local echo, only an RFC-compliant telnet client will correctly set or unset echo accordingly by demand.

property will_echo¶

Whether Server end is expected to echo back input sent by client.

From server perspective: the server should echo (duplicate) client input back over the wire, the client is awaiting this data to indicate their input has been received.

From client perspective: the server will not echo our input, we should chose to duplicate our input to standard out ourselves.

property mode¶

String describing NVT mode.

Rtype str

One of:

kludge: Client acknowledges WILL-ECHO, WILL-SGA. character-at-: a-time and remote line editing may be provided.
local: Default NVT half-duplex mode, client performs line: editing and transmits only after pressing send (usually CR)
remote: Client supports advanced remote line editing, using: mixed-mode local line buffering (optionally, echoing) until send, but also transmits buffer up to and including special line characters (SLCs).

property is_oob¶: The previous byte should not be received by the API stream.

property linemode¶

Linemode instance for stream.

Note

value is meaningful after successful LINEMODE negotiation, otherwise does not represent the linemode state of the stream.

Attributes of the stream’s active linemode may be tested using boolean instance attributes, edit, trapsig, soft_tab, lit_echo, remote, local.

send_iac(buf)[source]¶

Send a command starting with IAC (base 10 byte value 255).

No transformations of bytes are performed. Normally, if the byte value 255 is sent, it is escaped as IAC + IAC. This method ensures it is not escaped,.

iac(cmd, opt=b'')[source]¶

Send Is-A-Command 3-byte negotiation command.

Returns True if command was sent. Not all commands are legal in the context of client, server, or pending negotiation state, emitting a relevant debug warning to the log handler if not sent.

send_ga()[source]¶

Transmit IAC GA (Go-Ahead).

Returns True if sent. If IAC-DO-SGA has been received, then False is returned and IAC-GA is not transmitted.

send_eor()[source]¶

Transmit IAC CMD_EOR (End-of-Record), RFC 885.

Returns True if sent. If IAC-DO-EOR has not been received, False is returned and IAC-CMD_EOR is not transmitted.

request_status()[source]¶

Send IAC-SB-STATUS-SEND sub-negotiation (RFC 859).

This method may only be called after IAC-WILL-STATUS has been received. Returns True if status request was sent.

request_tspeed()[source]¶

Send IAC-SB-TSPEED-SEND sub-negotiation, RFC 1079.

This method may only be called after IAC-WILL-TSPEED has been received. Returns True if TSPEED request was sent.

request_charset()[source]¶

Request sub-negotiation CHARSET, RFC 2066.