telnetlib3: Async Telnet Server and Client

4.0.2 · active · verified Sat Apr 11

telnetlib3 is an asynchronous Python library for building Telnet servers and clients, supporting a wide array of Telnet Option specifications (RFCs). It offers both a programmatic API and command-line utilities. Currently at version 4.0.2, it maintains an active release cadence with frequent bug fixes and feature enhancements.

Warnings

breaking The `color_filter` module was removed. Any code directly importing or using this module will break.
Fix: Remove imports and usage of `telnetlib3.color_filter`. Consider migrating color filtering logic to a separate utility or `Telix` library if similar functionality is needed.
breaking The default operating mode for `telnetlib3-client` (CLI) and `telnetlib3-server --pty-exec` (CLI) changed from line-buffered local echo to raw terminal mode (no line buffering, no local echo). This significantly alters user interaction.
Fix: For the client, use the `--line-mode` CLI option to restore line-buffered behavior. For the server's PTY execution, use `--line-mode` with `--pty-exec` to restore cooked PTY mode with echo.
breaking The default value for the `connect_minwait` parameter in `open_connection()` and `create_server()` was changed from 1.0 seconds to 0 seconds. This affects how long the library waits before performing initial negotiation.
Fix: If your application relies on a minimum wait time for negotiation (e.g., for specific legacy clients/servers), explicitly set `connect_minwait=1.0` (or your desired value) when calling `open_connection()` or `create_server()`.
gotcha Prior to version 4.0.2, MCCP2 decompression could fail on some MUD servers using raw deflate or gzip-wrapped compression, leading to garbled banners or corrupted data.
Fix: Upgrade to `telnetlib3` version 4.0.2 or newer. The client now automatically detects zlib/gzip format and falls back to raw deflate as needed, resolving these decompression issues.

Install

pip install telnetlib3 Install stable version

Imports

telnetlib3
```
import telnetlib3
```
Primary library import, allows access to all functions via `telnetlib3.<function>`.
create_server
```
from telnetlib3 import create_server
```
Direct import for creating a Telnet server.
open_connection
```
from telnetlib3 import open_connection
```
Direct import for establishing a Telnet client connection.

Quickstart

This quickstart demonstrates a basic Telnet server using `telnetlib3`. It sets up an asynchronous server that echoes back any text received from connected clients. The server listens on port 6023 by default, or a port specified by the `TELNET_PORT` environment variable. To test, run this script and then connect with `telnet localhost 6023` in another terminal.

import telnetlib3
import asyncio
import os

async def simple_shell(reader, writer):
    peername = writer.get_extra_info('peername')
    print(f'Client {peername} connected.')
    writer.write(f'Hello, {peername}! Type something and press Enter (or Ctrl+C to quit).
')
    while True:
        try:
            text = await reader.read(1024)
            if not text:
                break
            print(f'Received from {peername}: {text!r}')
            writer.write(f'You said: {text!r}
')
            await writer.drain()
        except asyncio.IncompleteReadError:
            break # Client disconnected
        except ConnectionResetError:
            break # Client forcibly closed

    print(f'Client {peername} disconnected.')

async def main():
    # Use os.environ for port to make it runnable without hardcoding
    port = int(os.environ.get('TELNET_PORT', '6023'))
    server = await telnetlib3.create_server(port=port, shell=simple_shell)
    print(f"Telnet server listening on port {port}")
    async with server:
        await server.serve_forever()

if __name__ == '__main__':
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("Server stopped gracefully.")

view raw JSON →