Introduction

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

.. _asyncio: http://docs.python.org/3.11/library/asyncio.html

Quick Example

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

.. code-block:: python

import asyncio, telnetlib3

async def shell(reader, writer):
    writer.write('\r\nWould you like to play a game? ')
    inp = await 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')
        await 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:

.. code-block:: python

import asyncio, telnetlib3

async def shell(reader, writer):
    while True:
        # read stream until '?' mark is found
        outp = await 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.

jquast / telnetlib3

readme

Introduction

Quick Example

Command-line

Features

Further Reading