cmd2 4.3.1__tar.gz → 4.4.0__tar.gz

{cmd2-4.3.1 → cmd2-4.4.0}/.pre-commit-config.yaml

@@ -15,7 +15,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.17.1"
+    rev: "v0.17.3"
     hooks:
       - id: ruff-format
         args: [--config=ruff.toml]

{cmd2-4.3.1 → cmd2-4.4.0}/CHANGELOG.md

@@ -1,3 +1,62 @@
+## 4.4.0 (October 31, 2026) 🎃
+
+- Breaking Changes
+    - `set_window_title()` is now an instance method. Call `app.set_window_title(title)` or
+      `self.set_window_title(title)` so title changes use that application's terminal.
+    - `History.get()` and `History.span()` now raise `HistoryIndexError`, an `IndexError` subclass,
+      for invalid indices and bounded ranges selecting no history items. Unbounded ranges (`:` and
+      `..`) can still return an empty dictionary. Starts before the beginning of history are
+      rejected rather than clamped. Malformed ranges, including zero endpoints, raise
+      `HistoryFormatError`, a `ValueError` subclass. The `history` command reports these selection
+      errors without a traceback hint, and index zero includes the reminder that the first command
+      is command 1.
+    - End-only ranges now start at command 1 in the full history, including persisted commands, just
+      like explicit-start ranges and single indices. Bare `history` and unbounded ranges still
+      select only the current session unless `--all` is supplied.
+    - Replaying or editing a selection containing persisted commands now requires `--all`. This
+      includes single indices and bounded ranges. Displaying or saving these selections does not
+      require `--all`, and command numbers are unchanged.
+    - Running, editing, or saving an empty history selection now fails before replay, opening an
+      editor, or creating or overwriting a file. This includes `history -o FILE` and `history -e`
+      with no selector in an empty session, and actions on searches with no matches. Empty unbounded
+      selections report `No history items in range`, while search misses report
+      `No matching history items`; displaying them still succeeds without output. The no-argument
+      `history --run` safety refusal is unchanged.
+    - `History` now records which entries were loaded before the session started instead of keeping
+      a plain start index. Entries added after `start_session()` belong to the current session
+      wherever they are placed, including entries inserted at the front of the history.
+      `session_start_index` is now computed as the index just past the last persisted entry.
+      Assigning it marks only the entries already in the list, so assign it or call
+      `start_session()` after loading entries. After the list is reordered,
+      `history[history.session_start_index:]` can omit current-session entries; use
+      `History.is_persisted()` to check an entry instead.
+- Bug Fixes
+    - Fixed history ranges starting past the end selecting the last command. Invalid indices and
+      bounded ranges selecting no items report `No history items in range` before running, editing,
+      or saving commands.
+    - Negative single-index history selections now display and return the positive command number.
+    - History regular expressions containing range separators are now handled as regex searches.
+      Other selectors are treated as numbers or ranges only when they match the supported syntax;
+      strings such as URLs, `a:b`, `+1`, and `1_0` remain literal searches.
+    - Fixed `History.truncate()` leaving the current session's start index unchanged. Code calling
+      it directly would then have retained current-session entries hidden from unbounded ranges and
+      searches. Interactive `history` use was unaffected, since `cmd2` only truncates when
+      persisting history at exit.
+    - Fixed changing a `History` list in place moving commands between the persisted history and the
+      current session. Deleting, inserting, assigning, reordering (such as `reverse()` and
+      `sort()`), or repeating entries no longer shows persisted commands as current or hides
+      current-session commands, and `history --run` and `history --edit` still require `--all` for a
+      moved persisted command. Equal commands from different sessions remain separate entries.
+    - Fixed `set_window_title()` leaving title changes buffered until the next prompt render. The
+      title is now flushed before the method returns when no prompt is running. While a prompt or
+      `select()` menu is running, it is written on that prompt's event loop so it doesn't interleave
+      with rendering, and output errors are ignored so they can't disrupt the prompt. Titles are
+      still written to a terminal stdout when prompts use a dummy output, such as when stdin isn't a
+      terminal.
+- Enhancements
+    - Added `History.is_persisted()` to check whether a history entry was loaded from a previous
+      session.
+
 ## 4.3.1 (October 24, 2026)
 
 - Bug Fixes

{cmd2-4.3.1 → cmd2-4.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmd2
-Version: 4.3.1
+Version: 4.4.0
 Summary: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python
 Author: cmd2 Contributors
 License-Expression: MIT

{cmd2-4.3.1 → cmd2-4.4.0}/cmd2/cmd2.py

@@ -29,6 +29,7 @@ Documentation: https://cmd2.readthedocs.io/
 # import this module, many of these imports are lazy-loaded
 # i.e. we only import the module when we use it.
 import argparse
+import asyncio
 import contextlib
 import copy
 import dataclasses
@@ -71,7 +72,7 @@ from prompt_toolkit import (
     filters,
     print_formatted_text,
 )
-from prompt_toolkit.application import create_app_session, get_app
+from prompt_toolkit.application import Application, AppSession, create_app_session, get_app
 from prompt_toolkit.auto_suggest import AutoSuggestFromHistory
 from prompt_toolkit.completion import Completer, DummyCompleter
 from prompt_toolkit.formatted_text import ANSI, AnyFormattedText
@@ -82,9 +83,9 @@ from prompt_toolkit.key_binding.key_processor import KeyPress, KeyPressEvent
 from prompt_toolkit.keys import Keys
 from prompt_toolkit.layout import Window, walk
 from prompt_toolkit.layout.containers import ConditionalContainer, FloatContainer
-from prompt_toolkit.output import DummyOutput, create_output
+from prompt_toolkit.output import DummyOutput, Output, create_output
 from prompt_toolkit.patch_stdout import patch_stdout
-from prompt_toolkit.shortcuts import CompleteStyle, PromptSession, choice, set_title
+from prompt_toolkit.shortcuts import CompleteStyle, PromptSession, choice
 from prompt_toolkit.styles import DynamicStyle
 from rich.console import (
     Group,
@@ -153,7 +154,11 @@ from .exceptions import (
     SkipPostcommandHooks,
 )
 from .history import (
+    NO_HISTORY_ITEMS,
+    NO_MATCHING_HISTORY_ITEMS,
     History,
+    HistoryFormatError,
+    HistoryIndexError,
     HistoryItem,
 )
 from .parsing import (
@@ -216,6 +221,11 @@ if TYPE_CHECKING:  # pragma: no cover
     from prompt_toolkit.buffer import Buffer
 
 
+# Errors raised when prompt-toolkit can't use a terminal. For example, GitHub Actions on Windows reports
+# isatty() as True but has no real console.
+_TERMINAL_INIT_ERRORS = (NoConsoleScreenBufferError, AttributeError, ValueError)
+
+
 class _SavedCmd2Env:
     """cmd2 environment settings that are backed up when entering an interactive Python shell."""
 
@@ -685,6 +695,26 @@ class Cmd:
         self._alert_thread: threading.Thread | None = None
         self._alert_prompt_timestamp: float = 0.0  # Uses time.monotonic()
 
+        # Members related to setting the window title. The lock is reentrant so a signal handler which sets the title
+        # while the main thread is writing one doesn't deadlock. Such a nested call only records its title, and the
+        # outer call writes it next.
+        self._window_title_lock = threading.RLock()
+        self._pending_window_title: str | None = None
+        self._writing_window_title = False
+
+        # The prompt loop on which a title callback is queued but hasn't run yet. Later titles set while it's queued
+        # only replace the pending title, which that callback writes.
+        self._window_title_callback_loop: asyncio.AbstractEventLoop | None = None
+
+        # The stdout this app was created with. When the main session uses a DummyOutput, titles are written to it if
+        # it's a terminal, including while a command's output is redirected. See _get_window_title_fallback_output().
+        self._window_title_stdout: TextIO = self.stdout
+        self._window_title_fallback_checked = False
+        self._window_title_fallback_output: Output | None = None
+
+        # The AppSession of a select() menu while it is displayed, so window titles can find its event loop.
+        self._select_app_session: AppSession | None = None
+
         # Add functions decorated to be subcommands
         self._register_subcommands(self)
 
@@ -834,7 +864,7 @@ class Cmd:
                     kwargs["output"] = create_output(stdout=self.stdout)
                 return PromptSession(**kwargs)
 
-            except (NoConsoleScreenBufferError, AttributeError, ValueError):
+            except _TERMINAL_INIT_ERRORS:
                 # Fallback to dummy input/output if PromptSession initialization fails.
                 # This can happen in some CI environments (like GitHub Actions on Windows)
                 # where isatty() is True but there is no real console.
@@ -3655,14 +3685,19 @@ class Cmd:
             if not callable(prompt):
                 prompt = pt_filter_style(prompt)
 
-            with patch_stdout():
-                try:
-                    # Set this session as the active one for UI/completion logic.
-                    self.active_session = session
-                    return session.prompt(prompt, **prompt_kwargs)
-                finally:
-                    # Revert back to the main session.
-                    self.active_session = self.main_session
+            try:
+                with patch_stdout():
+                    try:
+                        # Set this session as the active one for UI/completion logic.
+                        self.active_session = session
+                        return session.prompt(prompt, **prompt_kwargs)
+                    finally:
+                        # Revert back to the main session.
+                        self.active_session = self.main_session
+            finally:
+                # Write any title whose callback the prompt's event loop didn't run. Do this after patch_stdout()
+                # exits so the write can't race with its writer thread on the same output.
+                self._flush_pending_window_title_quietly()
 
         # We're not at a terminal, so we're likely reading from a file or a pipe.
         prompt_obj = prompt if isinstance(prompt, (ANSI, str)) else prompt()
@@ -4790,8 +4825,13 @@ class Cmd:
         if self._is_tty_session(self.main_session):
             try:
                 while True:
-                    with create_app_session(input=self.main_session.input, output=self.main_session.output):
-                        result = choice(message=prompt, options=fulloptions)
+                    with create_app_session(input=self.main_session.input, output=self.main_session.output) as app_session:
+                        self._select_app_session = app_session
+                        try:
+                            result = choice(message=prompt, options=fulloptions)
+                        finally:
+                            self._select_app_session = None
+                            self._flush_pending_window_title_quietly()
                     if result is not None:
                         return result
             except KeyboardInterrupt:
@@ -5446,13 +5486,14 @@ class Cmd:
             "-a",
             "--all",
             action="store_true",
-            help="display all commands, including ones persisted from previous sessions",
+            help="include persisted commands; required to run or edit commands from previous sessions",
         )
 
         history_arg_help = (
-            "empty               all history items\n"
-            "a                   one history item by number\n"
-            "a..b, a:b, a:, ..b  items by indices (inclusive)\n"
+            "empty               current session (--all includes persisted commands)\n"
+            "a                   one item by number in the full history\n"
+            "a..b, a:b, a:, ..b  inclusive ranges in the full history\n"
+            ":, ..               current session (--all includes persisted commands)\n"
             "string              items containing string\n"
             "/regex/             items matching regular expression"
         )
@@ -5498,18 +5539,33 @@ class Cmd:
 
             return None
 
+        if args.run and not args.arg:
+            self.perror("Cowardly refusing to run all previously entered commands.")
+            self.perror("If this is what you want to do, specify '1:' as the range of history.")
+            return None
+
         # If an argument was supplied, then retrieve partial contents of the history, otherwise retrieve it all
-        history = self._get_history(args)
+        try:
+            history = self._get_history(args)
+        except (HistoryIndexError, HistoryFormatError) as ex:
+            self.perror(str(ex))
+            return None
+
+        # Selection is independent of the requested action. Empty displays are harmless.
+        if not history and (args.run or args.edit or args.output_file):
+            is_search = args.arg and not self.history.spanpattern.fullmatch(args.arg)
+            self.perror(NO_MATCHING_HISTORY_ITEMS if is_search else NO_HISTORY_ITEMS)
+            return None
+
+        if (args.run or args.edit) and not args.all and any(self.history.is_persisted(item) for item in history.values()):
+            self.perror("Use --all to run or edit commands from previous sessions.")
+            return None
 
         if args.run:
-            if not args.arg:
-                self.perror("Cowardly refusing to run all previously entered commands.")
-                self.perror("If this is what you want to do, specify '1:' as the range of history.")
-            else:
-                stop = self.runcmds_plus_hooks(list(history.values()))
-                self.last_result = True
-                return stop
-        elif args.edit:
+            stop = self.runcmds_plus_hooks(list(history.values()))
+            self.last_result = True
+            return stop
+        if args.edit:
             fd, fname = tempfile.mkstemp(suffix=".txt", text=True)
             fobj: TextIO
             with os.fdopen(fd, "w") as fobj:
@@ -5550,26 +5606,28 @@ class Cmd:
     def _get_history(self, args: argparse.Namespace) -> dict[int, HistoryItem]:
         """If an argument was supplied, then retrieve partial contents of the history; otherwise retrieve entire history.
 
-        This function returns a dictionary with history items keyed by their 1-based index in ascending order.
+        This function returns a dictionary with history items keyed by their positive 1-based index in ascending order.
+        Index and range errors propagate to the caller. Empty selections return an empty dictionary.
         """
         if args.arg:
-            try:
-                int_arg = int(args.arg)
-                return {int_arg: self.history.get(int_arg)}
-            except ValueError:
-                pass
-
-            if ".." in args.arg or ":" in args.arg:
-                # Get a slice of history
-                history = self.history.span(args.arg, args.all)
-            elif args.arg.startswith(r"/") and args.arg.endswith(r"/"):
-                history = self.history.regex_search(args.arg, args.all)
-            else:
-                history = self.history.str_search(args.arg, args.all)
-        else:
-            # Get a copy of the history so it doesn't get mutated while we are using it
-            history = self.history.span(":", args.all)
-        return history
+            if args.arg.startswith(r"/") and args.arg.endswith(r"/"):
+                return self.history.regex_search(args.arg, args.all)
+            if re.fullmatch(r"-?[0-9]+", args.arg):
+                try:
+                    index = int(args.arg)
+                except ValueError:
+                    # Python may reject integer strings exceeding its conversion limit.
+                    raise HistoryIndexError(NO_HISTORY_ITEMS) from None
+                if index == 0:
+                    # Preserve the dedicated index-zero error and command-one reminder.
+                    self.history.get(index)
+                return self.history.span(f"{index}:{index}")
+            if self.history.spanpattern.fullmatch(args.arg):
+                return self.history.span(args.arg, args.all)
+            return self.history.str_search(args.arg, args.all)
+
+        # Get a copy of the history so it doesn't get mutated while we are using it.
+        return self.history.span(":", args.all)
 
     def _initialize_history(self, hist_file: str) -> None:
         """Initialize history using history related attributes.
@@ -5664,8 +5722,10 @@ class Cmd:
         except ModuleNotFoundError:  # pragma: no cover
             import bz2 as compress_lib  # type: ignore[no-redef]
 
-        self.history.truncate(self._persistent_history_length)
-        history_json = self.history.to_json()
+        # Truncate a copy so live history numbering and the session boundary are unchanged.
+        history = History(self.history)
+        history.truncate(self._persistent_history_length)
+        history_json = history.to_json()
         compressed_bytes = compress_lib.compress(history_json.encode(encoding="utf-8"))
 
         try:
@@ -5861,13 +5921,125 @@ class Cmd:
             self._alert_queue.append(alert)
             self._alert_condition.notify_all()
 
-    @staticmethod
-    def set_window_title(title: str) -> None:  # pragma: no cover
-        """Set the terminal window title.
+    def set_window_title(self, title: str) -> None:
+        """Set the title of this application's terminal.
+
+        The title is written to the output used by the main prompt, custom input prompts, and
+        select() menus. That is a dummy output when stdin or stdout isn't a terminal, or when the
+        terminal couldn't be set up. In that case, the title is written to the stdout this app was
+        created with instead, if that is a terminal. Otherwise, no title is written.
+
+        This can be called from any thread. If no prompt is running, then the title is written and
+        flushed before this returns, and output errors propagate to the caller. Such a direct write
+        from another thread isn't synchronized with other writers to the terminal, such as a prompt
+        which is just starting or finishing.
+
+        While a prompt is running, the title is written on the prompt's event loop, even when this is
+        called on that loop, so it doesn't interleave with rendering. It appears once the loop runs its
+        next callback, which can be delayed while the loop is busy, such as in a slow completer. If
+        several titles are set before then, only the latest is written. Output errors are ignored so
+        they can't disrupt the prompt.
 
         :param title: the new window title
         """
-        set_title(title)
+        with self._window_title_lock:
+            self._pending_window_title = title
+            loop = self._get_prompt_loop()
+            if loop is not None:
+                if self._window_title_callback_loop is loop:
+                    # A callback queued on this loop hasn't run yet, and it will write this title.
+                    return
+
+                try:
+                    loop.call_soon_threadsafe(self._flush_pending_window_title_quietly)
+                except RuntimeError:
+                    # The loop closed after we found it, so the prompt is no longer rendering.
+                    pass
+                else:
+                    # If the prompt finishes before the loop runs the callback, then the prompt's
+                    # cleanup writes the pending title.
+                    self._window_title_callback_loop = loop
+                    return
+
+            # Keep ownership until the direct write finishes, so another caller or prompt cleanup cannot consume
+            # this request and receive or suppress its output error.
+            self._flush_pending_window_title()
+
+    def _get_prompt_loop(self) -> asyncio.AbstractEventLoop | None:
+        """Return the event loop of the prompt-toolkit application drawing on this terminal, if one is running.
+
+        An application's loop is set for its whole run, including startup and teardown, when its is_running flag
+        is already cleared but the loop can still write to the terminal.
+        """
+        apps: list[Application[Any]] = [self.active_session.app]
+
+        # The main thread clears these when select() finishes, so read each one only once.
+        select_app_session = self._select_app_session
+        if select_app_session is not None:
+            select_app = select_app_session.app
+            if select_app is not None:
+                apps.append(select_app)
+
+        for app in apps:
+            loop = app.loop
+            if loop is not None:
+                return loop
+        return None
+
+    def _get_window_title_fallback_output(self) -> Output | None:
+        """Return an output for the stdout this app was created with, or None if that isn't a terminal.
+
+        Window titles use it when the main session has a DummyOutput. It's created the first time a title needs it.
+        This isn't a cached_property because inspect.getmembers() evaluates properties while this app is constructed.
+        """
+        if not self._window_title_fallback_checked:
+            self._window_title_fallback_checked = True
+
+            # A stream without isatty(), or a closed one, raises AttributeError or ValueError here.
+            with contextlib.suppress(*_TERMINAL_INIT_ERRORS):
+                if self._window_title_stdout.isatty():
+                    self._window_title_fallback_output = create_output(stdout=self._window_title_stdout)
+
+        return self._window_title_fallback_output
+
+    def _get_window_title_output(self) -> Output:
+        """Return the output which window titles are written to."""
+        output = self.main_session.output
+        if isinstance(output, DummyOutput) and (fallback := self._get_window_title_fallback_output()) is not None:
+            return fallback
+        return output
+
+    def _flush_pending_window_title(self) -> None:
+        """Write and flush the most recent title passed to set_window_title(), if it hasn't been written yet."""
+        with self._window_title_lock:
+            if self._writing_window_title:
+                # This thread is already writing a title, such as when a signal handler calls set_window_title().
+                # Writing now would nest inside that write, so leave the title pending for the outer call.
+                return
+
+            self._writing_window_title = True
+            try:
+                # Keep going until no newer title arrived during the last write, so the latest title always wins.
+                while (title := self._pending_window_title) is not None:
+                    self._pending_window_title = None
+                    output = self._get_window_title_output()
+                    output.set_title(title)
+                    output.flush()
+            finally:
+                self._writing_window_title = False
+
+    def _flush_pending_window_title_quietly(self) -> None:
+        """Flush a pending window title on a prompt's event loop or during its cleanup, ignoring output errors.
+
+        An error here would otherwise disrupt the prompt or replace its result. Writing to a closed stream raises
+        ValueError rather than OSError.
+        """
+        with self._window_title_lock:
+            # Either this is the queued callback, or the prompt finished and its loop won't run that callback.
+            # Either way, the next title set during a prompt needs a new callback.
+            self._window_title_callback_loop = None
+            with contextlib.suppress(OSError, ValueError):
+                self._flush_pending_window_title()
 
     def enable_command(self, command: str) -> None:
         """Enable a command by restoring its functions.