2.5.0 (jquast#122)

- **change**: `telnetlib3-client` now defaults to raw terminal mode (no line buffering, no local echo), which is correct for most servers. Use `--line-mode` to restore line-buffered local-echo behavior.
- **change**: `telnetlib3-server --pty-exec` now defaults to raw PTY mode. Use `--line-mode` to restore cooked PTY mode with echo.
- **change**: `connect_minwait` default reduced to 0 across `BaseClient`, `open_connection()`, and `telnetlib3-client`. Negotiation continues asynchronously. Use `--connect-minwait` to restore a delay if needed, or use `TelnetWriter.wait_for()` in server or client shells to await a specific negotiation state.
- **new**: Color, keyboard input translation and `--encoding` support for ATASCII (ATARI ASCII) and PETSCII (Commodore ASCII).
- **new**: SyncTERM/CTerm font selection sequence detection (`CSI Ps1 ; Ps2 SP D`). Both `telnetlib3-fingerprint` and `telnetlib3-client` detect font switching and auto-switch encoding to the matching codec (e.g. font 36 = ATASCII, 32-35 = PETSCII, 0 = CP437). Explicit `--encoding` takes precedence.
- **new**: `TRACE` log level (5, below `DEBUG`) with hexdump style output for all sent and received bytes. Use `--loglevel=trace`.
- **bugfix**: `robot_check()` now uses a narrow character (space) instead of a wide Unicode character, allowing retro terminal emulators to pass.
- **bugfix**: ATASCII codec now maps bytes 0x0D and 0x0A to CR and LF instead of graphics characters, fixing garbled output when connecting to Atari BBS systems.
- **bugfix**: ATASCII codec normalizes CR and CRLF to the native ATASCII EOL (0x9B) during encoding, so the Return key works correctly.
- **bugfix**: PETSCII bare CR (0x0D) is now normalized to CRLF in raw terminal mode and to LF in `telnetlib3-fingerprint` banners.
- **bugfix**: `telnetlib3-fingerprint` re-encodes prompt responses for retro encodings so servers receive the correct EOL byte.
- **bugfix**: `telnetlib3-fingerprint` no longer crashes with `LookupError` when the server negotiates an unknown charset. Banner formatting falls back to `latin-1`.
- **bugfix**: `TelnetClient.send_charset()` normalises non-standard encoding names (`iso-8859-02` to `iso-8859-2`, `cp-1250` to `cp1250`, etc.).
- **enhancement**: `telnetlib3-fingerprint` responds more like a terminal and to more y/n prompts about colors, encoding, etc. to collect more banners for the https://bbs.modem.xyz/ project.
- **enhancement**: `telnetlib3-fingerprint` banner formatting uses `surrogateescape` error handler, preserving raw high bytes (e.g. CP437 art) as surrogates instead of replacing them with U+FFFD.

Author: jquast

README.rst

@@ -72,10 +72,10 @@ program.
     telnetlib3-server
     # or custom port and ip and shell
     telnetlib3-server 0.0.0.0 1984 --shell=bin.server_wargame.shell
-    # run an external program with a pseudo-terminal
-    telnetlib3-server --pty-exec /bin/bash --pty-raw -- --login
-    # or a simple linemode program, bc (calculator)
-    telnetlib3-server --pty-exec /bin/bc
+    # run an external program with a pseudo-terminal (raw mode is default)
+    telnetlib3-server --pty-exec /bin/bash -- --login
+    # or a linemode program, bc (calculator)
+    telnetlib3-server --pty-exec /bin/bc --line-mode
 
 
 There are also fingerprinting CLIs, ``telnetlib3-fingerprint`` and

docs/guidebook.rst

@@ -205,6 +205,50 @@ and utf-8 support.
 The same applies to clients -- ``open_connection(..., encoding=False)``
 returns a ``(TelnetReader, TelnetWriter)`` pair that works with ``bytes``.
 
+Retro BBS Encodings
+~~~~~~~~~~~~~~~~~~~
+
+telnetlib3 includes custom codecs for retro computing platforms commonly
+found on telnet BBS systems:
+
+- **ATASCII** (``--encoding=atascii``) -- Atari 8-bit computers (400, 800,
+  XL, XE).  Graphics characters at 0x00-0x1F, card suits, box drawing, and
+  an inverse-video range at 0x80-0xFF.  The ATASCII end-of-line character
+  (0x9B) maps to newline.  Aliases: ``atari8bit``, ``atari_8bit``.
+- **PETSCII** (``--encoding=petscii``) -- Commodore 64/128 shifted
+  (lowercase) mode.  Lowercase a-z at 0x41-0x5A, uppercase A-Z at
+  0xC1-0xDA.  Aliases: ``cbm``, ``commodore``, ``c64``, ``c128``.
+- **Atari ST** (``--encoding=atarist``) -- Atari ST character set with
+  extended Latin, Greek, and math symbols.  Alias: ``atari``.
+
+These encodings use bytes 0x80-0xFF for standard glyphs, which conflicts
+with the telnet protocol's default 7-bit NVT mode.  When any of these
+encodings is selected, ``--force-binary`` is automatically enabled so that
+high-bit bytes are transmitted without requiring BINARY option negotiation.
+
+PETSCII inline color codes are translated to ANSI 24-bit RGB using the
+VIC-II C64 palette, and cursor control codes (up/down/left/right, HOME,
+CLR, DEL) are translated to ANSI sequences.  ATASCII control character
+glyphs (cursor movement, backspace, clear screen) are similarly translated.
+
+Keyboard input is also mapped: arrow keys, backspace, delete, and enter
+produce the correct raw bytes for each encoding::
+
+    telnetlib3-client --encoding=atascii area52.tk 5200
+    telnetlib3-client --encoding=petscii bbs.example.com 6400
+
+``telnetlib3-fingerprint`` decodes and translates banners with these
+encodings, including PETSCII colors.
+
+SyncTERM Font Detection
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+When a server sends a SyncTERM/CTerm font selection sequence
+(``CSI Ps1 ; Ps2 SP D``), both ``telnetlib3-client`` and
+``telnetlib3-fingerprint`` automatically switch the session encoding
+to match the font (e.g. font 36 = ATASCII, 32-35 = PETSCII, 0 = CP437).
+An explicit ``--encoding`` flag takes precedence over font detection.
+
 Line Endings
 ~~~~~~~~~~~~
 
@@ -230,6 +274,44 @@ as-is -- it does **not** convert ``\n`` to ``\r\n``::
 For maximum compatibility with MUD clients, legacy terminals, and standard
 telnet implementations, always use ``\r\n`` with ``write()``.
 
+Raw Mode and Line Mode
+~~~~~~~~~~~~~~~~~~~~~~
+
+``telnetlib3-client`` defaults to **raw terminal mode** -- the local
+terminal is set to raw (no line buffering, no local echo, no signal
+processing), and each keystroke is sent to the server immediately.  This
+is the correct mode for most BBS and MUD servers that handle their own
+echo and line editing.
+
+Use ``--line-mode`` to switch to line-buffered input with local echo,
+which is appropriate for simple command-line services that expect the
+client to perform local line editing::
+
+    # Default: raw mode (correct for most servers)
+    telnetlib3-client bbs.example.com
+
+    # Line mode: local echo and line buffering
+    telnetlib3-client --line-mode simple-service.example.com
+
+Similarly, ``telnetlib3-server --pty-exec`` defaults to raw PTY mode
+(disabling PTY echo), which is correct for programs that handle their own
+terminal I/O (curses, blessed, etc.).  Use ``--line-mode`` for programs
+that expect cooked/canonical PTY mode::
+
+    # Default: raw PTY (correct for curses programs)
+    telnetlib3-server --pty-exec /bin/bash -- --login
+
+    # Line mode: cooked PTY with echo (for simple programs like bc)
+    telnetlib3-server --pty-exec /bin/bc --line-mode
+
+Debugging
+~~~~~~~~~
+
+Use ``--loglevel=trace`` to see hexdump-style output of all bytes sent
+and received on the wire::
+
+    telnetlib3-client --loglevel=trace --logfile=debug.log bbs.example.com
+
 server_binary.py
 ~~~~~~~~~~~~~~~~
 

docs/history.rst

@@ -1,5 +1,49 @@
 History
 =======
+2.5.0
+  * change: ``telnetlib3-client`` now defaults to raw terminal mode (no line buffering, no local
+    echo), which is correct for most servers.  Use ``--line-mode`` to restore line-buffered
+    local-echo behavior.
+  * change: ``telnetlib3-server --pty-exec`` now defaults to raw PTY mode.  Use ``--line-mode`` to
+    restore cooked PTY mode with echo.
+  * change: ``connect_minwait`` default reduced to 0 across
+    :class:`~telnetlib3.client_base.BaseClient`, :func:`~telnetlib3.client.open_connection`, and
+    ``telnetlib3-client``.  Negotiation continues asynchronously.  Use ``--connect-minwait`` to
+    restore a delay if needed, or, use :meth:`~telnetlib3.stream_writer.TelnetWriter.wait_for` in
+    server or client shells to await a specific negotiation state.
+  * new: Color, keyboard input translation and ``--encoding`` support for ATASCII (ATARI ASCII) and
+    PETSCII (Commodore ASCII).
+  * new: SyncTERM/CTerm font selection sequence detection (``CSI Ps1 ; Ps2 SP D``).  Both
+    ``telnetlib3-fingerprint`` and ``telnetlib3-client`` detect font switching and auto-switch
+    encoding to the matching codec (e.g. font 36 = ATASCII, 32-35 = PETSCII, 0 = CP437).  Explicit
+    ``--encoding`` takes precedence.
+  * new: :data:`~telnetlib3.accessories.TRACE` log level (5, below ``DEBUG``) with
+    :func:`~telnetlib3.accessories.hexdump` style output for all sent and received bytes.  Use
+    ``--loglevel=trace``.
+  * bugfix: :func:`~telnetlib3.guard_shells.robot_check` now uses a narrow
+    character (space) instead of a wide Unicode character, allowing retro
+    terminal emulators to pass.
+  * bugfix: ATASCII codec now maps bytes 0x0D and 0x0A to CR and LF instead
+    of graphics characters, fixing garbled output when connecting to Atari
+    BBS systems.
+  * bugfix: ATASCII codec normalizes CR and CRLF to the native ATASCII
+    EOL (0x9B) during encoding, so the Return key works correctly.
+  * bugfix: PETSCII bare CR (0x0D) is now normalized to CRLF in raw
+    terminal mode and to LF in ``telnetlib3-fingerprint`` banners.
+  * bugfix: ``telnetlib3-fingerprint`` re-encodes prompt responses for retro
+    encodings so servers receive the correct EOL byte.
+  * bugfix: ``telnetlib3-fingerprint`` no longer crashes with
+    ``LookupError`` when the server negotiates an unknown charset.
+    Banner formatting falls back to ``latin-1``.
+  * bugfix: :meth:`~telnetlib3.client.TelnetClient.send_charset` normalises
+    non-standard encoding names (``iso-8859-02`` to ``iso-8859-2``,
+    ``cp-1250`` to ``cp1250``, etc.).
+  * enhancement: ``telnetlib3-fingerprint`` responds more like a terminal and to more
+    y/n prompts about colors, encoding, etc. to collect more banners for https://bbs.modem.xyz/
+    project.
+  * enhancement: ``telnetlib3-fingerprint`` banner formatting uses
+    ``surrogateescape`` error handler, preserving raw high bytes (e.g. CP437
+    art) as surrogates instead of replacing them with U+FFFD.
 
 2.4.0
   * new: :mod:`telnetlib3.color_filter` module — translates 16-color ANSI SGR
@@ -28,7 +72,13 @@ History
     auto-answers yes/no, color, UTF-8 menu, ``who``, and ``help`` prompts.
   * enhancement: ``--banner-max-bytes`` option for ``telnetlib3-fingerprint``;
     default raised from 1024 to 65536.
-  * enhancement: new ``--encoding=petscii`` and ``--encoding=atarist``
+  * new: ATASCII (Atari 8-bit) codec -- ``--encoding=atascii`` for connecting
+    to Atari BBS systems.  Maps all 256 byte values to Unicode including
+    graphics characters, card suits, and the inverse-video range (0x80-0xFF).
+    ATASCII EOL (0x9B) maps to newline.  Aliases: ``atari8bit``, ``atari_8bit``.
+  * enhancement: ``--encoding=atascii``, ``--encoding=petscii``, and
+    ``--encoding=atarist`` now auto-enable ``--force-binary`` for both client
+    and server, since these encodings use bytes 0x80-0xFF for standard glyphs.
   * bugfix: rare LINEMODE ACK loop with misbehaving servers that re-send
     unchanged MODE without ACK.
   * bugfix: unknown IAC commands no longer raise ``ValueError``; treated as

telnetlib3/accessories.py

@@ -9,14 +9,20 @@
 import importlib
 from typing import TYPE_CHECKING, Any, Dict, Union, Mapping, Callable, Optional
 
+#: Custom TRACE log level, below DEBUG (10).
+TRACE = 5
+logging.addLevelName(TRACE, "TRACE")
+
 if TYPE_CHECKING:  # pragma: no cover
     # local
     from .stream_reader import TelnetReader, TelnetReaderUnicode
 
 __all__ = (
+    "TRACE",
     "encoding_from_lang",
     "name_unicode",
     "eightbits",
+    "hexdump",
     "make_logger",
     "repr_mapping",
     "function_lookup",
@@ -96,6 +102,29 @@ def eightbits(number: int) -> str:
     return f"0b{int(value):08d}"
 
 
+def hexdump(data: bytes, prefix: str = "") -> str:
+    """
+    Format *data* as ``hexdump -C`` style output.
+
+    Each 16-byte row shows the offset, hex bytes grouped 8+8,
+    and printable ASCII on the right::
+
+        00000000  48 65 6c 6c 6f 20 57 6f  72 6c 64 0d 0a         |Hello World..|
+
+    :param data: Raw bytes to format.
+    :param prefix: String prepended to every line (e.g. ``">>  "``).
+    :rtype: str
+    """
+    lines: list[str] = []
+    for offset in range(0, len(data), 16):
+        chunk = data[offset : offset + 16]
+        hex_left = " ".join(f"{b:02x}" for b in chunk[:8])
+        hex_right = " ".join(f"{b:02x}" for b in chunk[8:])
+        ascii_part = "".join(chr(b) if 0x20 <= b < 0x7F else "." for b in chunk)
+        lines.append(f"{prefix}{offset:08x}  {hex_left:<23s}  {hex_right:<23s}  |{ascii_part}|")
+    return "\n".join(lines)
+
+
 _DEFAULT_LOGFMT = " ".join(
     ("%(asctime)s", "%(levelname)s", "%(filename)s:%(lineno)d", "%(message)s")
 )
@@ -105,7 +134,9 @@ def make_logger(
     name: str, loglevel: str = "info", logfile: Optional[str] = None, logfmt: str = _DEFAULT_LOGFMT
 ) -> logging.Logger:
     """Create and return simple logger for given arguments."""
-    lvl = getattr(logging, loglevel.upper())
+    lvl = getattr(logging, loglevel.upper(), None)
+    if lvl is None:
+        lvl = logging.getLevelName(loglevel.upper())
 
     _cfg: Dict[str, Any] = {"format": logfmt}
     if logfile: