telnetlib3 3.0.2__tar.gz → 3.0.3__tar.gz

{telnetlib3-3.0.2 → telnetlib3-3.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telnetlib3
-Version: 3.0.2
+Version: 3.0.3
 Summary:  Python Telnet server and client CLI and Protocol library
 Project-URL: Homepage, https://github.com/jquast/telnetlib3
 Project-URL: Documentation, https://telnetlib3.readthedocs.io

{telnetlib3-3.0.2 → telnetlib3-3.0.3}/docs/history.rst

@@ -1,5 +1,15 @@
 History
 =======
+3.0.3
+  * bugfix: server and client now correctly complete LINEMODE negotiation when prompted to.
+  * new: ``--logfile-mode {append,rewrite}`` and ``--typescript-mode`` CLI flags
+    and :func:`~telnetlib3.accessories.make_logger` ``filemode`` argument control whether the log
+    file is appended to (default) or overwritten on each connection.
+  * new: :class:`~telnetlib3.client_shell.LinemodeBuffer` used by ``telnetlib3-client``, a
+    client-side line buffer for LINEMODE EDIT mode with local erase-char, erase-line, erase-word
+    editing, forwardmask flushing, and TRAPSIG IAC command generation. The default 'telsh' server
+    was also updated to support linemode.
+
 3.0.2
   * bugfix: :meth:`~telnetlib3.stream_writer.TelnetWriter.request_charset` raised :exc:`TypeError`,
     :ghissue:`128`.  Offer callbacks (no-arg, returning a list of items to propose) are now

{telnetlib3-3.0.2 → telnetlib3-3.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "telnetlib3"
-version = "3.0.2"  # Keep in sync with telnetlib3/accessories.py::get_version !
+version = "3.0.3"  # Keep in sync with telnetlib3/accessories.py::get_version !
 description = " Python Telnet server and client CLI and Protocol library"
 readme = "README.rst"
 license = "ISC"

{telnetlib3-3.0.2 → telnetlib3-3.0.3}/telnetlib3/accessories.py

@@ -42,7 +42,7 @@ PATIENCE_MESSAGES = [
 
 def get_version() -> str:
     """Return the current version of telnetlib3."""
-    return "3.0.2"  # keep in sync with pyproject.toml !
+    return "3.0.3"  # keep in sync with pyproject.toml !
 
 
 def encoding_from_lang(lang: str) -> Optional[str]:
@@ -130,7 +130,11 @@ _DEFAULT_LOGFMT = " ".join(
 
 
 def make_logger(
-    name: str, loglevel: str = "info", logfile: Optional[str] = None, logfmt: str = _DEFAULT_LOGFMT
+    name: str,
+    loglevel: str = "info",
+    logfile: Optional[str] = None,
+    logfmt: str = _DEFAULT_LOGFMT,
+    filemode: str = "a",
 ) -> logging.Logger:
     """Create and return simple logger for given arguments."""
     lvl = getattr(logging, loglevel.upper(), None)
@@ -140,6 +144,7 @@ def make_logger(
     _cfg: Dict[str, Any] = {"format": logfmt}
     if logfile:
         _cfg["filename"] = logfile
+        _cfg["filemode"] = filemode
     logging.basicConfig(**_cfg)
     for handler in logging.getLogger().handlers:
         if isinstance(handler, logging.StreamHandler) and not isinstance(

{telnetlib3-3.0.2 → telnetlib3-3.0.3}/telnetlib3/client.py

@@ -645,7 +645,11 @@ async def run_client() -> None:
     config_msg = f"Client configuration: {accessories.repr_mapping(args)}"
 
     log = accessories.make_logger(
-        name=__name__, loglevel=args["loglevel"], logfile=args["logfile"], logfmt=args["logfmt"]
+        name=__name__,
+        loglevel=args["loglevel"],
+        logfile=args["logfile"],
+        logfmt=args["logfmt"],
+        filemode="w" if args.get("logfile_mode") == "rewrite" else "a",
     )
     log.debug(config_msg)
 
@@ -774,7 +778,11 @@ async def run_client() -> None:
         ) -> None:
             ctx = writer_arg.ctx
             assert typescript_path is not None
-            ts_file = open(typescript_path, "a", encoding="utf-8")  # noqa: SIM115
+            ts_file = open(  # noqa: SIM115
+                typescript_path,
+                "w" if args.get("typescript_mode") == "rewrite" else "a",
+                encoding="utf-8",
+            )
             ctx.typescript_file = ts_file
             try:
                 await _ts_inner(reader, writer_arg)
@@ -819,6 +827,13 @@ def _get_argument_parser() -> argparse.ArgumentParser:
     parser.add_argument("--loglevel", default="warn", help="log level")
     parser.add_argument("--logfmt", default=accessories._DEFAULT_LOGFMT, help="log format")
     parser.add_argument("--logfile", help="filepath")
+    parser.add_argument(
+        "--logfile-mode",
+        default="append",
+        choices=["append", "rewrite"],
+        dest="logfile_mode",
+        help="Log file write mode: append (default) or rewrite.",
+    )
     parser.add_argument(
         "--shell", default="telnetlib3.telnet_client_shell", help="module.function_name"
     )
@@ -972,6 +987,13 @@ def _get_argument_parser() -> argparse.ArgumentParser:
         metavar="FILE",
         help="record session to FILE (like Unix script(1))",
     )
+    parser.add_argument(
+        "--typescript-mode",
+        default="append",
+        choices=["append", "rewrite"],
+        dest="typescript_mode",
+        help="Typescript write mode: append (default) or rewrite.",
+    )
     return parser
 
 
@@ -1040,6 +1062,7 @@ def _transform_args(args: argparse.Namespace) -> Dict[str, Any]:
         "port": args.port,
         "loglevel": args.loglevel,
         "logfile": args.logfile,
+        "logfile_mode": args.logfile_mode,
         "logfmt": args.logfmt,
         "encoding": args.encoding,
         "tspeed": (args.speed, args.speed),
@@ -1068,6 +1091,7 @@ def _transform_args(args: argparse.Namespace) -> Dict[str, Any]:
         ),
         "compression": args.compression,
         "typescript": args.typescript,
+        "typescript_mode": args.typescript_mode,
     }
 
 

{telnetlib3-3.0.2 → telnetlib3-3.0.3}/telnetlib3/client_shell.py

@@ -10,12 +10,14 @@ from typing import Any, Dict, Tuple, Union, Callable, Optional
 from dataclasses import dataclass
 
 # local
+from . import slc as slc_module
 from . import accessories
 from ._session_context import TelnetSessionContext
 
 log = logging.getLogger(__name__)
 
 # local
+from .telopt import LINEMODE  # noqa: E402
 from .accessories import TRACE  # noqa: E402
 from .stream_reader import TelnetReader, TelnetReaderUnicode  # noqa: E402
 from .stream_writer import TelnetWriter, TelnetWriterUnicode  # noqa: E402
@@ -180,6 +182,93 @@ class _RawLoopState:
     reactivate_repl: bool = False
 
 
+class LinemodeBuffer:
+    """
+    Client-side line buffer for LINEMODE EDIT mode (RFC 1184 §3.1).
+
+    Accumulates characters typed by the user, applying local SLC editing functions (erase-char,
+    erase-line, erase-word) and transmitting complete lines to the server.  When TRAPSIG is enabled,
+    signal characters (^C etc.) are sent as IAC commands instead of buffered.
+
+    :param slctab: The writer's current SLC character table.
+    :param forwardmask: FORWARDMASK received from server, or None.
+    :param trapsig: When True, signal characters are sent as IAC commands.
+    """
+
+    def __init__(
+        self,
+        slctab: Dict[bytes, slc_module.SLC],
+        forwardmask: Optional[slc_module.Forwardmask] = None,
+        trapsig: bool = False,
+    ) -> None:
+        """Initialize LinemodeBuffer."""
+        from .telopt import IP, AYT, BRK, EOF, IAC, SUSP, ABORT
+
+        self._buf: list[str] = []
+        self.slctab = slctab
+        self.forwardmask = forwardmask
+        self.trapsig = trapsig
+        self._trapsig_map: Dict[bytes, bytes] = {
+            slc_module.SLC_IP: IAC + IP,
+            slc_module.SLC_ABORT: IAC + ABORT,
+            slc_module.SLC_SUSP: IAC + SUSP,
+            slc_module.SLC_EOF: IAC + EOF,
+            slc_module.SLC_BRK: IAC + BRK,
+            slc_module.SLC_AYT: IAC + AYT,
+        }
+
+    def _slc_val(self, func: bytes) -> Optional[int]:
+        """Return the active byte value for SLC function, or None if unsupported."""
+        defn = self.slctab.get(func)
+        if defn is None or defn.nosupport:
+            return None
+        v = defn.val
+        return ord(v) if v and v != slc_module.theNULL else None
+
+    def feed(self, char: str) -> Tuple[str, Optional[bytes]]:
+        """
+        Feed one character into the buffer.
+
+        :returns: ``(echo, data)`` where ``echo`` is text to display locally
+            (may be empty) and ``data`` is bytes to send to server, or None
+            if buffering.
+        """
+        b = ord(char)
+        if self.trapsig:
+            for func, cmd in self._trapsig_map.items():
+                if b == self._slc_val(func):
+                    return ("", cmd)
+        if b == self._slc_val(slc_module.SLC_EC):
+            if self._buf:
+                self._buf.pop()
+                return ("\b \b", None)
+            return ("", None)
+        if b == self._slc_val(slc_module.SLC_EL):
+            n = len(self._buf)
+            self._buf.clear()
+            return ("\b \b" * n, None)
+        if b == self._slc_val(slc_module.SLC_EW):
+            popped = 0
+            # skip trailing spaces (POSIX VWERASE behaviour)
+            while self._buf and self._buf[-1] == " ":
+                self._buf.pop()
+                popped += 1
+            while self._buf and self._buf[-1] != " ":
+                self._buf.pop()
+                popped += 1
+            return ("\b \b" * popped, None)
+        if char in ("\r", "\n"):
+            line = "".join(self._buf) + char
+            self._buf.clear()
+            return (char, line.encode())
+        if self.forwardmask is not None and b in self.forwardmask:
+            data = ("".join(self._buf) + char).encode()
+            self._buf.clear()
+            return (char, data)
+        self._buf.append(char)
+        return (char, None)
+
+
 if sys.platform == "win32":
 
     async def telnet_client_shell(
@@ -310,10 +399,11 @@ else:
             )
 
         def _server_will_sga(self) -> bool:
-            """Whether server has negotiated WILL SGA."""
+            """Whether SGA has been negotiated (either direction)."""
             from .telopt import SGA
 
-            return bool(self.telnet_writer.client and self.telnet_writer.remote_option.enabled(SGA))
+            w = self.telnet_writer
+            return bool(w.client and (w.remote_option.enabled(SGA) or w.local_option.enabled(SGA)))
 
         def check_auto_mode(
             self, switched_to_raw: bool, last_will_echo: bool
@@ -330,6 +420,20 @@ else:
                 return None
             wecho = self.telnet_writer.will_echo
             wsga = self._server_will_sga()
+            # LINEMODE EDIT: kernel must handle line editing; keep/restore cooked mode.
+            # This takes priority over the SGA/ECHO raw-mode heuristics below.
+            if (
+                self.telnet_writer.local_option.enabled(LINEMODE)
+                and self.telnet_writer.linemode.edit
+            ):
+                if switched_to_raw:
+                    assert self._save_mode is not None
+                    self.set_mode(self._save_mode)
+                    self.telnet_writer.log.debug(
+                        "auto: LINEMODE EDIT confirmed, restoring cooked mode"
+                    )
+                    return (False, wecho, False)
+                return None
             # WILL ECHO alone = line mode with server echo (suppress local echo)
             # WILL SGA (with or without ECHO) = raw/character-at-a-time
             should_go_raw = not switched_to_raw and wsga
@@ -362,20 +466,35 @@ else:
 
             Auto mode (``_raw_mode is None``): follows the server's negotiation.
 
-            =================  ========  ==========  ================================
+            =================  ========  ==========  ========================================
             Server negotiates  ICANON    ECHO        Behavior
-            =================  ========  ==========  ================================
+            =================  ========  ==========  ========================================
             Nothing            on        on          Line mode, local echo
+            LINEMODE EDIT      **on**    on          Cooked mode, kernel handles EC/EL/echo
+            LINEMODE remote    **off**   **off**     Raw, server echoes
             WILL SGA only      **off**   on          Character-at-a-time, local echo
             WILL ECHO only     on        **off**     Line mode, server echoes
             WILL SGA + ECHO    **off**   **off**     Full kludge mode (most common)
-            =================  ========  ==========  ================================
+            =================  ========  ==========  ========================================
             """
             raw_mode = _get_raw_mode(self.telnet_writer)
             will_echo = self.telnet_writer.will_echo
             will_sga = self._server_will_sga()
             # Auto mode (None): follow server negotiation
             if raw_mode is None:
+                if self.telnet_writer.local_option.enabled(LINEMODE):
+                    linemode_mode = self.telnet_writer.linemode
+                    if linemode_mode.edit:
+                        # RFC 1184 / NetBSD reference: LINEMODE EDIT means ICANON on.
+                        # The kernel line discipline handles EC (VERASE), EL (VKILL),
+                        # EW (VWERASE), and echo.  No software line editing needed.
+                        self.telnet_writer.log.debug(
+                            "auto: LINEMODE EDIT, cooked mode (kernel line editing)"
+                        )
+                        self.software_echo = False
+                        return mode  # keep ICANON on; kernel handles EC/EL/EW and echo
+                    self.telnet_writer.log.debug("auto: LINEMODE remote, raw input server echo")
+                    return self._make_raw(mode, suppress_echo=True)
                 if will_echo and will_sga:
                     self.telnet_writer.log.debug("auto: server echo + SGA, kludge mode")
                     return self._make_raw(mode)
@@ -531,6 +650,18 @@ else:
         """Return the autoreply engine from the writer's context, if set."""
         return telnet_writer.ctx.autoreply_engine
 
+    def _get_linemode_buffer(writer: Union[TelnetWriter, TelnetWriterUnicode]) -> "LinemodeBuffer":
+        """Return (or lazily create) the LinemodeBuffer attached to *writer*."""
+        buf: Optional[LinemodeBuffer] = getattr(writer, "_linemode_buf", None)
+        if buf is None:
+            buf = LinemodeBuffer(
+                slctab=writer.slctab,
+                forwardmask=writer.forwardmask,
+                trapsig=writer.linemode.trapsig,
+            )
+            writer._linemode_buf = buf
+        return buf
+
     async def _raw_event_loop(
         telnet_reader: Union[TelnetReader, TelnetReaderUnicode],
         telnet_writer: Union[TelnetWriter, TelnetWriterUnicode],
@@ -589,7 +720,26 @@ else:
                         wait_for.remove(telnet_task)
                     handle_close("Connection closed.")
                     break
-                new_timer, has_pending = _send_stdin(inp, telnet_writer, stdout, state.local_echo)
+                linemode_edit = (
+                    telnet_writer.local_option.enabled(LINEMODE) and telnet_writer.linemode.edit
+                )
+                if linemode_edit and state.switched_to_raw:
+                    # Raw PTY or non-TTY: kernel not doing line editing, use LinemodeBuffer
+                    lmbuf = _get_linemode_buffer(telnet_writer)
+                    for ch in inp.decode(errors="replace"):
+                        echo, data = lmbuf.feed(ch)
+                        if echo:
+                            stdout.write(echo.encode())
+                        if data:
+                            telnet_writer._write(data)
+                    new_timer, has_pending = None, False
+                elif linemode_edit:
+                    # Cooked PTY: kernel already handled EC/EL/echo; forward line directly
+                    new_timer, has_pending = _send_stdin(inp, telnet_writer, stdout, False)
+                else:
+                    new_timer, has_pending = _send_stdin(
+                        inp, telnet_writer, stdout, state.local_echo
+                    )
                 if has_pending and esc_timer_task not in wait_for:
                     esc_timer_task = new_timer
                     if esc_timer_task is not None:

{telnetlib3-3.0.2 → telnetlib3-3.0.3}/telnetlib3/server.py

@@ -42,7 +42,14 @@ try:
 except ImportError:
     PTY_SUPPORT = False
 
-__all__ = ("TelnetServer", "Server", "create_server", "run_server", "parse_server_args")
+__all__ = (
+    "TelnetServer",
+    "LinemodeServer",
+    "Server",
+    "create_server",
+    "run_server",
+    "parse_server_args",
+)
 
 
 class CONFIG(NamedTuple):
@@ -806,6 +813,42 @@ class _TLSAutoDetectProtocol(asyncio.Protocol):
         _ = exc
 
 
+class LinemodeServer(TelnetServer):
+    """
+    :class:`TelnetServer` subclass that negotiates LINEMODE EDIT.
+
+    In addition to the standard options negotiated by :class:`TelnetServer`,
+    this server sends ``DO LINEMODE`` during advanced negotiation, proposes
+    LINEMODE EDIT (local line editing by the client), and suppresses
+    ``WILL ECHO`` so the client performs local echoing via its LINEMODE buffer.
+
+    Use with :func:`create_server` to enable RFC 1184 LINEMODE EDIT on a
+    :func:`~.telnet_server_shell` session or any custom shell.
+    """
+
+    from . import slc as _slc_module
+
+    #: Propose LINEMODE EDIT (local line editing) instead of remote mode.
+    default_linemode = _slc_module.Linemode(_slc_module.LMODE_MODE_LOCAL)
+
+    def begin_advanced_negotiation(self) -> None:
+        """Negotiate standard options plus ``DO LINEMODE``."""
+        from .telopt import DO, LINEMODE
+
+        super().begin_advanced_negotiation()
+        # Propagate the protocol-level default_linemode to the writer so that
+        # TelnetWriter.handle_will(LINEMODE) proposes the correct mode (LOCAL/EDIT)
+        # rather than the TelnetWriter class default (REMOTE).
+        self.writer.default_linemode = self.default_linemode
+        self.writer.iac(DO, LINEMODE)
+
+    def _negotiate_echo(self) -> None:
+        """Skip ``WILL ECHO`` — LINEMODE EDIT client handles local echo."""
+        if self._echo_negotiated:
+            return
+        self._echo_negotiated = True
+
+
 class Server:
     """
     Telnet server that tracks connected clients.

{telnetlib3-3.0.2 → telnetlib3-3.0.3}/telnetlib3/server_shell.py

@@ -137,7 +137,14 @@ class _LineEditor:
         return char, None
 
 
-__all__ = ("telnet_server_shell", "readline_async", "readline")
+__all__ = (
+    "telnet_server_shell",
+    "readline_async",
+    "readline",
+    "get_linemode",
+    "get_slcdata",
+    "do_toggle",
+)
 
 
 async def telnet_server_shell(
@@ -179,7 +186,7 @@ async def telnet_server_shell(
             writer.write("Goodbye." + CR + LF)
             break
         if command == "help":
-            writer.write("quit, writer, slc, toggle [option|all], reader, proto, dump")
+            writer.write("quit, writer, slc, linemode, toggle [option|all], reader, proto, dump")
         elif command == "writer":
             # show 'writer' status
             writer.write(repr(writer))
@@ -194,6 +201,8 @@ async def telnet_server_shell(
         elif command == "slc":
             # show 'slc' support and data tables
             writer.write(get_slcdata(writer))
+        elif command == "linemode":
+            writer.write(get_linemode(writer))
         elif command.startswith("toggle"):
             # toggle specified options
             option = command[len("toggle ") :] or None
@@ -342,8 +351,25 @@ def get_slcdata(writer: Union[TelnetWriter, TelnetWriterUnicode]) -> str:
     )
 
 
+def get_linemode(writer: Union[TelnetWriter, TelnetWriterUnicode]) -> str:
+    """Display current LINEMODE negotiation state."""
+    active = writer.remote_option.enabled(telopt.LINEMODE)
+    if not active:
+        return "LINEMODE not negotiated."
+    lm = writer.linemode
+    bits = (
+        f"EDIT={'on' if lm.edit else 'off'}"
+        f" TRAPSIG={'on' if lm.trapsig else 'off'}"
+        f" SOFT_TAB={'on' if lm.soft_tab else 'off'}"
+        f" LIT_ECHO={'on' if lm.lit_echo else 'off'}"
+        f" ACK={'on' if lm.ack else 'off'}"
+    )
+    return f"LINEMODE active. Mode: {writer.mode}\r\n{bits}"
+
+
 def do_toggle(writer: Union[TelnetWriter, TelnetWriterUnicode], option: Optional[str]) -> str:
     """Display or toggle telnet session parameters."""
+    linemode_active = writer.remote_option.enabled(telopt.LINEMODE)
     tbl_opt = {
         "echo": writer.local_option.enabled(telopt.ECHO),
         "goahead": not writer.local_option.enabled(telopt.SGA),
@@ -352,6 +378,9 @@ def do_toggle(writer: Union[TelnetWriter, TelnetWriterUnicode], option: Optional
         "binary": writer.outbinary and writer.inbinary,
         "xon-any": writer.xon_any,
         "lflow": writer.lflow,
+        "linemode": linemode_active,
+        "linemode-edit": writer.linemode.edit if linemode_active else False,
+        "linemode-trapsig": writer.linemode.trapsig if linemode_active else False,
     }
 
     if not option:
@@ -390,6 +419,25 @@ def do_toggle(writer: Union[TelnetWriter, TelnetWriterUnicode], option: Optional
         writer.send_lineflow_mode()
         msgs.append(f"lineflow {'en' if writer.lflow else 'dis'}abled.")
 
+    if option in ("linemode",):
+        cmd = telopt.DONT if tbl_opt["linemode"] else telopt.DO
+        writer.iac(cmd, telopt.LINEMODE)
+        msgs.append(f"{telopt.name_command(cmd).lower()} linemode.")
+
+    if option in ("linemode-edit",):
+        if not tbl_opt["linemode"]:
+            msgs.append("linemode not active.")
+        else:
+            writer.request_linemode_change(edit=not tbl_opt["linemode-edit"])
+            msgs.append(f"linemode-edit {'dis' if tbl_opt['linemode-edit'] else 'en'}abled.")
+
+    if option in ("linemode-trapsig",):
+        if not tbl_opt["linemode"]:
+            msgs.append("linemode not active.")
+        else:
+            writer.request_linemode_change(trapsig=not tbl_opt["linemode-trapsig"])
+            msgs.append(f"linemode-trapsig {'dis' if tbl_opt['linemode-trapsig'] else 'en'}abled.")
+
     if option not in tbl_opt and option != "all":
         msgs.append("toggle: not an option.")
 

{telnetlib3-3.0.2 → telnetlib3-3.0.3}/telnetlib3/slc.py

@@ -17,6 +17,7 @@ __all__ = (
     "Linemode",
     "LMODE_FORWARDMASK",
     "LMODE_MODE",
+    "LMODE_MODE_EDIT",
     "LMODE_MODE_REMOTE",
     "LMODE_SLC",
     "name_slc_command",
@@ -89,6 +90,9 @@ LMODE_MODE, LMODE_FORWARDMASK, LMODE_SLC = (bytes([const]) for const in range(1,
 LMODE_MODE_REMOTE, LMODE_MODE_LOCAL, LMODE_MODE_TRAPSIG = (bytes([const]) for const in range(3))
 LMODE_MODE_ACK, LMODE_MODE_SOFT_TAB, LMODE_MODE_LIT_ECHO = (bytes([4]), bytes([8]), bytes([16]))
 
+#: RFC 1184's name for LMODE_MODE_LOCAL (EDIT bit)
+LMODE_MODE_EDIT = LMODE_MODE_LOCAL
+
 
 class SLC:
     """Defines the willingness to support a Special Linemode Character."""
@@ -315,6 +319,15 @@ class Linemode:
         """True if linemode is local."""
         return bool(ord(self.mask) & ord(LMODE_MODE_LOCAL))
 
+    @property
+    def edit(self) -> bool:
+        """
+        True if EDIT bit set (client performs local line editing).
+
+        RFC 1184 name.
+        """
+        return self.local
+
     @property
     def remote(self) -> bool:
         """True if linemode is remote."""