Add files using upload-large-folder tool

lib/python3.12/site-packages/prompt_toolkit/__init__.py

@@ -0,0 +1,54 @@
+"""
+prompt_toolkit
+==============
+
+Author: Jonathan Slenders
+
+Description: prompt_toolkit is a Library for building powerful interactive
+             command lines in Python.  It can be a replacement for GNU
+             Readline, but it can be much more than that.
+
+See the examples directory to learn about the usage.
+
+Probably, to get started, you might also want to have a look at
+`prompt_toolkit.shortcuts.prompt`.
+"""
+
+from __future__ import annotations
+
+import re
+from importlib import metadata
+
+# note: this is a bit more lax than the actual pep 440 to allow for a/b/rc/dev without a number
+pep440 = re.compile(
+    r"^([1-9]\d*!)?(0|[1-9]\d*)(\.(0|[1-9]\d*))*((a|b|rc)(0|[1-9]\d*)?)?(\.post(0|[1-9]\d*))?(\.dev(0|[1-9]\d*)?)?$",
+    re.UNICODE,
+)
+from .application import Application
+from .formatted_text import ANSI, HTML
+from .shortcuts import PromptSession, choice, print_formatted_text, prompt
+
+# Don't forget to update in `docs/conf.py`!
+__version__ = metadata.version("prompt_toolkit")
+
+assert pep440.match(__version__)
+
+# Version tuple.
+VERSION = tuple(int(v.rstrip("abrc")) for v in __version__.split(".")[:3])
+
+
+__all__ = [
+    # Application.
+    "Application",
+    # Shortcuts.
+    "prompt",
+    "choice",
+    "PromptSession",
+    "print_formatted_text",
+    # Formatted text.
+    "HTML",
+    "ANSI",
+    # Version info.
+    "__version__",
+    "VERSION",
+]

lib/python3.12/site-packages/prompt_toolkit/auto_suggest.py

@@ -0,0 +1,177 @@
+"""
+`Fish-style <http://fishshell.com/>`_  like auto-suggestion.
+
+While a user types input in a certain buffer, suggestions are generated
+(asynchronously.) Usually, they are displayed after the input. When the cursor
+presses the right arrow and the cursor is at the end of the input, the
+suggestion will be inserted.
+
+If you want the auto suggestions to be asynchronous (in a background thread),
+because they take too much time, and could potentially block the event loop,
+then wrap the :class:`.AutoSuggest` instance into a
+:class:`.ThreadedAutoSuggest`.
+"""
+
+from __future__ import annotations
+
+from abc import ABCMeta, abstractmethod
+from typing import TYPE_CHECKING, Callable
+
+from prompt_toolkit.eventloop import run_in_executor_with_context
+
+from .document import Document
+from .filters import Filter, to_filter
+
+if TYPE_CHECKING:
+    from .buffer import Buffer
+
+__all__ = [
+    "Suggestion",
+    "AutoSuggest",
+    "ThreadedAutoSuggest",
+    "DummyAutoSuggest",
+    "AutoSuggestFromHistory",
+    "ConditionalAutoSuggest",
+    "DynamicAutoSuggest",
+]
+
+
+class Suggestion:
+    """
+    Suggestion returned by an auto-suggest algorithm.
+
+    :param text: The suggestion text.
+    """
+
+    def __init__(self, text: str) -> None:
+        self.text = text
+
+    def __repr__(self) -> str:
+        return f"Suggestion({self.text})"
+
+
+class AutoSuggest(metaclass=ABCMeta):
+    """
+    Base class for auto suggestion implementations.
+    """
+
+    @abstractmethod
+    def get_suggestion(self, buffer: Buffer, document: Document) -> Suggestion | None:
+        """
+        Return `None` or a :class:`.Suggestion` instance.
+
+        We receive both :class:`~prompt_toolkit.buffer.Buffer` and
+        :class:`~prompt_toolkit.document.Document`. The reason is that auto
+        suggestions are retrieved asynchronously. (Like completions.) The
+        buffer text could be changed in the meantime, but ``document`` contains
+        the buffer document like it was at the start of the auto suggestion
+        call. So, from here, don't access ``buffer.text``, but use
+        ``document.text`` instead.
+
+        :param buffer: The :class:`~prompt_toolkit.buffer.Buffer` instance.
+        :param document: The :class:`~prompt_toolkit.document.Document` instance.
+        """
+
+    async def get_suggestion_async(
+        self, buff: Buffer, document: Document
+    ) -> Suggestion | None:
+        """
+        Return a :class:`.Future` which is set when the suggestions are ready.
+        This function can be overloaded in order to provide an asynchronous
+        implementation.
+        """
+        return self.get_suggestion(buff, document)
+
+
+class ThreadedAutoSuggest(AutoSuggest):
+    """
+    Wrapper that runs auto suggestions in a thread.
+    (Use this to prevent the user interface from becoming unresponsive if the
+    generation of suggestions takes too much time.)
+    """
+
+    def __init__(self, auto_suggest: AutoSuggest) -> None:
+        self.auto_suggest = auto_suggest
+
+    def get_suggestion(self, buff: Buffer, document: Document) -> Suggestion | None:
+        return self.auto_suggest.get_suggestion(buff, document)
+
+    async def get_suggestion_async(
+        self, buff: Buffer, document: Document
+    ) -> Suggestion | None:
+        """
+        Run the `get_suggestion` function in a thread.
+        """
+
+        def run_get_suggestion_thread() -> Suggestion | None:
+            return self.get_suggestion(buff, document)
+
+        return await run_in_executor_with_context(run_get_suggestion_thread)
+
+
+class DummyAutoSuggest(AutoSuggest):
+    """
+    AutoSuggest class that doesn't return any suggestion.
+    """
+
+    def get_suggestion(self, buffer: Buffer, document: Document) -> Suggestion | None:
+        return None  # No suggestion
+
+
+class AutoSuggestFromHistory(AutoSuggest):
+    """
+    Give suggestions based on the lines in the history.
+    """
+
+    def get_suggestion(self, buffer: Buffer, document: Document) -> Suggestion | None:
+        history = buffer.history
+
+        # Consider only the last line for the suggestion.
+        text = document.text.rsplit("\n", 1)[-1]
+
+        # Only create a suggestion when this is not an empty line.
+        if text.strip():
+            # Find first matching line in history.
+            for string in reversed(list(history.get_strings())):
+                for line in reversed(string.splitlines()):
+                    if line.startswith(text):
+                        return Suggestion(line[len(text) :])
+
+        return None
+
+
+class ConditionalAutoSuggest(AutoSuggest):
+    """
+    Auto suggest that can be turned on and of according to a certain condition.
+    """
+
+    def __init__(self, auto_suggest: AutoSuggest, filter: bool | Filter) -> None:
+        self.auto_suggest = auto_suggest
+        self.filter = to_filter(filter)
+
+    def get_suggestion(self, buffer: Buffer, document: Document) -> Suggestion | None:
+        if self.filter():
+            return self.auto_suggest.get_suggestion(buffer, document)
+
+        return None
+
+
+class DynamicAutoSuggest(AutoSuggest):
+    """
+    Validator class that can dynamically returns any Validator.
+
+    :param get_validator: Callable that returns a :class:`.Validator` instance.
+    """
+
+    def __init__(self, get_auto_suggest: Callable[[], AutoSuggest | None]) -> None:
+        self.get_auto_suggest = get_auto_suggest
+
+    def get_suggestion(self, buff: Buffer, document: Document) -> Suggestion | None:
+        auto_suggest = self.get_auto_suggest() or DummyAutoSuggest()
+        return auto_suggest.get_suggestion(buff, document)
+
+    async def get_suggestion_async(
+        self, buff: Buffer, document: Document
+    ) -> Suggestion | None:
+        auto_suggest = self.get_auto_suggest() or DummyAutoSuggest()
+        return await auto_suggest.get_suggestion_async(buff, document)

lib/python3.12/site-packages/prompt_toolkit/buffer.py

@@ -0,0 +1,2029 @@
+"""
+Data structures for the Buffer.
+It holds the text, cursor position, history, etc...
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import tempfile
+from collections import deque
+from enum import Enum
+from functools import wraps
+from typing import Any, Callable, Coroutine, Iterable, TypeVar, cast
+
+from .application.current import get_app
+from .application.run_in_terminal import run_in_terminal
+from .auto_suggest import AutoSuggest, Suggestion
+from .cache import FastDictCache
+from .clipboard import ClipboardData
+from .completion import (
+    CompleteEvent,
+    Completer,
+    Completion,
+    DummyCompleter,
+    get_common_complete_suffix,
+)
+from .document import Document
+from .eventloop import aclosing
+from .filters import FilterOrBool, to_filter
+from .history import History, InMemoryHistory
+from .search import SearchDirection, SearchState
+from .selection import PasteMode, SelectionState, SelectionType
+from .utils import Event, to_str
+from .validation import ValidationError, Validator
+
+__all__ = [
+    "EditReadOnlyBuffer",
+    "Buffer",
+    "CompletionState",
+    "indent",
+    "unindent",
+    "reshape_text",
+]
+
+logger = logging.getLogger(__name__)
+
+
+class EditReadOnlyBuffer(Exception):
+    "Attempt editing of read-only :class:`.Buffer`."
+
+
+class ValidationState(Enum):
+    "The validation state of a buffer. This is set after the validation."
+
+    VALID = "VALID"
+    INVALID = "INVALID"
+    UNKNOWN = "UNKNOWN"
+
+
+class CompletionState:
+    """
+    Immutable class that contains a completion state.
+    """
+
+    def __init__(
+        self,
+        original_document: Document,
+        completions: list[Completion] | None = None,
+        complete_index: int | None = None,
+    ) -> None:
+        #: Document as it was when the completion started.
+        self.original_document = original_document
+
+        #: List of all the current Completion instances which are possible at
+        #: this point.
+        self.completions = completions or []
+
+        #: Position in the `completions` array.
+        #: This can be `None` to indicate "no completion", the original text.
+        self.complete_index = complete_index  # Position in the `_completions` array.
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.original_document!r}, <{len(self.completions)!r}> completions, index={self.complete_index!r})"
+
+    def go_to_index(self, index: int | None) -> None:
+        """
+        Create a new :class:`.CompletionState` object with the new index.
+
+        When `index` is `None` deselect the completion.
+        """
+        if self.completions:
+            assert index is None or 0 <= index < len(self.completions)
+            self.complete_index = index
+
+    def new_text_and_position(self) -> tuple[str, int]:
+        """
+        Return (new_text, new_cursor_position) for this completion.
+        """
+        if self.complete_index is None:
+            return self.original_document.text, self.original_document.cursor_position
+        else:
+            original_text_before_cursor = self.original_document.text_before_cursor
+            original_text_after_cursor = self.original_document.text_after_cursor
+
+            c = self.completions[self.complete_index]
+            if c.start_position == 0:
+                before = original_text_before_cursor
+            else:
+                before = original_text_before_cursor[: c.start_position]
+
+            new_text = before + c.text + original_text_after_cursor
+            new_cursor_position = len(before) + len(c.text)
+            return new_text, new_cursor_position
+
+    @property
+    def current_completion(self) -> Completion | None:
+        """
+        Return the current completion, or return `None` when no completion is
+        selected.
+        """
+        if self.complete_index is not None:
+            return self.completions[self.complete_index]
+        return None
+
+
+_QUOTED_WORDS_RE = re.compile(r"""(\s+|".*?"|'.*?')""")
+
+
+class YankNthArgState:
+    """
+    For yank-last-arg/yank-nth-arg: Keep track of where we are in the history.
+    """
+
+    def __init__(
+        self, history_position: int = 0, n: int = -1, previous_inserted_word: str = ""
+    ) -> None:
+        self.history_position = history_position
+        self.previous_inserted_word = previous_inserted_word
+        self.n = n
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(history_position={self.history_position!r}, n={self.n!r}, previous_inserted_word={self.previous_inserted_word!r})"
+
+
+BufferEventHandler = Callable[["Buffer"], None]
+BufferAcceptHandler = Callable[["Buffer"], bool]
+
+
+class Buffer:
+    """
+    The core data structure that holds the text and cursor position of the
+    current input line and implements all text manipulations on top of it. It
+    also implements the history, undo stack and the completion state.
+
+    :param completer: :class:`~prompt_toolkit.completion.Completer` instance.
+    :param history: :class:`~prompt_toolkit.history.History` instance.
+    :param tempfile_suffix: The tempfile suffix (extension) to be used for the
+        "open in editor" function. For a Python REPL, this would be ".py", so
+        that the editor knows the syntax highlighting to use. This can also be
+        a callable that returns a string.
+    :param tempfile: For more advanced tempfile situations where you need
+        control over the subdirectories and filename. For a Git Commit Message,
+        this would be ".git/COMMIT_EDITMSG", so that the editor knows the syntax
+        highlighting to use. This can also be a callable that returns a string.
+    :param name: Name for this buffer. E.g. DEFAULT_BUFFER. This is mostly
+        useful for key bindings where we sometimes prefer to refer to a buffer
+        by their name instead of by reference.
+    :param accept_handler: Called when the buffer input is accepted. (Usually
+        when the user presses `enter`.) The accept handler receives this
+        `Buffer` as input and should return True when the buffer text should be
+        kept instead of calling reset.
+
+        In case of a `PromptSession` for instance, we want to keep the text,
+        because we will exit the application, and only reset it during the next
+        run.
+    :param max_number_of_completions: Never display more than this number of
+        completions, even when the completer can produce more (limited by
+        default to 10k for performance).
+
+    Events:
+
+    :param on_text_changed: When the buffer text changes. (Callable or None.)
+    :param on_text_insert: When new text is inserted. (Callable or None.)
+    :param on_cursor_position_changed: When the cursor moves. (Callable or None.)
+    :param on_completions_changed: When the completions were changed. (Callable or None.)
+    :param on_suggestion_set: When an auto-suggestion text has been set. (Callable or None.)
+
+    Filters:
+
+    :param complete_while_typing: :class:`~prompt_toolkit.filters.Filter`
+        or `bool`. Decide whether or not to do asynchronous autocompleting while
+        typing.
+    :param validate_while_typing: :class:`~prompt_toolkit.filters.Filter`
+        or `bool`. Decide whether or not to do asynchronous validation while
+        typing.
+    :param enable_history_search: :class:`~prompt_toolkit.filters.Filter` or
+        `bool` to indicate when up-arrow partial string matching is enabled. It
+        is advised to not enable this at the same time as
+        `complete_while_typing`, because when there is an autocompletion found,
+        the up arrows usually browse through the completions, rather than
+        through the history.
+    :param read_only: :class:`~prompt_toolkit.filters.Filter`. When True,
+        changes will not be allowed.
+    :param multiline: :class:`~prompt_toolkit.filters.Filter` or `bool`. When
+        not set, pressing `Enter` will call the `accept_handler`.  Otherwise,
+        pressing `Esc-Enter` is required.
+    """
+
+    def __init__(
+        self,
+        completer: Completer | None = None,
+        auto_suggest: AutoSuggest | None = None,
+        history: History | None = None,
+        validator: Validator | None = None,
+        tempfile_suffix: str | Callable[[], str] = "",
+        tempfile: str | Callable[[], str] = "",
+        name: str = "",
+        complete_while_typing: FilterOrBool = False,
+        validate_while_typing: FilterOrBool = False,
+        enable_history_search: FilterOrBool = False,
+        document: Document | None = None,
+        accept_handler: BufferAcceptHandler | None = None,
+        read_only: FilterOrBool = False,
+        multiline: FilterOrBool = True,
+        max_number_of_completions: int = 10000,
+        on_text_changed: BufferEventHandler | None = None,
+        on_text_insert: BufferEventHandler | None = None,
+        on_cursor_position_changed: BufferEventHandler | None = None,
+        on_completions_changed: BufferEventHandler | None = None,
+        on_suggestion_set: BufferEventHandler | None = None,
+    ) -> None:
+        # Accept both filters and booleans as input.
+        enable_history_search = to_filter(enable_history_search)
+        complete_while_typing = to_filter(complete_while_typing)
+        validate_while_typing = to_filter(validate_while_typing)
+        read_only = to_filter(read_only)
+        multiline = to_filter(multiline)
+
+        self.completer = completer or DummyCompleter()
+        self.auto_suggest = auto_suggest
+        self.validator = validator
+        self.tempfile_suffix = tempfile_suffix
+        self.tempfile = tempfile
+        self.name = name
+        self.accept_handler = accept_handler
+
+        # Filters. (Usually, used by the key bindings to drive the buffer.)
+        self.complete_while_typing = complete_while_typing
+        self.validate_while_typing = validate_while_typing
+        self.enable_history_search = enable_history_search
+        self.read_only = read_only
+        self.multiline = multiline
+        self.max_number_of_completions = max_number_of_completions
+
+        # Text width. (For wrapping, used by the Vi 'gq' operator.)
+        self.text_width = 0
+
+        #: The command buffer history.
+        # Note that we shouldn't use a lazy 'or' here. bool(history) could be
+        # False when empty.
+        self.history = InMemoryHistory() if history is None else history
+
+        self.__cursor_position = 0
+
+        # Events
+        self.on_text_changed: Event[Buffer] = Event(self, on_text_changed)
+        self.on_text_insert: Event[Buffer] = Event(self, on_text_insert)
+        self.on_cursor_position_changed: Event[Buffer] = Event(
+            self, on_cursor_position_changed
+        )
+        self.on_completions_changed: Event[Buffer] = Event(self, on_completions_changed)
+        self.on_suggestion_set: Event[Buffer] = Event(self, on_suggestion_set)
+
+        # Document cache. (Avoid creating new Document instances.)
+        self._document_cache: FastDictCache[
+            tuple[str, int, SelectionState | None], Document
+        ] = FastDictCache(Document, size=10)
+
+        # Create completer / auto suggestion / validation coroutines.
+        self._async_suggester = self._create_auto_suggest_coroutine()
+        self._async_completer = self._create_completer_coroutine()
+        self._async_validator = self._create_auto_validate_coroutine()
+
+        # Asyncio task for populating the history.
+        self._load_history_task: asyncio.Future[None] | None = None
+
+        # Reset other attributes.
+        self.reset(document=document)
+
+    def __repr__(self) -> str:
+        if len(self.text) < 15:
+            text = self.text
+        else:
+            text = self.text[:12] + "..."
+
+        return f"<Buffer(name={self.name!r}, text={text!r}) at {id(self)!r}>"
+
+    def reset(
+        self, document: Document | None = None, append_to_history: bool = False
+    ) -> None:
+        """
+        :param append_to_history: Append current input to history first.
+        """
+        if append_to_history:
+            self.append_to_history()
+
+        document = document or Document()
+
+        self.__cursor_position = document.cursor_position
+
+        # `ValidationError` instance. (Will be set when the input is wrong.)
+        self.validation_error: ValidationError | None = None
+        self.validation_state: ValidationState | None = ValidationState.UNKNOWN
+
+        # State of the selection.
+        self.selection_state: SelectionState | None = None
+
+        # Multiple cursor mode. (When we press 'I' or 'A' in visual-block mode,
+        # we can insert text on multiple lines at once. This is implemented by
+        # using multiple cursors.)
+        self.multiple_cursor_positions: list[int] = []
+
+        # When doing consecutive up/down movements, prefer to stay at this column.
+        self.preferred_column: int | None = None
+
+        # State of complete browser
+        # For interactive completion through Ctrl-N/Ctrl-P.
+        self.complete_state: CompletionState | None = None
+
+        # State of Emacs yank-nth-arg completion.
+        self.yank_nth_arg_state: YankNthArgState | None = None  # for yank-nth-arg.
+
+        # Remember the document that we had *right before* the last paste
+        # operation. This is used for rotating through the kill ring.
+        self.document_before_paste: Document | None = None
+
+        # Current suggestion.
+        self.suggestion: Suggestion | None = None
+
+        # The history search text. (Used for filtering the history when we
+        # browse through it.)
+        self.history_search_text: str | None = None
+
+        # Undo/redo stacks (stack of `(text, cursor_position)`).
+        self._undo_stack: list[tuple[str, int]] = []
+        self._redo_stack: list[tuple[str, int]] = []
+
+        # Cancel history loader. If history loading was still ongoing.
+        # Cancel the `_load_history_task`, so that next repaint of the
+        # `BufferControl` we will repopulate it.
+        if self._load_history_task is not None:
+            self._load_history_task.cancel()
+        self._load_history_task = None
+
+        #: The working lines. Similar to history, except that this can be
+        #: modified. The user can press arrow_up and edit previous entries.
+        #: Ctrl-C should reset this, and copy the whole history back in here.
+        #: Enter should process the current command and append to the real
+        #: history.
+        self._working_lines: deque[str] = deque([document.text])
+        self.__working_index = 0
+
+    def load_history_if_not_yet_loaded(self) -> None:
+        """
+        Create task for populating the buffer history (if not yet done).
+
+        Note::
+
+            This needs to be called from within the event loop of the
+            application, because history loading is async, and we need to be
+            sure the right event loop is active. Therefor, we call this method
+            in the `BufferControl.create_content`.
+
+            There are situations where prompt_toolkit applications are created
+            in one thread, but will later run in a different thread (Ptpython
+            is one example. The REPL runs in a separate thread, in order to
+            prevent interfering with a potential different event loop in the
+            main thread. The REPL UI however is still created in the main
+            thread.) We could decide to not support creating prompt_toolkit
+            objects in one thread and running the application in a different
+            thread, but history loading is the only place where it matters, and
+            this solves it.
+        """
+        if self._load_history_task is None:
+
+            async def load_history() -> None:
+                async for item in self.history.load():
+                    self._working_lines.appendleft(item)
+                    self.__working_index += 1
+
+            self._load_history_task = get_app().create_background_task(load_history())
+
+            def load_history_done(f: asyncio.Future[None]) -> None:
+                """
+                Handle `load_history` result when either done, cancelled, or
+                when an exception was raised.
+                """
+                try:
+                    f.result()
+                except asyncio.CancelledError:
+                    # Ignore cancellation. But handle it, so that we don't get
+                    # this traceback.
+                    pass
+                except GeneratorExit:
+                    # Probably not needed, but we had situations where
+                    # `GeneratorExit` was raised in `load_history` during
+                    # cancellation.
+                    pass
+                except BaseException:
+                    # Log error if something goes wrong. (We don't have a
+                    # caller to which we can propagate this exception.)
+                    logger.exception("Loading history failed")
+
+            self._load_history_task.add_done_callback(load_history_done)
+
+    # <getters/setters>
+
+    def _set_text(self, value: str) -> bool:
+        """set text at current working_index. Return whether it changed."""
+        working_index = self.working_index
+        working_lines = self._working_lines
+
+        original_value = working_lines[working_index]
+        working_lines[working_index] = value
+
+        # Return True when this text has been changed.
+        if len(value) != len(original_value):
+            # For Python 2, it seems that when two strings have a different
+            # length and one is a prefix of the other, Python still scans
+            # character by character to see whether the strings are different.
+            # (Some benchmarking showed significant differences for big
+            # documents. >100,000 of lines.)
+            return True
+        elif value != original_value:
+            return True
+        return False
+
+    def _set_cursor_position(self, value: int) -> bool:
+        """Set cursor position. Return whether it changed."""
+        original_position = self.__cursor_position
+        self.__cursor_position = max(0, value)
+
+        return self.__cursor_position != original_position
+
+    @property
+    def text(self) -> str:
+        return self._working_lines[self.working_index]
+
+    @text.setter
+    def text(self, value: str) -> None:
+        """
+        Setting text. (When doing this, make sure that the cursor_position is
+        valid for this text. text/cursor_position should be consistent at any time,
+        otherwise set a Document instead.)
+        """
+        # Ensure cursor position remains within the size of the text.
+        if self.cursor_position > len(value):
+            self.cursor_position = len(value)
+
+        # Don't allow editing of read-only buffers.
+        if self.read_only():
+            raise EditReadOnlyBuffer()
+
+        changed = self._set_text(value)
+
+        if changed:
+            self._text_changed()
+
+            # Reset history search text.
+            # (Note that this doesn't need to happen when working_index
+            #  changes, which is when we traverse the history. That's why we
+            #  don't do this in `self._text_changed`.)
+            self.history_search_text = None
+
+    @property
+    def cursor_position(self) -> int:
+        return self.__cursor_position
+
+    @cursor_position.setter
+    def cursor_position(self, value: int) -> None:
+        """
+        Setting cursor position.
+        """
+        assert isinstance(value, int)
+
+        # Ensure cursor position is within the size of the text.
+        if value > len(self.text):
+            value = len(self.text)
+        if value < 0:
+            value = 0
+
+        changed = self._set_cursor_position(value)
+
+        if changed:
+            self._cursor_position_changed()
+
+    @property
+    def working_index(self) -> int:
+        return self.__working_index
+
+    @working_index.setter
+    def working_index(self, value: int) -> None:
+        if self.__working_index != value:
+            self.__working_index = value
+            # Make sure to reset the cursor position, otherwise we end up in
+            # situations where the cursor position is out of the bounds of the
+            # text.
+            self.cursor_position = 0
+            self._text_changed()
+
+    def _text_changed(self) -> None:
+        # Remove any validation errors and complete state.
+        self.validation_error = None
+        self.validation_state = ValidationState.UNKNOWN
+        self.complete_state = None
+        self.yank_nth_arg_state = None
+        self.document_before_paste = None
+        self.selection_state = None
+        self.suggestion = None
+        self.preferred_column = None
+
+        # fire 'on_text_changed' event.
+        self.on_text_changed.fire()
+
+        # Input validation.
+        # (This happens on all change events, unlike auto completion, also when
+        # deleting text.)
+        if self.validator and self.validate_while_typing():
+            get_app().create_background_task(self._async_validator())
+
+    def _cursor_position_changed(self) -> None:
+        # Remove any complete state.
+        # (Input validation should only be undone when the cursor position
+        # changes.)
+        self.complete_state = None
+        self.yank_nth_arg_state = None
+        self.document_before_paste = None
+
+        # Unset preferred_column. (Will be set after the cursor movement, if
+        # required.)
+        self.preferred_column = None
+
+        # Note that the cursor position can change if we have a selection the
+        # new position of the cursor determines the end of the selection.
+
+        # fire 'on_cursor_position_changed' event.
+        self.on_cursor_position_changed.fire()
+
+    @property
+    def document(self) -> Document:
+        """
+        Return :class:`~prompt_toolkit.document.Document` instance from the
+        current text, cursor position and selection state.
+        """
+        return self._document_cache[
+            self.text, self.cursor_position, self.selection_state
+        ]
+
+    @document.setter
+    def document(self, value: Document) -> None:
+        """
+        Set :class:`~prompt_toolkit.document.Document` instance.
+
+        This will set both the text and cursor position at the same time, but
+        atomically. (Change events will be triggered only after both have been set.)
+        """
+        self.set_document(value)
+
+    def set_document(self, value: Document, bypass_readonly: bool = False) -> None:
+        """
+        Set :class:`~prompt_toolkit.document.Document` instance. Like the
+        ``document`` property, but accept an ``bypass_readonly`` argument.
+
+        :param bypass_readonly: When True, don't raise an
+                                :class:`.EditReadOnlyBuffer` exception, even
+                                when the buffer is read-only.
+
+        .. warning::
+
+            When this buffer is read-only and `bypass_readonly` was not passed,
+            the `EditReadOnlyBuffer` exception will be caught by the
+            `KeyProcessor` and is silently suppressed. This is important to
+            keep in mind when writing key bindings, because it won't do what
+            you expect, and there won't be a stack trace. Use try/finally
+            around this function if you need some cleanup code.
+        """
+        # Don't allow editing of read-only buffers.
+        if not bypass_readonly and self.read_only():
+            raise EditReadOnlyBuffer()
+
+        # Set text and cursor position first.
+        text_changed = self._set_text(value.text)
+        cursor_position_changed = self._set_cursor_position(value.cursor_position)
+
+        # Now handle change events. (We do this when text/cursor position is
+        # both set and consistent.)
+        if text_changed:
+            self._text_changed()
+            self.history_search_text = None
+
+        if cursor_position_changed:
+            self._cursor_position_changed()
+
+    @property
+    def is_returnable(self) -> bool:
+        """
+        True when there is something handling accept.
+        """
+        return bool(self.accept_handler)
+
+    # End of <getters/setters>
+
+    def save_to_undo_stack(self, clear_redo_stack: bool = True) -> None:
+        """
+        Safe current state (input text and cursor position), so that we can
+        restore it by calling undo.
+        """
+        # Safe if the text is different from the text at the top of the stack
+        # is different. If the text is the same, just update the cursor position.
+        if self._undo_stack and self._undo_stack[-1][0] == self.text:
+            self._undo_stack[-1] = (self._undo_stack[-1][0], self.cursor_position)
+        else:
+            self._undo_stack.append((self.text, self.cursor_position))
+
+        # Saving anything to the undo stack, clears the redo stack.
+        if clear_redo_stack:
+            self._redo_stack = []
+
+    def transform_lines(
+        self,
+        line_index_iterator: Iterable[int],
+        transform_callback: Callable[[str], str],
+    ) -> str:
+        """
+        Transforms the text on a range of lines.
+        When the iterator yield an index not in the range of lines that the
+        document contains, it skips them silently.
+
+        To uppercase some lines::
+
+            new_text = transform_lines(range(5,10), lambda text: text.upper())
+
+        :param line_index_iterator: Iterator of line numbers (int)
+        :param transform_callback: callable that takes the original text of a
+                                   line, and return the new text for this line.
+
+        :returns: The new text.
+        """
+        # Split lines
+        lines = self.text.split("\n")
+
+        # Apply transformation
+        for index in line_index_iterator:
+            try:
+                lines[index] = transform_callback(lines[index])
+            except IndexError:
+                pass
+
+        return "\n".join(lines)
+
+    def transform_current_line(self, transform_callback: Callable[[str], str]) -> None:
+        """
+        Apply the given transformation function to the current line.
+
+        :param transform_callback: callable that takes a string and return a new string.
+        """
+        document = self.document
+        a = document.cursor_position + document.get_start_of_line_position()
+        b = document.cursor_position + document.get_end_of_line_position()
+        self.text = (
+            document.text[:a]
+            + transform_callback(document.text[a:b])
+            + document.text[b:]
+        )
+
+    def transform_region(
+        self, from_: int, to: int, transform_callback: Callable[[str], str]
+    ) -> None:
+        """
+        Transform a part of the input string.
+
+        :param from_: (int) start position.
+        :param to: (int) end position.
+        :param transform_callback: Callable which accepts a string and returns
+            the transformed string.
+        """
+        assert from_ < to
+
+        self.text = "".join(
+            [
+                self.text[:from_]
+                + transform_callback(self.text[from_:to])
+                + self.text[to:]
+            ]
+        )
+
+    def cursor_left(self, count: int = 1) -> None:
+        self.cursor_position += self.document.get_cursor_left_position(count=count)
+
+    def cursor_right(self, count: int = 1) -> None:
+        self.cursor_position += self.document.get_cursor_right_position(count=count)
+
+    def cursor_up(self, count: int = 1) -> None:
+        """(for multiline edit). Move cursor to the previous line."""
+        original_column = self.preferred_column or self.document.cursor_position_col
+        self.cursor_position += self.document.get_cursor_up_position(
+            count=count, preferred_column=original_column
+        )
+
+        # Remember the original column for the next up/down movement.
+        self.preferred_column = original_column
+
+    def cursor_down(self, count: int = 1) -> None:
+        """(for multiline edit). Move cursor to the next line."""
+        original_column = self.preferred_column or self.document.cursor_position_col
+        self.cursor_position += self.document.get_cursor_down_position(
+            count=count, preferred_column=original_column
+        )
+
+        # Remember the original column for the next up/down movement.
+        self.preferred_column = original_column
+
+    def auto_up(
+        self, count: int = 1, go_to_start_of_line_if_history_changes: bool = False
+    ) -> None:
+        """
+        If we're not on the first line (of a multiline input) go a line up,
+        otherwise go back in history. (If nothing is selected.)
+        """
+        if self.complete_state:
+            self.complete_previous(count=count)
+        elif self.document.cursor_position_row > 0:
+            self.cursor_up(count=count)
+        elif not self.selection_state:
+            self.history_backward(count=count)
+
+            # Go to the start of the line?
+            if go_to_start_of_line_if_history_changes:
+                self.cursor_position += self.document.get_start_of_line_position()
+
+    def auto_down(
+        self, count: int = 1, go_to_start_of_line_if_history_changes: bool = False
+    ) -> None:
+        """
+        If we're not on the last line (of a multiline input) go a line down,
+        otherwise go forward in history. (If nothing is selected.)
+        """
+        if self.complete_state:
+            self.complete_next(count=count)
+        elif self.document.cursor_position_row < self.document.line_count - 1:
+            self.cursor_down(count=count)
+        elif not self.selection_state:
+            self.history_forward(count=count)
+
+            # Go to the start of the line?
+            if go_to_start_of_line_if_history_changes:
+                self.cursor_position += self.document.get_start_of_line_position()
+
+    def delete_before_cursor(self, count: int = 1) -> str:
+        """
+        Delete specified number of characters before cursor and return the
+        deleted text.
+        """
+        assert count >= 0
+        deleted = ""
+
+        if self.cursor_position > 0:
+            deleted = self.text[self.cursor_position - count : self.cursor_position]
+
+            new_text = (
+                self.text[: self.cursor_position - count]
+                + self.text[self.cursor_position :]
+            )
+            new_cursor_position = self.cursor_position - len(deleted)
+
+            # Set new Document atomically.
+            self.document = Document(new_text, new_cursor_position)
+
+        return deleted
+
+    def delete(self, count: int = 1) -> str:
+        """
+        Delete specified number of characters and Return the deleted text.
+        """
+        if self.cursor_position < len(self.text):
+            deleted = self.document.text_after_cursor[:count]
+            self.text = (
+                self.text[: self.cursor_position]
+                + self.text[self.cursor_position + len(deleted) :]
+            )
+            return deleted
+        else:
+            return ""
+
+    def join_next_line(self, separator: str = " ") -> None:
+        """
+        Join the next line to the current one by deleting the line ending after
+        the current line.
+        """
+        if not self.document.on_last_line:
+            self.cursor_position += self.document.get_end_of_line_position()
+            self.delete()
+
+            # Remove spaces.
+            self.text = (
+                self.document.text_before_cursor
+                + separator
+                + self.document.text_after_cursor.lstrip(" ")
+            )
+
+    def join_selected_lines(self, separator: str = " ") -> None:
+        """
+        Join the selected lines.
+        """
+        assert self.selection_state
+
+        # Get lines.
+        from_, to = sorted(
+            [self.cursor_position, self.selection_state.original_cursor_position]
+        )
+
+        before = self.text[:from_]
+        lines = self.text[from_:to].splitlines()
+        after = self.text[to:]
+
+        # Replace leading spaces with just one space.
+        lines = [l.lstrip(" ") + separator for l in lines]
+
+        # Set new document.
+        self.document = Document(
+            text=before + "".join(lines) + after,
+            cursor_position=len(before + "".join(lines[:-1])) - 1,
+        )
+
+    def swap_characters_before_cursor(self) -> None:
+        """
+        Swap the last two characters before the cursor.
+        """
+        pos = self.cursor_position
+
+        if pos >= 2:
+            a = self.text[pos - 2]
+            b = self.text[pos - 1]
+
+            self.text = self.text[: pos - 2] + b + a + self.text[pos:]
+
+    def go_to_history(self, index: int) -> None:
+        """
+        Go to this item in the history.
+        """
+        if index < len(self._working_lines):
+            self.working_index = index
+            self.cursor_position = len(self.text)
+
+    def complete_next(self, count: int = 1, disable_wrap_around: bool = False) -> None:
+        """
+        Browse to the next completions.
+        (Does nothing if there are no completion.)
+        """
+        index: int | None
+
+        if self.complete_state:
+            completions_count = len(self.complete_state.completions)
+
+            if self.complete_state.complete_index is None:
+                index = 0
+            elif self.complete_state.complete_index == completions_count - 1:
+                index = None
+
+                if disable_wrap_around:
+                    return
+            else:
+                index = min(
+                    completions_count - 1, self.complete_state.complete_index + count
+                )
+            self.go_to_completion(index)
+
+    def complete_previous(
+        self, count: int = 1, disable_wrap_around: bool = False
+    ) -> None:
+        """
+        Browse to the previous completions.
+        (Does nothing if there are no completion.)
+        """
+        index: int | None
+
+        if self.complete_state:
+            if self.complete_state.complete_index == 0:
+                index = None
+
+                if disable_wrap_around:
+                    return
+            elif self.complete_state.complete_index is None:
+                index = len(self.complete_state.completions) - 1
+            else:
+                index = max(0, self.complete_state.complete_index - count)
+
+            self.go_to_completion(index)
+
+    def cancel_completion(self) -> None:
+        """
+        Cancel completion, go back to the original text.
+        """
+        if self.complete_state:
+            self.go_to_completion(None)
+            self.complete_state = None
+
+    def _set_completions(self, completions: list[Completion]) -> CompletionState:
+        """
+        Start completions. (Generate list of completions and initialize.)
+
+        By default, no completion will be selected.
+        """
+        self.complete_state = CompletionState(
+            original_document=self.document, completions=completions
+        )
+
+        # Trigger event. This should eventually invalidate the layout.
+        self.on_completions_changed.fire()
+
+        return self.complete_state
+
+    def start_history_lines_completion(self) -> None:
+        """
+        Start a completion based on all the other lines in the document and the
+        history.
+        """
+        found_completions: set[str] = set()
+        completions = []
+
+        # For every line of the whole history, find matches with the current line.
+        current_line = self.document.current_line_before_cursor.lstrip()
+
+        for i, string in enumerate(self._working_lines):
+            for j, l in enumerate(string.split("\n")):
+                l = l.strip()
+                if l and l.startswith(current_line):
+                    # When a new line has been found.
+                    if l not in found_completions:
+                        found_completions.add(l)
+
+                        # Create completion.
+                        if i == self.working_index:
+                            display_meta = "Current, line %s" % (j + 1)
+                        else:
+                            display_meta = f"History {i + 1}, line {j + 1}"
+
+                        completions.append(
+                            Completion(
+                                text=l,
+                                start_position=-len(current_line),
+                                display_meta=display_meta,
+                            )
+                        )
+
+        self._set_completions(completions=completions[::-1])
+        self.go_to_completion(0)
+
+    def go_to_completion(self, index: int | None) -> None:
+        """
+        Select a completion from the list of current completions.
+        """
+        assert self.complete_state
+
+        # Set new completion
+        state = self.complete_state
+        state.go_to_index(index)
+
+        # Set text/cursor position
+        new_text, new_cursor_position = state.new_text_and_position()
+        self.document = Document(new_text, new_cursor_position)
+
+        # (changing text/cursor position will unset complete_state.)
+        self.complete_state = state
+
+    def apply_completion(self, completion: Completion) -> None:
+        """
+        Insert a given completion.
+        """
+        # If there was already a completion active, cancel that one.
+        if self.complete_state:
+            self.go_to_completion(None)
+        self.complete_state = None
+
+        # Insert text from the given completion.
+        self.delete_before_cursor(-completion.start_position)
+        self.insert_text(completion.text)
+
+    def _set_history_search(self) -> None:
+        """
+        Set `history_search_text`.
+        (The text before the cursor will be used for filtering the history.)
+        """
+        if self.enable_history_search():
+            if self.history_search_text is None:
+                self.history_search_text = self.document.text_before_cursor
+        else:
+            self.history_search_text = None
+
+    def _history_matches(self, i: int) -> bool:
+        """
+        True when the current entry matches the history search.
+        (when we don't have history search, it's also True.)
+        """
+        return self.history_search_text is None or self._working_lines[i].startswith(
+            self.history_search_text
+        )
+
+    def history_forward(self, count: int = 1) -> None:
+        """
+        Move forwards through the history.
+
+        :param count: Amount of items to move forward.
+        """
+        self._set_history_search()
+
+        # Go forward in history.
+        found_something = False
+
+        for i in range(self.working_index + 1, len(self._working_lines)):
+            if self._history_matches(i):
+                self.working_index = i
+                count -= 1
+                found_something = True
+            if count == 0:
+                break
+
+        # If we found an entry, move cursor to the end of the first line.
+        if found_something:
+            self.cursor_position = 0
+            self.cursor_position += self.document.get_end_of_line_position()
+
+    def history_backward(self, count: int = 1) -> None:
+        """
+        Move backwards through history.
+        """
+        self._set_history_search()
+
+        # Go back in history.
+        found_something = False
+
+        for i in range(self.working_index - 1, -1, -1):
+            if self._history_matches(i):
+                self.working_index = i
+                count -= 1
+                found_something = True
+            if count == 0:
+                break
+
+        # If we move to another entry, move cursor to the end of the line.
+        if found_something:
+            self.cursor_position = len(self.text)
+
+    def yank_nth_arg(self, n: int | None = None, _yank_last_arg: bool = False) -> None:
+        """
+        Pick nth word from previous history entry (depending on current
+        `yank_nth_arg_state`) and insert it at current position. Rotate through
+        history if called repeatedly. If no `n` has been given, take the first
+        argument. (The second word.)
+
+        :param n: (None or int), The index of the word from the previous line
+            to take.
+        """
+        assert n is None or isinstance(n, int)
+        history_strings = self.history.get_strings()
+
+        if not len(history_strings):
+            return
+
+        # Make sure we have a `YankNthArgState`.
+        if self.yank_nth_arg_state is None:
+            state = YankNthArgState(n=-1 if _yank_last_arg else 1)
+        else:
+            state = self.yank_nth_arg_state
+
+        if n is not None:
+            state.n = n
+
+        # Get new history position.
+        new_pos = state.history_position - 1
+        if -new_pos > len(history_strings):
+            new_pos = -1
+
+        # Take argument from line.
+        line = history_strings[new_pos]
+
+        words = [w.strip() for w in _QUOTED_WORDS_RE.split(line)]
+        words = [w for w in words if w]
+        try:
+            word = words[state.n]
+        except IndexError:
+            word = ""
+
+        # Insert new argument.
+        if state.previous_inserted_word:
+            self.delete_before_cursor(len(state.previous_inserted_word))
+        self.insert_text(word)
+
+        # Save state again for next completion. (Note that the 'insert'
+        # operation from above clears `self.yank_nth_arg_state`.)
+        state.previous_inserted_word = word
+        state.history_position = new_pos
+        self.yank_nth_arg_state = state
+
+    def yank_last_arg(self, n: int | None = None) -> None:
+        """
+        Like `yank_nth_arg`, but if no argument has been given, yank the last
+        word by default.
+        """
+        self.yank_nth_arg(n=n, _yank_last_arg=True)
+
+    def start_selection(
+        self, selection_type: SelectionType = SelectionType.CHARACTERS
+    ) -> None:
+        """
+        Take the current cursor position as the start of this selection.
+        """
+        self.selection_state = SelectionState(self.cursor_position, selection_type)
+
+    def copy_selection(self, _cut: bool = False) -> ClipboardData:
+        """
+        Copy selected text and return :class:`.ClipboardData` instance.
+
+        Notice that this doesn't store the copied data on the clipboard yet.
+        You can store it like this:
+
+        .. code:: python
+
+            data = buffer.copy_selection()
+            get_app().clipboard.set_data(data)
+        """
+        new_document, clipboard_data = self.document.cut_selection()
+        if _cut:
+            self.document = new_document
+
+        self.selection_state = None
+        return clipboard_data
+
+    def cut_selection(self) -> ClipboardData:
+        """
+        Delete selected text and return :class:`.ClipboardData` instance.
+        """
+        return self.copy_selection(_cut=True)
+
+    def paste_clipboard_data(
+        self,
+        data: ClipboardData,
+        paste_mode: PasteMode = PasteMode.EMACS,
+        count: int = 1,
+    ) -> None:
+        """
+        Insert the data from the clipboard.
+        """
+        assert isinstance(data, ClipboardData)
+        assert paste_mode in (PasteMode.VI_BEFORE, PasteMode.VI_AFTER, PasteMode.EMACS)
+
+        original_document = self.document
+        self.document = self.document.paste_clipboard_data(
+            data, paste_mode=paste_mode, count=count
+        )
+
+        # Remember original document. This assignment should come at the end,
+        # because assigning to 'document' will erase it.
+        self.document_before_paste = original_document
+
+    def newline(self, copy_margin: bool = True) -> None:
+        """
+        Insert a line ending at the current position.
+        """
+        if copy_margin:
+            self.insert_text("\n" + self.document.leading_whitespace_in_current_line)
+        else:
+            self.insert_text("\n")
+
+    def insert_line_above(self, copy_margin: bool = True) -> None:
+        """
+        Insert a new line above the current one.
+        """
+        if copy_margin:
+            insert = self.document.leading_whitespace_in_current_line + "\n"
+        else:
+            insert = "\n"
+
+        self.cursor_position += self.document.get_start_of_line_position()
+        self.insert_text(insert)
+        self.cursor_position -= 1
+
+    def insert_line_below(self, copy_margin: bool = True) -> None:
+        """
+        Insert a new line below the current one.
+        """
+        if copy_margin:
+            insert = "\n" + self.document.leading_whitespace_in_current_line
+        else:
+            insert = "\n"
+
+        self.cursor_position += self.document.get_end_of_line_position()
+        self.insert_text(insert)
+
+    def insert_text(
+        self,
+        data: str,
+        overwrite: bool = False,
+        move_cursor: bool = True,
+        fire_event: bool = True,
+    ) -> None:
+        """
+        Insert characters at cursor position.
+
+        :param fire_event: Fire `on_text_insert` event. This is mainly used to
+            trigger autocompletion while typing.
+        """
+        # Original text & cursor position.
+        otext = self.text
+        ocpos = self.cursor_position
+
+        # In insert/text mode.
+        if overwrite:
+            # Don't overwrite the newline itself. Just before the line ending,
+            # it should act like insert mode.
+            overwritten_text = otext[ocpos : ocpos + len(data)]
+            if "\n" in overwritten_text:
+                overwritten_text = overwritten_text[: overwritten_text.find("\n")]
+
+            text = otext[:ocpos] + data + otext[ocpos + len(overwritten_text) :]
+        else:
+            text = otext[:ocpos] + data + otext[ocpos:]
+
+        if move_cursor:
+            cpos = self.cursor_position + len(data)
+        else:
+            cpos = self.cursor_position
+
+        # Set new document.
+        # (Set text and cursor position at the same time. Otherwise, setting
+        # the text will fire a change event before the cursor position has been
+        # set. It works better to have this atomic.)
+        self.document = Document(text, cpos)
+
+        # Fire 'on_text_insert' event.
+        if fire_event:  # XXX: rename to `start_complete`.
+            self.on_text_insert.fire()
+
+            # Only complete when "complete_while_typing" is enabled.
+            if self.completer and self.complete_while_typing():
+                get_app().create_background_task(self._async_completer())
+
+            # Call auto_suggest.
+            if self.auto_suggest:
+                get_app().create_background_task(self._async_suggester())
+
+    def undo(self) -> None:
+        # Pop from the undo-stack until we find a text that if different from
+        # the current text. (The current logic of `save_to_undo_stack` will
+        # cause that the top of the undo stack is usually the same as the
+        # current text, so in that case we have to pop twice.)
+        while self._undo_stack:
+            text, pos = self._undo_stack.pop()
+
+            if text != self.text:
+                # Push current text to redo stack.
+                self._redo_stack.append((self.text, self.cursor_position))
+
+                # Set new text/cursor_position.
+                self.document = Document(text, cursor_position=pos)
+                break
+
+    def redo(self) -> None:
+        if self._redo_stack:
+            # Copy current state on undo stack.
+            self.save_to_undo_stack(clear_redo_stack=False)
+
+            # Pop state from redo stack.
+            text, pos = self._redo_stack.pop()
+            self.document = Document(text, cursor_position=pos)
+
+    def validate(self, set_cursor: bool = False) -> bool:
+        """
+        Returns `True` if valid.
+
+        :param set_cursor: Set the cursor position, if an error was found.
+        """
+        # Don't call the validator again, if it was already called for the
+        # current input.
+        if self.validation_state != ValidationState.UNKNOWN:
+            return self.validation_state == ValidationState.VALID
+
+        # Call validator.
+        if self.validator:
+            try:
+                self.validator.validate(self.document)
+            except ValidationError as e:
+                # Set cursor position (don't allow invalid values.)
+                if set_cursor:
+                    self.cursor_position = min(
+                        max(0, e.cursor_position), len(self.text)
+                    )
+
+                self.validation_state = ValidationState.INVALID
+                self.validation_error = e
+                return False
+
+        # Handle validation result.
+        self.validation_state = ValidationState.VALID
+        self.validation_error = None
+        return True
+
+    async def _validate_async(self) -> None:
+        """
+        Asynchronous version of `validate()`.
+        This one doesn't set the cursor position.
+
+        We have both variants, because a synchronous version is required.
+        Handling the ENTER key needs to be completely synchronous, otherwise
+        stuff like type-ahead is going to give very weird results. (People
+        could type input while the ENTER key is still processed.)
+
+        An asynchronous version is required if we have `validate_while_typing`
+        enabled.
+        """
+        while True:
+            # Don't call the validator again, if it was already called for the
+            # current input.
+            if self.validation_state != ValidationState.UNKNOWN:
+                return
+
+            # Call validator.
+            error = None
+            document = self.document
+
+            if self.validator:
+                try:
+                    await self.validator.validate_async(self.document)
+                except ValidationError as e:
+                    error = e
+
+                # If the document changed during the validation, try again.
+                if self.document != document:
+                    continue
+
+            # Handle validation result.
+            if error:
+                self.validation_state = ValidationState.INVALID
+            else:
+                self.validation_state = ValidationState.VALID
+
+            self.validation_error = error
+            get_app().invalidate()  # Trigger redraw (display error).
+
+    def append_to_history(self) -> None:
+        """
+        Append the current input to the history.
+        """
+        # Save at the tail of the history. (But don't if the last entry the
+        # history is already the same.)
+        if self.text:
+            history_strings = self.history.get_strings()
+            if not len(history_strings) or history_strings[-1] != self.text:
+                self.history.append_string(self.text)
+
+    def _search(
+        self,
+        search_state: SearchState,
+        include_current_position: bool = False,
+        count: int = 1,
+    ) -> tuple[int, int] | None:
+        """
+        Execute search. Return (working_index, cursor_position) tuple when this
+        search is applied. Returns `None` when this text cannot be found.
+        """
+        assert count > 0
+
+        text = search_state.text
+        direction = search_state.direction
+        ignore_case = search_state.ignore_case()
+
+        def search_once(
+            working_index: int, document: Document
+        ) -> tuple[int, Document] | None:
+            """
+            Do search one time.
+            Return (working_index, document) or `None`
+            """
+            if direction == SearchDirection.FORWARD:
+                # Try find at the current input.
+                new_index = document.find(
+                    text,
+                    include_current_position=include_current_position,
+                    ignore_case=ignore_case,
+                )
+
+                if new_index is not None:
+                    return (
+                        working_index,
+                        Document(document.text, document.cursor_position + new_index),
+                    )
+                else:
+                    # No match, go forward in the history. (Include len+1 to wrap around.)
+                    # (Here we should always include all cursor positions, because
+                    # it's a different line.)
+                    for i in range(working_index + 1, len(self._working_lines) + 1):
+                        i %= len(self._working_lines)
+
+                        document = Document(self._working_lines[i], 0)
+                        new_index = document.find(
+                            text, include_current_position=True, ignore_case=ignore_case
+                        )
+                        if new_index is not None:
+                            return (i, Document(document.text, new_index))
+            else:
+                # Try find at the current input.
+                new_index = document.find_backwards(text, ignore_case=ignore_case)
+
+                if new_index is not None:
+                    return (
+                        working_index,
+                        Document(document.text, document.cursor_position + new_index),
+                    )
+                else:
+                    # No match, go back in the history. (Include -1 to wrap around.)
+                    for i in range(working_index - 1, -2, -1):
+                        i %= len(self._working_lines)
+
+                        document = Document(
+                            self._working_lines[i], len(self._working_lines[i])
+                        )
+                        new_index = document.find_backwards(
+                            text, ignore_case=ignore_case
+                        )
+                        if new_index is not None:
+                            return (
+                                i,
+                                Document(document.text, len(document.text) + new_index),
+                            )
+            return None
+
+        # Do 'count' search iterations.
+        working_index = self.working_index
+        document = self.document
+        for _ in range(count):
+            result = search_once(working_index, document)
+            if result is None:
+                return None  # Nothing found.
+            else:
+                working_index, document = result
+
+        return (working_index, document.cursor_position)
+
+    def document_for_search(self, search_state: SearchState) -> Document:
+        """
+        Return a :class:`~prompt_toolkit.document.Document` instance that has
+        the text/cursor position for this search, if we would apply it. This
+        will be used in the
+        :class:`~prompt_toolkit.layout.BufferControl` to display feedback while
+        searching.
+        """
+        search_result = self._search(search_state, include_current_position=True)
+
+        if search_result is None:
+            return self.document
+        else:
+            working_index, cursor_position = search_result
+
+            # Keep selection, when `working_index` was not changed.
+            if working_index == self.working_index:
+                selection = self.selection_state
+            else:
+                selection = None
+
+            return Document(
+                self._working_lines[working_index], cursor_position, selection=selection
+            )
+
+    def get_search_position(
+        self,
+        search_state: SearchState,
+        include_current_position: bool = True,
+        count: int = 1,
+    ) -> int:
+        """
+        Get the cursor position for this search.
+        (This operation won't change the `working_index`. It's won't go through
+        the history. Vi text objects can't span multiple items.)
+        """
+        search_result = self._search(
+            search_state, include_current_position=include_current_position, count=count
+        )
+
+        if search_result is None:
+            return self.cursor_position
+        else:
+            working_index, cursor_position = search_result
+            return cursor_position
+
+    def apply_search(
+        self,
+        search_state: SearchState,
+        include_current_position: bool = True,
+        count: int = 1,
+    ) -> None:
+        """
+        Apply search. If something is found, set `working_index` and
+        `cursor_position`.
+        """
+        search_result = self._search(
+            search_state, include_current_position=include_current_position, count=count
+        )
+
+        if search_result is not None:
+            working_index, cursor_position = search_result
+            self.working_index = working_index
+            self.cursor_position = cursor_position
+
+    def exit_selection(self) -> None:
+        self.selection_state = None
+
+    def _editor_simple_tempfile(self) -> tuple[str, Callable[[], None]]:
+        """
+        Simple (file) tempfile implementation.
+        Return (tempfile, cleanup_func).
+        """
+        suffix = to_str(self.tempfile_suffix)
+        descriptor, filename = tempfile.mkstemp(suffix)
+
+        os.write(descriptor, self.text.encode("utf-8"))
+        os.close(descriptor)
+
+        def cleanup() -> None:
+            os.unlink(filename)
+
+        return filename, cleanup
+
+    def _editor_complex_tempfile(self) -> tuple[str, Callable[[], None]]:
+        # Complex (directory) tempfile implementation.
+        headtail = to_str(self.tempfile)
+        if not headtail:
+            # Revert to simple case.
+            return self._editor_simple_tempfile()
+        headtail = str(headtail)
+
+        # Try to make according to tempfile logic.
+        head, tail = os.path.split(headtail)
+        if os.path.isabs(head):
+            head = head[1:]
+
+        dirpath = tempfile.mkdtemp()
+        if head:
+            dirpath = os.path.join(dirpath, head)
+        # Assume there is no issue creating dirs in this temp dir.
+        os.makedirs(dirpath)
+
+        # Open the filename and write current text.
+        filename = os.path.join(dirpath, tail)
+        with open(filename, "w", encoding="utf-8") as fh:
+            fh.write(self.text)
+
+        def cleanup() -> None:
+            shutil.rmtree(dirpath)
+
+        return filename, cleanup
+
+    def open_in_editor(self, validate_and_handle: bool = False) -> asyncio.Task[None]:
+        """
+        Open code in editor.
+
+        This returns a future, and runs in a thread executor.
+        """
+        if self.read_only():
+            raise EditReadOnlyBuffer()
+
+        # Write current text to temporary file
+        if self.tempfile:
+            filename, cleanup_func = self._editor_complex_tempfile()
+        else:
+            filename, cleanup_func = self._editor_simple_tempfile()
+
+        async def run() -> None:
+            try:
+                # Open in editor
+                # (We need to use `run_in_terminal`, because not all editors go to
+                # the alternate screen buffer, and some could influence the cursor
+                # position.)
+                success = await run_in_terminal(
+                    lambda: self._open_file_in_editor(filename), in_executor=True
+                )
+
+                # Read content again.
+                if success:
+                    with open(filename, "rb") as f:
+                        text = f.read().decode("utf-8")
+
+                        # Drop trailing newline. (Editors are supposed to add it at the
+                        # end, but we don't need it.)
+                        if text.endswith("\n"):
+                            text = text[:-1]
+
+                        self.document = Document(text=text, cursor_position=len(text))
+
+                    # Accept the input.
+                    if validate_and_handle:
+                        self.validate_and_handle()
+
+            finally:
+                # Clean up temp dir/file.
+                cleanup_func()
+
+        return get_app().create_background_task(run())
+
+    def _open_file_in_editor(self, filename: str) -> bool:
+        """
+        Call editor executable.
+
+        Return True when we received a zero return code.
+        """
+        # If the 'VISUAL' or 'EDITOR' environment variable has been set, use that.
+        # Otherwise, fall back to the first available editor that we can find.
+        visual = os.environ.get("VISUAL")
+        editor = os.environ.get("EDITOR")
+
+        editors = [
+            visual,
+            editor,
+            # Order of preference.
+            "/usr/bin/editor",
+            "/usr/bin/nano",
+            "/usr/bin/pico",
+            "/usr/bin/vi",
+            "/usr/bin/emacs",
+        ]
+
+        for e in editors:
+            if e:
+                try:
+                    # Use 'shlex.split()', because $VISUAL can contain spaces
+                    # and quotes.
+                    returncode = subprocess.call(shlex.split(e) + [filename])
+                    return returncode == 0
+
+                except OSError:
+                    # Executable does not exist, try the next one.
+                    pass
+
+        return False
+
+    def start_completion(
+        self,
+        select_first: bool = False,
+        select_last: bool = False,
+        insert_common_part: bool = False,
+        complete_event: CompleteEvent | None = None,
+    ) -> None:
+        """
+        Start asynchronous autocompletion of this buffer.
+        (This will do nothing if a previous completion was still in progress.)
+        """
+        # Only one of these options can be selected.
+        assert select_first + select_last + insert_common_part <= 1
+
+        get_app().create_background_task(
+            self._async_completer(
+                select_first=select_first,
+                select_last=select_last,
+                insert_common_part=insert_common_part,
+                complete_event=complete_event
+                or CompleteEvent(completion_requested=True),
+            )
+        )
+
+    def _create_completer_coroutine(self) -> Callable[..., Coroutine[Any, Any, None]]:
+        """
+        Create function for asynchronous autocompletion.
+
+        (This consumes the asynchronous completer generator, which possibly
+        runs the completion algorithm in another thread.)
+        """
+
+        def completion_does_nothing(document: Document, completion: Completion) -> bool:
+            """
+            Return `True` if applying this completion doesn't have any effect.
+            (When it doesn't insert any new text.
+            """
+            text_before_cursor = document.text_before_cursor
+            replaced_text = text_before_cursor[
+                len(text_before_cursor) + completion.start_position :
+            ]
+            return replaced_text == completion.text
+
+        @_only_one_at_a_time
+        async def async_completer(
+            select_first: bool = False,
+            select_last: bool = False,
+            insert_common_part: bool = False,
+            complete_event: CompleteEvent | None = None,
+        ) -> None:
+            document = self.document
+            complete_event = complete_event or CompleteEvent(text_inserted=True)
+
+            # Don't complete when we already have completions.
+            if self.complete_state or not self.completer:
+                return
+
+            # Create an empty CompletionState.
+            complete_state = CompletionState(original_document=self.document)
+            self.complete_state = complete_state
+
+            def proceed() -> bool:
+                """Keep retrieving completions. Input text has not yet changed
+                while generating completions."""
+                return self.complete_state == complete_state
+
+            refresh_needed = asyncio.Event()
+
+            async def refresh_while_loading() -> None:
+                """Background loop to refresh the UI at most 3 times a second
+                while the completion are loading. Calling
+                `on_completions_changed.fire()` for every completion that we
+                receive is too expensive when there are many completions. (We
+                could tune `Application.max_render_postpone_time` and
+                `Application.min_redraw_interval`, but having this here is a
+                better approach.)
+                """
+                while True:
+                    self.on_completions_changed.fire()
+                    refresh_needed.clear()
+                    await asyncio.sleep(0.3)
+                    await refresh_needed.wait()
+
+            refresh_task = asyncio.ensure_future(refresh_while_loading())
+            try:
+                # Load.
+                async with aclosing(
+                    self.completer.get_completions_async(document, complete_event)
+                ) as async_generator:
+                    async for completion in async_generator:
+                        complete_state.completions.append(completion)
+                        refresh_needed.set()
+
+                        # If the input text changes, abort.
+                        if not proceed():
+                            break
+
+                        # Always stop at 10k completions.
+                        if (
+                            len(complete_state.completions)
+                            >= self.max_number_of_completions
+                        ):
+                            break
+            finally:
+                refresh_task.cancel()
+
+                # Refresh one final time after we got everything.
+                self.on_completions_changed.fire()
+
+            completions = complete_state.completions
+
+            # When there is only one completion, which has nothing to add, ignore it.
+            if len(completions) == 1 and completion_does_nothing(
+                document, completions[0]
+            ):
+                del completions[:]
+
+            # Set completions if the text was not yet changed.
+            if proceed():
+                # When no completions were found, or when the user selected
+                # already a completion by using the arrow keys, don't do anything.
+                if (
+                    not self.complete_state
+                    or self.complete_state.complete_index is not None
+                ):
+                    return
+
+                # When there are no completions, reset completion state anyway.
+                if not completions:
+                    self.complete_state = None
+                    # Render the ui if the completion menu was shown
+                    # it is needed especially if there is one completion and it was deleted.
+                    self.on_completions_changed.fire()
+                    return
+
+                # Select first/last or insert common part, depending on the key
+                # binding. (For this we have to wait until all completions are
+                # loaded.)
+
+                if select_first:
+                    self.go_to_completion(0)
+
+                elif select_last:
+                    self.go_to_completion(len(completions) - 1)
+
+                elif insert_common_part:
+                    common_part = get_common_complete_suffix(document, completions)
+                    if common_part:
+                        # Insert the common part, update completions.
+                        self.insert_text(common_part)
+                        if len(completions) > 1:
+                            # (Don't call `async_completer` again, but
+                            # recalculate completions. See:
+                            # https://github.com/ipython/ipython/issues/9658)
+                            completions[:] = [
+                                c.new_completion_from_position(len(common_part))
+                                for c in completions
+                            ]
+
+                            self._set_completions(completions=completions)
+                        else:
+                            self.complete_state = None
+                    else:
+                        # When we were asked to insert the "common"
+                        # prefix, but there was no common suffix but
+                        # still exactly one match, then select the
+                        # first. (It could be that we have a completion
+                        # which does * expansion, like '*.py', with
+                        # exactly one match.)
+                        if len(completions) == 1:
+                            self.go_to_completion(0)
+
+            else:
+                # If the last operation was an insert, (not a delete), restart
+                # the completion coroutine.
+
+                if self.document.text_before_cursor == document.text_before_cursor:
+                    return  # Nothing changed.
+
+                if self.document.text_before_cursor.startswith(
+                    document.text_before_cursor
+                ):
+                    raise _Retry
+
+        return async_completer
+
+    def _create_auto_suggest_coroutine(self) -> Callable[[], Coroutine[Any, Any, None]]:
+        """
+        Create function for asynchronous auto suggestion.
+        (This can be in another thread.)
+        """
+
+        @_only_one_at_a_time
+        async def async_suggestor() -> None:
+            document = self.document
+
+            # Don't suggest when we already have a suggestion.
+            if self.suggestion or not self.auto_suggest:
+                return
+
+            suggestion = await self.auto_suggest.get_suggestion_async(self, document)
+
+            # Set suggestion only if the text was not yet changed.
+            if self.document == document:
+                # Set suggestion and redraw interface.
+                self.suggestion = suggestion
+                self.on_suggestion_set.fire()
+            else:
+                # Otherwise, restart thread.
+                raise _Retry
+
+        return async_suggestor
+
+    def _create_auto_validate_coroutine(
+        self,
+    ) -> Callable[[], Coroutine[Any, Any, None]]:
+        """
+        Create a function for asynchronous validation while typing.
+        (This can be in another thread.)
+        """
+
+        @_only_one_at_a_time
+        async def async_validator() -> None:
+            await self._validate_async()
+
+        return async_validator
+
+    def validate_and_handle(self) -> None:
+        """
+        Validate buffer and handle the accept action.
+        """
+        valid = self.validate(set_cursor=True)
+
+        # When the validation succeeded, accept the input.
+        if valid:
+            if self.accept_handler:
+                keep_text = self.accept_handler(self)
+            else:
+                keep_text = False
+
+            self.append_to_history()
+
+            if not keep_text:
+                self.reset()
+
+
+_T = TypeVar("_T", bound=Callable[..., Coroutine[Any, Any, None]])
+
+
+def _only_one_at_a_time(coroutine: _T) -> _T:
+    """
+    Decorator that only starts the coroutine only if the previous call has
+    finished. (Used to make sure that we have only one autocompleter, auto
+    suggestor and validator running at a time.)
+
+    When the coroutine raises `_Retry`, it is restarted.
+    """
+    running = False
+
+    @wraps(coroutine)
+    async def new_coroutine(*a: Any, **kw: Any) -> Any:
+        nonlocal running
+
+        # Don't start a new function, if the previous is still in progress.
+        if running:
+            return
+
+        running = True
+
+        try:
+            while True:
+                try:
+                    await coroutine(*a, **kw)
+                except _Retry:
+                    continue
+                else:
+                    return None
+        finally:
+            running = False
+
+    return cast(_T, new_coroutine)
+
+
+class _Retry(Exception):
+    "Retry in `_only_one_at_a_time`."
+
+
+def indent(buffer: Buffer, from_row: int, to_row: int, count: int = 1) -> None:
+    """
+    Indent text of a :class:`.Buffer` object.
+    """
+    current_row = buffer.document.cursor_position_row
+    current_col = buffer.document.cursor_position_col
+    line_range = range(from_row, to_row)
+
+    # Apply transformation.
+    indent_content = "    " * count
+    new_text = buffer.transform_lines(line_range, lambda l: indent_content + l)
+    buffer.document = Document(
+        new_text, Document(new_text).translate_row_col_to_index(current_row, 0)
+    )
+
+    # Place cursor in the same position in text after indenting
+    buffer.cursor_position += current_col + len(indent_content)
+
+
+def unindent(buffer: Buffer, from_row: int, to_row: int, count: int = 1) -> None:
+    """
+    Unindent text of a :class:`.Buffer` object.
+    """
+    current_row = buffer.document.cursor_position_row
+    current_col = buffer.document.cursor_position_col
+    line_range = range(from_row, to_row)
+
+    indent_content = "    " * count
+
+    def transform(text: str) -> str:
+        remove = indent_content
+        if text.startswith(remove):
+            return text[len(remove) :]
+        else:
+            return text.lstrip()
+
+    # Apply transformation.
+    new_text = buffer.transform_lines(line_range, transform)
+    buffer.document = Document(
+        new_text, Document(new_text).translate_row_col_to_index(current_row, 0)
+    )
+
+    # Place cursor in the same position in text after dedent
+    buffer.cursor_position += current_col - len(indent_content)
+
+
+def reshape_text(buffer: Buffer, from_row: int, to_row: int) -> None:
+    """
+    Reformat text, taking the width into account.
+    `to_row` is included.
+    (Vi 'gq' operator.)
+    """
+    lines = buffer.text.splitlines(True)
+    lines_before = lines[:from_row]
+    lines_after = lines[to_row + 1 :]
+    lines_to_reformat = lines[from_row : to_row + 1]
+
+    if lines_to_reformat:
+        # Take indentation from the first line.
+        match = re.search(r"^\s*", lines_to_reformat[0])
+        length = match.end() if match else 0  # `match` can't be None, actually.
+
+        indent = lines_to_reformat[0][:length].replace("\n", "")
+
+        # Now, take all the 'words' from the lines to be reshaped.
+        words = "".join(lines_to_reformat).split()
+
+        # And reshape.
+        width = (buffer.text_width or 80) - len(indent)
+        reshaped_text = [indent]
+        current_width = 0
+        for w in words:
+            if current_width:
+                if len(w) + current_width + 1 > width:
+                    reshaped_text.append("\n")
+                    reshaped_text.append(indent)
+                    current_width = 0
+                else:
+                    reshaped_text.append(" ")
+                    current_width += 1
+
+            reshaped_text.append(w)
+            current_width += len(w)
+
+        if reshaped_text[-1] != "\n":
+            reshaped_text.append("\n")
+
+        # Apply result.
+        buffer.document = Document(
+            text="".join(lines_before + reshaped_text + lines_after),
+            cursor_position=len("".join(lines_before + reshaped_text)),
+        )

lib/python3.12/site-packages/prompt_toolkit/cache.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from collections import deque
+from functools import wraps
+from typing import Any, Callable, Dict, Generic, Hashable, Tuple, TypeVar, cast
+
+__all__ = [
+    "SimpleCache",
+    "FastDictCache",
+    "memoized",
+]
+
+_T = TypeVar("_T", bound=Hashable)
+_U = TypeVar("_U")
+
+
+class SimpleCache(Generic[_T, _U]):
+    """
+    Very simple cache that discards the oldest item when the cache size is
+    exceeded.
+
+    :param maxsize: Maximum size of the cache. (Don't make it too big.)
+    """
+
+    def __init__(self, maxsize: int = 8) -> None:
+        assert maxsize > 0
+
+        self._data: dict[_T, _U] = {}
+        self._keys: deque[_T] = deque()
+        self.maxsize: int = maxsize
+
+    def get(self, key: _T, getter_func: Callable[[], _U]) -> _U:
+        """
+        Get object from the cache.
+        If not found, call `getter_func` to resolve it, and put that on the top
+        of the cache instead.
+        """
+        # Look in cache first.
+        try:
+            return self._data[key]
+        except KeyError:
+            # Not found? Get it.
+            value = getter_func()
+            self._data[key] = value
+            self._keys.append(key)
+
+            # Remove the oldest key when the size is exceeded.
+            if len(self._data) > self.maxsize:
+                key_to_remove = self._keys.popleft()
+                if key_to_remove in self._data:
+                    del self._data[key_to_remove]
+
+            return value
+
+    def clear(self) -> None:
+        "Clear cache."
+        self._data = {}
+        self._keys = deque()
+
+
+_K = TypeVar("_K", bound=Tuple[Hashable, ...])
+_V = TypeVar("_V")
+
+
+class FastDictCache(Dict[_K, _V]):
+    """
+    Fast, lightweight cache which keeps at most `size` items.
+    It will discard the oldest items in the cache first.
+
+    The cache is a dictionary, which doesn't keep track of access counts.
+    It is perfect to cache little immutable objects which are not expensive to
+    create, but where a dictionary lookup is still much faster than an object
+    instantiation.
+
+    :param get_value: Callable that's called in case of a missing key.
+    """
+
+    # NOTE: This cache is used to cache `prompt_toolkit.layout.screen.Char` and
+    #       `prompt_toolkit.Document`. Make sure to keep this really lightweight.
+    #       Accessing the cache should stay faster than instantiating new
+    #       objects.
+    #       (Dictionary lookups are really fast.)
+    #       SimpleCache is still required for cases where the cache key is not
+    #       the same as the arguments given to the function that creates the
+    #       value.)
+    def __init__(self, get_value: Callable[..., _V], size: int = 1000000) -> None:
+        assert size > 0
+
+        self._keys: deque[_K] = deque()
+        self.get_value = get_value
+        self.size = size
+
+    def __missing__(self, key: _K) -> _V:
+        # Remove the oldest key when the size is exceeded.
+        if len(self) > self.size:
+            key_to_remove = self._keys.popleft()
+            if key_to_remove in self:
+                del self[key_to_remove]
+
+        result = self.get_value(*key)
+        self[key] = result
+        self._keys.append(key)
+        return result
+
+
+_F = TypeVar("_F", bound=Callable[..., object])
+
+
+def memoized(maxsize: int = 1024) -> Callable[[_F], _F]:
+    """
+    Memoization decorator for immutable classes and pure functions.
+    """
+
+    def decorator(obj: _F) -> _F:
+        cache: SimpleCache[Hashable, Any] = SimpleCache(maxsize=maxsize)
+
+        @wraps(obj)
+        def new_callable(*a: Any, **kw: Any) -> Any:
+            def create_new() -> Any:
+                return obj(*a, **kw)
+
+            key = (a, tuple(sorted(kw.items())))
+            return cache.get(key, create_new)
+
+        return cast(_F, new_callable)
+
+    return decorator

lib/python3.12/site-packages/prompt_toolkit/contrib/completers/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .system import SystemCompleter
+
+__all__ = ["SystemCompleter"]

lib/python3.12/site-packages/prompt_toolkit/contrib/completers/system.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from prompt_toolkit.completion.filesystem import ExecutableCompleter, PathCompleter
+from prompt_toolkit.contrib.regular_languages.compiler import compile
+from prompt_toolkit.contrib.regular_languages.completion import GrammarCompleter
+
+__all__ = [
+    "SystemCompleter",
+]
+
+
+class SystemCompleter(GrammarCompleter):
+    """
+    Completer for system commands.
+    """
+
+    def __init__(self) -> None:
+        # Compile grammar.
+        g = compile(
+            r"""
+                # First we have an executable.
+                (?P<executable>[^\s]+)
+
+                # Ignore literals in between.
+                (
+                    \s+
+                    ("[^"]*" | '[^']*' | [^'"]+ )
+                )*
+
+                \s+
+
+                # Filename as parameters.
+                (
+                    (?P<filename>[^\s]+) |
+                    "(?P<double_quoted_filename>[^\s]+)" |
+                    '(?P<single_quoted_filename>[^\s]+)'
+                )
+            """,
+            escape_funcs={
+                "double_quoted_filename": (lambda string: string.replace('"', '\\"')),
+                "single_quoted_filename": (lambda string: string.replace("'", "\\'")),
+            },
+            unescape_funcs={
+                "double_quoted_filename": (
+                    lambda string: string.replace('\\"', '"')
+                ),  # XXX: not entirely correct.
+                "single_quoted_filename": (lambda string: string.replace("\\'", "'")),
+            },
+        )
+
+        # Create GrammarCompleter
+        super().__init__(
+            g,
+            {
+                "executable": ExecutableCompleter(),
+                "filename": PathCompleter(only_directories=False, expanduser=True),
+                "double_quoted_filename": PathCompleter(
+                    only_directories=False, expanduser=True
+                ),
+                "single_quoted_filename": PathCompleter(
+                    only_directories=False, expanduser=True
+                ),
+            },
+        )

lib/python3.12/site-packages/prompt_toolkit/contrib/regular_languages/__init__.py

@@ -0,0 +1,80 @@
+r"""
+Tool for expressing the grammar of an input as a regular language.
+==================================================================
+
+The grammar for the input of many simple command line interfaces can be
+expressed by a regular language. Examples are PDB (the Python debugger); a
+simple (bash-like) shell with "pwd", "cd", "cat" and "ls" commands; arguments
+that you can pass to an executable; etc. It is possible to use regular
+expressions for validation and parsing of such a grammar. (More about regular
+languages: http://en.wikipedia.org/wiki/Regular_language)
+
+Example
+-------
+
+Let's take the pwd/cd/cat/ls example. We want to have a shell that accepts
+these three commands. "cd" is followed by a quoted directory name and "cat" is
+followed by a quoted file name. (We allow quotes inside the filename when
+they're escaped with a backslash.) We could define the grammar using the
+following regular expression::
+
+    grammar = \s* (
+        pwd |
+        ls |
+        (cd  \s+ " ([^"]|\.)+ ") |
+        (cat \s+ " ([^"]|\.)+ ")
+    ) \s*
+
+
+What can we do with this grammar?
+---------------------------------
+
+- Syntax highlighting: We could use this for instance to give file names
+                       different color.
+- Parse the result: .. We can extract the file names and commands by using a
+                       regular expression with named groups.
+- Input validation: .. Don't accept anything that does not match this grammar.
+                       When combined with a parser, we can also recursively do
+                       filename validation (and accept only existing files.)
+- Autocompletion: .... Each part of the grammar can have its own autocompleter.
+                       "cat" has to be completed using file names, while "cd"
+                       has to be completed using directory names.
+
+How does it work?
+-----------------
+
+As a user of this library, you have to define the grammar of the input as a
+regular expression. The parts of this grammar where autocompletion, validation
+or any other processing is required need to be marked using a regex named
+group. Like ``(?P<varname>...)`` for instance.
+
+When the input is processed for validation (for instance), the regex will
+execute, the named group is captured, and the validator associated with this
+named group will test the captured string.
+
+There is one tricky bit:
+
+    Often we operate on incomplete input (this is by definition the case for
+    autocompletion) and we have to decide for the cursor position in which
+    possible state the grammar it could be and in which way variables could be
+    matched up to that point.
+
+To solve this problem, the compiler takes the original regular expression and
+translates it into a set of other regular expressions which each match certain
+prefixes of the original regular expression. We generate one prefix regular
+expression for every named variable (with this variable being the end of that
+expression).
+
+
+TODO: some examples of:
+    - How to create a highlighter from this grammar.
+    - How to create a validator from this grammar.
+    - How to create an autocompleter from this grammar.
+    - How to create a parser from this grammar.
+"""
+
+from __future__ import annotations
+
+from .compiler import compile
+
+__all__ = ["compile"]

lib/python3.12/site-packages/prompt_toolkit/contrib/regular_languages/compiler.py

@@ -0,0 +1,579 @@
+r"""
+Compiler for a regular grammar.
+
+Example usage::
+
+    # Create and compile grammar.
+    p = compile('add \s+ (?P<var1>[^\s]+)  \s+  (?P<var2>[^\s]+)')
+
+    # Match input string.
+    m = p.match('add 23 432')
+
+    # Get variables.
+    m.variables().get('var1')  # Returns "23"
+    m.variables().get('var2')  # Returns "432"
+
+
+Partial matches are possible::
+
+    # Create and compile grammar.
+    p = compile('''
+        # Operators with two arguments.
+        ((?P<operator1>[^\s]+)  \s+ (?P<var1>[^\s]+)  \s+  (?P<var2>[^\s]+)) |
+
+        # Operators with only one arguments.
+        ((?P<operator2>[^\s]+)  \s+ (?P<var1>[^\s]+))
+    ''')
+
+    # Match partial input string.
+    m = p.match_prefix('add 23')
+
+    # Get variables. (Notice that both operator1 and operator2 contain the
+    # value "add".) This is because our input is incomplete, and we don't know
+    # yet in which rule of the regex we we'll end up. It could also be that
+    # `operator1` and `operator2` have a different autocompleter and we want to
+    # call all possible autocompleters that would result in valid input.)
+    m.variables().get('var1')  # Returns "23"
+    m.variables().get('operator1')  # Returns "add"
+    m.variables().get('operator2')  # Returns "add"
+
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Callable, Dict, Iterable, Iterator, Pattern, TypeVar, overload
+from typing import Match as RegexMatch
+
+from .regex_parser import (
+    AnyNode,
+    Lookahead,
+    Node,
+    NodeSequence,
+    Regex,
+    Repeat,
+    Variable,
+    parse_regex,
+    tokenize_regex,
+)
+
+__all__ = ["compile", "Match", "Variables"]
+
+
+# Name of the named group in the regex, matching trailing input.
+# (Trailing input is when the input contains characters after the end of the
+# expression has been matched.)
+_INVALID_TRAILING_INPUT = "invalid_trailing"
+
+EscapeFuncDict = Dict[str, Callable[[str], str]]
+
+
+class _CompiledGrammar:
+    """
+    Compiles a grammar. This will take the parse tree of a regular expression
+    and compile the grammar.
+
+    :param root_node: :class~`.regex_parser.Node` instance.
+    :param escape_funcs: `dict` mapping variable names to escape callables.
+    :param unescape_funcs: `dict` mapping variable names to unescape callables.
+    """
+
+    def __init__(
+        self,
+        root_node: Node,
+        escape_funcs: EscapeFuncDict | None = None,
+        unescape_funcs: EscapeFuncDict | None = None,
+    ) -> None:
+        self.root_node = root_node
+        self.escape_funcs = escape_funcs or {}
+        self.unescape_funcs = unescape_funcs or {}
+
+        #: Dictionary that will map the regex names to Node instances.
+        self._group_names_to_nodes: dict[
+            str, str
+        ] = {}  # Maps regex group names to varnames.
+        counter = [0]
+
+        def create_group_func(node: Variable) -> str:
+            name = f"n{counter[0]}"
+            self._group_names_to_nodes[name] = node.varname
+            counter[0] += 1
+            return name
+
+        # Compile regex strings.
+        self._re_pattern = f"^{self._transform(root_node, create_group_func)}$"
+        self._re_prefix_patterns = list(
+            self._transform_prefix(root_node, create_group_func)
+        )
+
+        # Compile the regex itself.
+        flags = re.DOTALL  # Note that we don't need re.MULTILINE! (^ and $
+        # still represent the start and end of input text.)
+        self._re = re.compile(self._re_pattern, flags)
+        self._re_prefix = [re.compile(t, flags) for t in self._re_prefix_patterns]
+
+        # We compile one more set of regexes, similar to `_re_prefix`, but accept any trailing
+        # input. This will ensure that we can still highlight the input correctly, even when the
+        # input contains some additional characters at the end that don't match the grammar.)
+        self._re_prefix_with_trailing_input = [
+            re.compile(
+                r"(?:{})(?P<{}>.*?)$".format(t.rstrip("$"), _INVALID_TRAILING_INPUT),
+                flags,
+            )
+            for t in self._re_prefix_patterns
+        ]
+
+    def escape(self, varname: str, value: str) -> str:
+        """
+        Escape `value` to fit in the place of this variable into the grammar.
+        """
+        f = self.escape_funcs.get(varname)
+        return f(value) if f else value
+
+    def unescape(self, varname: str, value: str) -> str:
+        """
+        Unescape `value`.
+        """
+        f = self.unescape_funcs.get(varname)
+        return f(value) if f else value
+
+    @classmethod
+    def _transform(
+        cls, root_node: Node, create_group_func: Callable[[Variable], str]
+    ) -> str:
+        """
+        Turn a :class:`Node` object into a regular expression.
+
+        :param root_node: The :class:`Node` instance for which we generate the grammar.
+        :param create_group_func: A callable which takes a `Node` and returns the next
+            free name for this node.
+        """
+
+        def transform(node: Node) -> str:
+            # Turn `AnyNode` into an OR.
+            if isinstance(node, AnyNode):
+                return "(?:{})".format("|".join(transform(c) for c in node.children))
+
+            # Concatenate a `NodeSequence`
+            elif isinstance(node, NodeSequence):
+                return "".join(transform(c) for c in node.children)
+
+            # For Regex and Lookahead nodes, just insert them literally.
+            elif isinstance(node, Regex):
+                return node.regex
+
+            elif isinstance(node, Lookahead):
+                before = "(?!" if node.negative else "(="
+                return before + transform(node.childnode) + ")"
+
+            # A `Variable` wraps the children into a named group.
+            elif isinstance(node, Variable):
+                return f"(?P<{create_group_func(node)}>{transform(node.childnode)})"
+
+            # `Repeat`.
+            elif isinstance(node, Repeat):
+                if node.max_repeat is None:
+                    if node.min_repeat == 0:
+                        repeat_sign = "*"
+                    elif node.min_repeat == 1:
+                        repeat_sign = "+"
+                else:
+                    repeat_sign = "{%i,%s}" % (
+                        node.min_repeat,
+                        ("" if node.max_repeat is None else str(node.max_repeat)),
+                    )
+
+                return "(?:{}){}{}".format(
+                    transform(node.childnode),
+                    repeat_sign,
+                    ("" if node.greedy else "?"),
+                )
+            else:
+                raise TypeError(f"Got {node!r}")
+
+        return transform(root_node)
+
+    @classmethod
+    def _transform_prefix(
+        cls, root_node: Node, create_group_func: Callable[[Variable], str]
+    ) -> Iterable[str]:
+        """
+        Yield all the regular expressions matching a prefix of the grammar
+        defined by the `Node` instance.
+
+        For each `Variable`, one regex pattern will be generated, with this
+        named group at the end. This is required because a regex engine will
+        terminate once a match is found. For autocompletion however, we need
+        the matches for all possible paths, so that we can provide completions
+        for each `Variable`.
+
+        - So, in the case of an `Any` (`A|B|C)', we generate a pattern for each
+          clause. This is one for `A`, one for `B` and one for `C`. Unless some
+          groups don't contain a `Variable`, then these can be merged together.
+        - In the case of a `NodeSequence` (`ABC`), we generate a pattern for
+          each prefix that ends with a variable, and one pattern for the whole
+          sequence. So, that's one for `A`, one for `AB` and one for `ABC`.
+
+        :param root_node: The :class:`Node` instance for which we generate the grammar.
+        :param create_group_func: A callable which takes a `Node` and returns the next
+            free name for this node.
+        """
+
+        def contains_variable(node: Node) -> bool:
+            if isinstance(node, Regex):
+                return False
+            elif isinstance(node, Variable):
+                return True
+            elif isinstance(node, (Lookahead, Repeat)):
+                return contains_variable(node.childnode)
+            elif isinstance(node, (NodeSequence, AnyNode)):
+                return any(contains_variable(child) for child in node.children)
+
+            return False
+
+        def transform(node: Node) -> Iterable[str]:
+            # Generate separate pattern for all terms that contain variables
+            # within this OR. Terms that don't contain a variable can be merged
+            # together in one pattern.
+            if isinstance(node, AnyNode):
+                # If we have a definition like:
+                #           (?P<name> .*)  | (?P<city> .*)
+                # Then we want to be able to generate completions for both the
+                # name as well as the city. We do this by yielding two
+                # different regular expressions, because the engine won't
+                # follow multiple paths, if multiple are possible.
+                children_with_variable = []
+                children_without_variable = []
+                for c in node.children:
+                    if contains_variable(c):
+                        children_with_variable.append(c)
+                    else:
+                        children_without_variable.append(c)
+
+                for c in children_with_variable:
+                    yield from transform(c)
+
+                # Merge options without variable together.
+                if children_without_variable:
+                    yield "|".join(
+                        r for c in children_without_variable for r in transform(c)
+                    )
+
+            # For a sequence, generate a pattern for each prefix that ends with
+            # a variable + one pattern of the complete sequence.
+            # (This is because, for autocompletion, we match the text before
+            # the cursor, and completions are given for the variable that we
+            # match right before the cursor.)
+            elif isinstance(node, NodeSequence):
+                # For all components in the sequence, compute prefix patterns,
+                # as well as full patterns.
+                complete = [cls._transform(c, create_group_func) for c in node.children]
+                prefixes = [list(transform(c)) for c in node.children]
+                variable_nodes = [contains_variable(c) for c in node.children]
+
+                # If any child is contains a variable, we should yield a
+                # pattern up to that point, so that we are sure this will be
+                # matched.
+                for i in range(len(node.children)):
+                    if variable_nodes[i]:
+                        for c_str in prefixes[i]:
+                            yield "".join(complete[:i]) + c_str
+
+                # If there are non-variable nodes, merge all the prefixes into
+                # one pattern. If the input is: "[part1] [part2] [part3]", then
+                # this gets compiled into:
+                #  (complete1 + (complete2 + (complete3  | partial3) | partial2) | partial1 )
+                # For nodes that contain a variable, we skip the "|partial"
+                # part here, because thees are matched with the previous
+                # patterns.
+                if not all(variable_nodes):
+                    result = []
+
+                    # Start with complete patterns.
+                    for i in range(len(node.children)):
+                        result.append("(?:")
+                        result.append(complete[i])
+
+                    # Add prefix patterns.
+                    for i in range(len(node.children) - 1, -1, -1):
+                        if variable_nodes[i]:
+                            # No need to yield a prefix for this one, we did
+                            # the variable prefixes earlier.
+                            result.append(")")
+                        else:
+                            result.append("|(?:")
+                            # If this yields multiple, we should yield all combinations.
+                            assert len(prefixes[i]) == 1
+                            result.append(prefixes[i][0])
+                            result.append("))")
+
+                    yield "".join(result)
+
+            elif isinstance(node, Regex):
+                yield f"(?:{node.regex})?"
+
+            elif isinstance(node, Lookahead):
+                if node.negative:
+                    yield f"(?!{cls._transform(node.childnode, create_group_func)})"
+                else:
+                    # Not sure what the correct semantics are in this case.
+                    # (Probably it's not worth implementing this.)
+                    raise Exception("Positive lookahead not yet supported.")
+
+            elif isinstance(node, Variable):
+                # (Note that we should not append a '?' here. the 'transform'
+                # method will already recursively do that.)
+                for c_str in transform(node.childnode):
+                    yield f"(?P<{create_group_func(node)}>{c_str})"
+
+            elif isinstance(node, Repeat):
+                # If we have a repetition of 8 times. That would mean that the
+                # current input could have for instance 7 times a complete
+                # match, followed by a partial match.
+                prefix = cls._transform(node.childnode, create_group_func)
+
+                if node.max_repeat == 1:
+                    yield from transform(node.childnode)
+                else:
+                    for c_str in transform(node.childnode):
+                        if node.max_repeat:
+                            repeat_sign = "{,%i}" % (node.max_repeat - 1)
+                        else:
+                            repeat_sign = "*"
+                        yield "(?:{}){}{}{}".format(
+                            prefix,
+                            repeat_sign,
+                            ("" if node.greedy else "?"),
+                            c_str,
+                        )
+
+            else:
+                raise TypeError(f"Got {node!r}")
+
+        for r in transform(root_node):
+            yield f"^(?:{r})$"
+
+    def match(self, string: str) -> Match | None:
+        """
+        Match the string with the grammar.
+        Returns a :class:`Match` instance or `None` when the input doesn't match the grammar.
+
+        :param string: The input string.
+        """
+        m = self._re.match(string)
+
+        if m:
+            return Match(
+                string, [(self._re, m)], self._group_names_to_nodes, self.unescape_funcs
+            )
+        return None
+
+    def match_prefix(self, string: str) -> Match | None:
+        """
+        Do a partial match of the string with the grammar. The returned
+        :class:`Match` instance can contain multiple representations of the
+        match. This will never return `None`. If it doesn't match at all, the "trailing input"
+        part will capture all of the input.
+
+        :param string: The input string.
+        """
+        # First try to match using `_re_prefix`. If nothing is found, use the patterns that
+        # also accept trailing characters.
+        for patterns in [self._re_prefix, self._re_prefix_with_trailing_input]:
+            matches = [(r, r.match(string)) for r in patterns]
+            matches2 = [(r, m) for r, m in matches if m]
+
+            if matches2 != []:
+                return Match(
+                    string, matches2, self._group_names_to_nodes, self.unescape_funcs
+                )
+
+        return None
+
+
+class Match:
+    """
+    :param string: The input string.
+    :param re_matches: List of (compiled_re_pattern, re_match) tuples.
+    :param group_names_to_nodes: Dictionary mapping all the re group names to the matching Node instances.
+    """
+
+    def __init__(
+        self,
+        string: str,
+        re_matches: list[tuple[Pattern[str], RegexMatch[str]]],
+        group_names_to_nodes: dict[str, str],
+        unescape_funcs: dict[str, Callable[[str], str]],
+    ):
+        self.string = string
+        self._re_matches = re_matches
+        self._group_names_to_nodes = group_names_to_nodes
+        self._unescape_funcs = unescape_funcs
+
+    def _nodes_to_regs(self) -> list[tuple[str, tuple[int, int]]]:
+        """
+        Return a list of (varname, reg) tuples.
+        """
+
+        def get_tuples() -> Iterable[tuple[str, tuple[int, int]]]:
+            for r, re_match in self._re_matches:
+                for group_name, group_index in r.groupindex.items():
+                    if group_name != _INVALID_TRAILING_INPUT:
+                        regs = re_match.regs
+                        reg = regs[group_index]
+                        node = self._group_names_to_nodes[group_name]
+                        yield (node, reg)
+
+        return list(get_tuples())
+
+    def _nodes_to_values(self) -> list[tuple[str, str, tuple[int, int]]]:
+        """
+        Returns list of (Node, string_value) tuples.
+        """
+
+        def is_none(sl: tuple[int, int]) -> bool:
+            return sl[0] == -1 and sl[1] == -1
+
+        def get(sl: tuple[int, int]) -> str:
+            return self.string[sl[0] : sl[1]]
+
+        return [
+            (varname, get(slice), slice)
+            for varname, slice in self._nodes_to_regs()
+            if not is_none(slice)
+        ]
+
+    def _unescape(self, varname: str, value: str) -> str:
+        unwrapper = self._unescape_funcs.get(varname)
+        return unwrapper(value) if unwrapper else value
+
+    def variables(self) -> Variables:
+        """
+        Returns :class:`Variables` instance.
+        """
+        return Variables(
+            [(k, self._unescape(k, v), sl) for k, v, sl in self._nodes_to_values()]
+        )
+
+    def trailing_input(self) -> MatchVariable | None:
+        """
+        Get the `MatchVariable` instance, representing trailing input, if there is any.
+        "Trailing input" is input at the end that does not match the grammar anymore, but
+        when this is removed from the end of the input, the input would be a valid string.
+        """
+        slices: list[tuple[int, int]] = []
+
+        # Find all regex group for the name _INVALID_TRAILING_INPUT.
+        for r, re_match in self._re_matches:
+            for group_name, group_index in r.groupindex.items():
+                if group_name == _INVALID_TRAILING_INPUT:
+                    slices.append(re_match.regs[group_index])
+
+        # Take the smallest part. (Smaller trailing text means that a larger input has
+        # been matched, so that is better.)
+        if slices:
+            slice = (max(i[0] for i in slices), max(i[1] for i in slices))
+            value = self.string[slice[0] : slice[1]]
+            return MatchVariable("<trailing_input>", value, slice)
+        return None
+
+    def end_nodes(self) -> Iterable[MatchVariable]:
+        """
+        Yields `MatchVariable` instances for all the nodes having their end
+        position at the end of the input string.
+        """
+        for varname, reg in self._nodes_to_regs():
+            # If this part goes until the end of the input string.
+            if reg[1] == len(self.string):
+                value = self._unescape(varname, self.string[reg[0] : reg[1]])
+                yield MatchVariable(varname, value, (reg[0], reg[1]))
+
+
+_T = TypeVar("_T")
+
+
+class Variables:
+    def __init__(self, tuples: list[tuple[str, str, tuple[int, int]]]) -> None:
+        #: List of (varname, value, slice) tuples.
+        self._tuples = tuples
+
+    def __repr__(self) -> str:
+        return "{}({})".format(
+            self.__class__.__name__,
+            ", ".join(f"{k}={v!r}" for k, v, _ in self._tuples),
+        )
+
+    @overload
+    def get(self, key: str) -> str | None: ...
+
+    @overload
+    def get(self, key: str, default: str | _T) -> str | _T: ...
+
+    def get(self, key: str, default: str | _T | None = None) -> str | _T | None:
+        items = self.getall(key)
+        return items[0] if items else default
+
+    def getall(self, key: str) -> list[str]:
+        return [v for k, v, _ in self._tuples if k == key]
+
+    def __getitem__(self, key: str) -> str | None:
+        return self.get(key)
+
+    def __iter__(self) -> Iterator[MatchVariable]:
+        """
+        Yield `MatchVariable` instances.
+        """
+        for varname, value, slice in self._tuples:
+            yield MatchVariable(varname, value, slice)
+
+
+class MatchVariable:
+    """
+    Represents a match of a variable in the grammar.
+
+    :param varname: (string) Name of the variable.
+    :param value: (string) Value of this variable.
+    :param slice: (start, stop) tuple, indicating the position of this variable
+                  in the input string.
+    """
+
+    def __init__(self, varname: str, value: str, slice: tuple[int, int]) -> None:
+        self.varname = varname
+        self.value = value
+        self.slice = slice
+
+        self.start = self.slice[0]
+        self.stop = self.slice[1]
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.varname!r}, {self.value!r})"
+
+
+def compile(
+    expression: str,
+    escape_funcs: EscapeFuncDict | None = None,
+    unescape_funcs: EscapeFuncDict | None = None,
+) -> _CompiledGrammar:
+    """
+    Compile grammar (given as regex string), returning a `CompiledGrammar`
+    instance.
+    """
+    return _compile_from_parse_tree(
+        parse_regex(tokenize_regex(expression)),
+        escape_funcs=escape_funcs,
+        unescape_funcs=unescape_funcs,
+    )
+
+
+def _compile_from_parse_tree(
+    root_node: Node,
+    escape_funcs: EscapeFuncDict | None = None,
+    unescape_funcs: EscapeFuncDict | None = None,
+) -> _CompiledGrammar:
+    """
+    Compile grammar (given as parse tree), returning a `CompiledGrammar`
+    instance.
+    """
+    return _CompiledGrammar(
+        root_node, escape_funcs=escape_funcs, unescape_funcs=unescape_funcs
+    )

lib/python3.12/site-packages/prompt_toolkit/contrib/regular_languages/completion.py

@@ -0,0 +1,100 @@
+"""
+Completer for a regular grammar.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from prompt_toolkit.completion import CompleteEvent, Completer, Completion
+from prompt_toolkit.document import Document
+
+from .compiler import Match, _CompiledGrammar
+
+__all__ = [
+    "GrammarCompleter",
+]
+
+
+class GrammarCompleter(Completer):
+    """
+    Completer which can be used for autocompletion according to variables in
+    the grammar. Each variable can have a different autocompleter.
+
+    :param compiled_grammar: `GrammarCompleter` instance.
+    :param completers: `dict` mapping variable names of the grammar to the
+                       `Completer` instances to be used for each variable.
+    """
+
+    def __init__(
+        self, compiled_grammar: _CompiledGrammar, completers: dict[str, Completer]
+    ) -> None:
+        self.compiled_grammar = compiled_grammar
+        self.completers = completers
+
+    def get_completions(
+        self, document: Document, complete_event: CompleteEvent
+    ) -> Iterable[Completion]:
+        m = self.compiled_grammar.match_prefix(document.text_before_cursor)
+
+        if m:
+            yield from self._remove_duplicates(
+                self._get_completions_for_match(m, complete_event)
+            )
+
+    def _get_completions_for_match(
+        self, match: Match, complete_event: CompleteEvent
+    ) -> Iterable[Completion]:
+        """
+        Yield all the possible completions for this input string.
+        (The completer assumes that the cursor position was at the end of the
+        input string.)
+        """
+        for match_variable in match.end_nodes():
+            varname = match_variable.varname
+            start = match_variable.start
+
+            completer = self.completers.get(varname)
+
+            if completer:
+                text = match_variable.value
+
+                # Unwrap text.
+                unwrapped_text = self.compiled_grammar.unescape(varname, text)
+
+                # Create a document, for the completions API (text/cursor_position)
+                document = Document(unwrapped_text, len(unwrapped_text))
+
+                # Call completer
+                for completion in completer.get_completions(document, complete_event):
+                    new_text = (
+                        unwrapped_text[: len(text) + completion.start_position]
+                        + completion.text
+                    )
+
+                    # Wrap again.
+                    yield Completion(
+                        text=self.compiled_grammar.escape(varname, new_text),
+                        start_position=start - len(match.string),
+                        display=completion.display,
+                        display_meta=completion.display_meta,
+                    )
+
+    def _remove_duplicates(self, items: Iterable[Completion]) -> Iterable[Completion]:
+        """
+        Remove duplicates, while keeping the order.
+        (Sometimes we have duplicates, because the there several matches of the
+        same grammar, each yielding similar completions.)
+        """
+
+        def hash_completion(completion: Completion) -> tuple[str, int]:
+            return completion.text, completion.start_position
+
+        yielded_so_far: set[tuple[str, int]] = set()
+
+        for completion in items:
+            hash_value = hash_completion(completion)
+
+            if hash_value not in yielded_so_far:
+                yielded_so_far.add(hash_value)
+                yield completion

lib/python3.12/site-packages/prompt_toolkit/contrib/regular_languages/lexer.py

@@ -0,0 +1,94 @@
+"""
+`GrammarLexer` is compatible with other lexers and can be used to highlight
+the input using a regular grammar with annotations.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from prompt_toolkit.document import Document
+from prompt_toolkit.formatted_text.base import StyleAndTextTuples
+from prompt_toolkit.formatted_text.utils import split_lines
+from prompt_toolkit.lexers import Lexer
+
+from .compiler import _CompiledGrammar
+
+__all__ = [
+    "GrammarLexer",
+]
+
+
+class GrammarLexer(Lexer):
+    """
+    Lexer which can be used for highlighting of fragments according to variables in the grammar.
+
+    (It does not actual lexing of the string, but it exposes an API, compatible
+    with the Pygments lexer class.)
+
+    :param compiled_grammar: Grammar as returned by the `compile()` function.
+    :param lexers: Dictionary mapping variable names of the regular grammar to
+                   the lexers that should be used for this part. (This can
+                   call other lexers recursively.) If you wish a part of the
+                   grammar to just get one fragment, use a
+                   `prompt_toolkit.lexers.SimpleLexer`.
+    """
+
+    def __init__(
+        self,
+        compiled_grammar: _CompiledGrammar,
+        default_style: str = "",
+        lexers: dict[str, Lexer] | None = None,
+    ) -> None:
+        self.compiled_grammar = compiled_grammar
+        self.default_style = default_style
+        self.lexers = lexers or {}
+
+    def _get_text_fragments(self, text: str) -> StyleAndTextTuples:
+        m = self.compiled_grammar.match_prefix(text)
+
+        if m:
+            characters: StyleAndTextTuples = [(self.default_style, c) for c in text]
+
+            for v in m.variables():
+                # If we have a `Lexer` instance for this part of the input.
+                # Tokenize recursively and apply tokens.
+                lexer = self.lexers.get(v.varname)
+
+                if lexer:
+                    document = Document(text[v.start : v.stop])
+                    lexer_tokens_for_line = lexer.lex_document(document)
+                    text_fragments: StyleAndTextTuples = []
+                    for i in range(len(document.lines)):
+                        text_fragments.extend(lexer_tokens_for_line(i))
+                        text_fragments.append(("", "\n"))
+                    if text_fragments:
+                        text_fragments.pop()
+
+                    i = v.start
+                    for t, s, *_ in text_fragments:
+                        for c in s:
+                            if characters[i][0] == self.default_style:
+                                characters[i] = (t, characters[i][1])
+                            i += 1
+
+            # Highlight trailing input.
+            trailing_input = m.trailing_input()
+            if trailing_input:
+                for i in range(trailing_input.start, trailing_input.stop):
+                    characters[i] = ("class:trailing-input", characters[i][1])
+
+            return characters
+        else:
+            return [("", text)]
+
+    def lex_document(self, document: Document) -> Callable[[int], StyleAndTextTuples]:
+        lines = list(split_lines(self._get_text_fragments(document.text)))
+
+        def get_line(lineno: int) -> StyleAndTextTuples:
+            try:
+                return lines[lineno]
+            except IndexError:
+                return []
+
+        return get_line

lib/python3.12/site-packages/prompt_toolkit/contrib/regular_languages/regex_parser.py

@@ -0,0 +1,279 @@
+"""
+Parser for parsing a regular expression.
+Take a string representing a regular expression and return the root node of its
+parse tree.
+
+usage::
+
+    root_node = parse_regex('(hello|world)')
+
+Remarks:
+- The regex parser processes multiline, it ignores all whitespace and supports
+  multiple named groups with the same name and #-style comments.
+
+Limitations:
+- Lookahead is not supported.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = [
+    "Repeat",
+    "Variable",
+    "Regex",
+    "Lookahead",
+    "tokenize_regex",
+    "parse_regex",
+]
+
+
+class Node:
+    """
+    Base class for all the grammar nodes.
+    (You don't initialize this one.)
+    """
+
+    def __add__(self, other_node: Node) -> NodeSequence:
+        return NodeSequence([self, other_node])
+
+    def __or__(self, other_node: Node) -> AnyNode:
+        return AnyNode([self, other_node])
+
+
+class AnyNode(Node):
+    """
+    Union operation (OR operation) between several grammars. You don't
+    initialize this yourself, but it's a result of a "Grammar1 | Grammar2"
+    operation.
+    """
+
+    def __init__(self, children: list[Node]) -> None:
+        self.children = children
+
+    def __or__(self, other_node: Node) -> AnyNode:
+        return AnyNode(self.children + [other_node])
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.children!r})"
+
+
+class NodeSequence(Node):
+    """
+    Concatenation operation of several grammars. You don't initialize this
+    yourself, but it's a result of a "Grammar1 + Grammar2" operation.
+    """
+
+    def __init__(self, children: list[Node]) -> None:
+        self.children = children
+
+    def __add__(self, other_node: Node) -> NodeSequence:
+        return NodeSequence(self.children + [other_node])
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.children!r})"
+
+
+class Regex(Node):
+    """
+    Regular expression.
+    """
+
+    def __init__(self, regex: str) -> None:
+        re.compile(regex)  # Validate
+
+        self.regex = regex
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(/{self.regex}/)"
+
+
+class Lookahead(Node):
+    """
+    Lookahead expression.
+    """
+
+    def __init__(self, childnode: Node, negative: bool = False) -> None:
+        self.childnode = childnode
+        self.negative = negative
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.childnode!r})"
+
+
+class Variable(Node):
+    """
+    Mark a variable in the regular grammar. This will be translated into a
+    named group. Each variable can have his own completer, validator, etc..
+
+    :param childnode: The grammar which is wrapped inside this variable.
+    :param varname: String.
+    """
+
+    def __init__(self, childnode: Node, varname: str = "") -> None:
+        self.childnode = childnode
+        self.varname = varname
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(childnode={self.childnode!r}, varname={self.varname!r})"
+
+
+class Repeat(Node):
+    def __init__(
+        self,
+        childnode: Node,
+        min_repeat: int = 0,
+        max_repeat: int | None = None,
+        greedy: bool = True,
+    ) -> None:
+        self.childnode = childnode
+        self.min_repeat = min_repeat
+        self.max_repeat = max_repeat
+        self.greedy = greedy
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(childnode={self.childnode!r})"
+
+
+def tokenize_regex(input: str) -> list[str]:
+    """
+    Takes a string, representing a regular expression as input, and tokenizes
+    it.
+
+    :param input: string, representing a regular expression.
+    :returns: List of tokens.
+    """
+    # Regular expression for tokenizing other regular expressions.
+    p = re.compile(
+        r"""^(
+        \(\?P\<[a-zA-Z0-9_-]+\>  | # Start of named group.
+        \(\?#[^)]*\)             | # Comment
+        \(\?=                    | # Start of lookahead assertion
+        \(\?!                    | # Start of negative lookahead assertion
+        \(\?<=                   | # If preceded by.
+        \(\?<                    | # If not preceded by.
+        \(?:                     | # Start of group. (non capturing.)
+        \(                       | # Start of group.
+        \(?[iLmsux]              | # Flags.
+        \(?P=[a-zA-Z]+\)         | # Back reference to named group
+        \)                       | # End of group.
+        \{[^{}]*\}               | # Repetition
+        \*\? | \+\? | \?\?\      | # Non greedy repetition.
+        \* | \+ | \?             | # Repetition
+        \#.*\n                   | # Comment
+        \\. |
+
+        # Character group.
+        \[
+            ( [^\]\\]  |  \\.)*
+        \]                  |
+
+        [^(){}]             |
+        .
+    )""",
+        re.VERBOSE,
+    )
+
+    tokens = []
+
+    while input:
+        m = p.match(input)
+        if m:
+            token, input = input[: m.end()], input[m.end() :]
+            if not token.isspace():
+                tokens.append(token)
+        else:
+            raise Exception("Could not tokenize input regex.")
+
+    return tokens
+
+
+def parse_regex(regex_tokens: list[str]) -> Node:
+    """
+    Takes a list of tokens from the tokenizer, and returns a parse tree.
+    """
+    # We add a closing brace because that represents the final pop of the stack.
+    tokens: list[str] = [")"] + regex_tokens[::-1]
+
+    def wrap(lst: list[Node]) -> Node:
+        """Turn list into sequence when it contains several items."""
+        if len(lst) == 1:
+            return lst[0]
+        else:
+            return NodeSequence(lst)
+
+    def _parse() -> Node:
+        or_list: list[list[Node]] = []
+        result: list[Node] = []
+
+        def wrapped_result() -> Node:
+            if or_list == []:
+                return wrap(result)
+            else:
+                or_list.append(result)
+                return AnyNode([wrap(i) for i in or_list])
+
+        while tokens:
+            t = tokens.pop()
+
+            if t.startswith("(?P<"):
+                variable = Variable(_parse(), varname=t[4:-1])
+                result.append(variable)
+
+            elif t in ("*", "*?"):
+                greedy = t == "*"
+                result[-1] = Repeat(result[-1], greedy=greedy)
+
+            elif t in ("+", "+?"):
+                greedy = t == "+"
+                result[-1] = Repeat(result[-1], min_repeat=1, greedy=greedy)
+
+            elif t in ("?", "??"):
+                if result == []:
+                    raise Exception("Nothing to repeat." + repr(tokens))
+                else:
+                    greedy = t == "?"
+                    result[-1] = Repeat(
+                        result[-1], min_repeat=0, max_repeat=1, greedy=greedy
+                    )
+
+            elif t == "|":
+                or_list.append(result)
+                result = []
+
+            elif t in ("(", "(?:"):
+                result.append(_parse())
+
+            elif t == "(?!":
+                result.append(Lookahead(_parse(), negative=True))
+
+            elif t == "(?=":
+                result.append(Lookahead(_parse(), negative=False))
+
+            elif t == ")":
+                return wrapped_result()
+
+            elif t.startswith("#"):
+                pass
+
+            elif t.startswith("{"):
+                # TODO: implement!
+                raise Exception(f"{t}-style repetition not yet supported")
+
+            elif t.startswith("(?"):
+                raise Exception(f"{t!r} not supported")
+
+            elif t.isspace():
+                pass
+            else:
+                result.append(Regex(t))
+
+        raise Exception("Expecting ')' token")
+
+    result = _parse()
+
+    if len(tokens) != 0:
+        raise Exception("Unmatched parentheses.")
+    else:
+        return result

lib/python3.12/site-packages/prompt_toolkit/contrib/regular_languages/validation.py

@@ -0,0 +1,60 @@
+"""
+Validator for a regular language.
+"""
+
+from __future__ import annotations
+
+from prompt_toolkit.document import Document
+from prompt_toolkit.validation import ValidationError, Validator
+
+from .compiler import _CompiledGrammar
+
+__all__ = [
+    "GrammarValidator",
+]
+
+
+class GrammarValidator(Validator):
+    """
+    Validator which can be used for validation according to variables in
+    the grammar. Each variable can have its own validator.
+
+    :param compiled_grammar: `GrammarCompleter` instance.
+    :param validators: `dict` mapping variable names of the grammar to the
+                       `Validator` instances to be used for each variable.
+    """
+
+    def __init__(
+        self, compiled_grammar: _CompiledGrammar, validators: dict[str, Validator]
+    ) -> None:
+        self.compiled_grammar = compiled_grammar
+        self.validators = validators
+
+    def validate(self, document: Document) -> None:
+        # Parse input document.
+        # We use `match`, not `match_prefix`, because for validation, we want
+        # the actual, unambiguous interpretation of the input.
+        m = self.compiled_grammar.match(document.text)
+
+        if m:
+            for v in m.variables():
+                validator = self.validators.get(v.varname)
+
+                if validator:
+                    # Unescape text.
+                    unwrapped_text = self.compiled_grammar.unescape(v.varname, v.value)
+
+                    # Create a document, for the completions API (text/cursor_position)
+                    inner_document = Document(unwrapped_text, len(unwrapped_text))
+
+                    try:
+                        validator.validate(inner_document)
+                    except ValidationError as e:
+                        raise ValidationError(
+                            cursor_position=v.start + e.cursor_position,
+                            message=e.message,
+                        ) from e
+        else:
+            raise ValidationError(
+                cursor_position=len(document.text), message="Invalid command"
+            )

lib/python3.12/site-packages/prompt_toolkit/contrib/ssh/__init__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from .server import PromptToolkitSSHServer, PromptToolkitSSHSession
+
+__all__ = [
+    "PromptToolkitSSHSession",
+    "PromptToolkitSSHServer",
+]

lib/python3.12/site-packages/prompt_toolkit/contrib/ssh/server.py

@@ -0,0 +1,178 @@
+"""
+Utility for running a prompt_toolkit application in an asyncssh server.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import traceback
+from asyncio import get_running_loop
+from typing import Any, Callable, Coroutine, TextIO, cast
+
+import asyncssh
+
+from prompt_toolkit.application.current import AppSession, create_app_session
+from prompt_toolkit.data_structures import Size
+from prompt_toolkit.input import PipeInput, create_pipe_input
+from prompt_toolkit.output.vt100 import Vt100_Output
+
+__all__ = ["PromptToolkitSSHSession", "PromptToolkitSSHServer"]
+
+
+class PromptToolkitSSHSession(asyncssh.SSHServerSession):  # type: ignore
+    def __init__(
+        self,
+        interact: Callable[[PromptToolkitSSHSession], Coroutine[Any, Any, None]],
+        *,
+        enable_cpr: bool,
+    ) -> None:
+        self.interact = interact
+        self.enable_cpr = enable_cpr
+        self.interact_task: asyncio.Task[None] | None = None
+        self._chan: Any | None = None
+        self.app_session: AppSession | None = None
+
+        # PipInput object, for sending input in the CLI.
+        # (This is something that we can use in the prompt_toolkit event loop,
+        # but still write date in manually.)
+        self._input: PipeInput | None = None
+        self._output: Vt100_Output | None = None
+
+        # Output object. Don't render to the real stdout, but write everything
+        # in the SSH channel.
+        class Stdout:
+            def write(s, data: str) -> None:
+                try:
+                    if self._chan is not None:
+                        self._chan.write(data.replace("\n", "\r\n"))
+                except BrokenPipeError:
+                    pass  # Channel not open for sending.
+
+            def isatty(s) -> bool:
+                return True
+
+            def flush(s) -> None:
+                pass
+
+            @property
+            def encoding(s) -> str:
+                assert self._chan is not None
+                return str(self._chan._orig_chan.get_encoding()[0])
+
+        self.stdout = cast(TextIO, Stdout())
+
+    def _get_size(self) -> Size:
+        """
+        Callable that returns the current `Size`, required by Vt100_Output.
+        """
+        if self._chan is None:
+            return Size(rows=20, columns=79)
+        else:
+            width, height, pixwidth, pixheight = self._chan.get_terminal_size()
+            return Size(rows=height, columns=width)
+
+    def connection_made(self, chan: Any) -> None:
+        self._chan = chan
+
+    def shell_requested(self) -> bool:
+        return True
+
+    def session_started(self) -> None:
+        self.interact_task = get_running_loop().create_task(self._interact())
+
+    async def _interact(self) -> None:
+        if self._chan is None:
+            # Should not happen.
+            raise Exception("`_interact` called before `connection_made`.")
+
+        if hasattr(self._chan, "set_line_mode") and self._chan._editor is not None:
+            # Disable the line editing provided by asyncssh. Prompt_toolkit
+            # provides the line editing.
+            self._chan.set_line_mode(False)
+
+        term = self._chan.get_terminal_type()
+
+        self._output = Vt100_Output(
+            self.stdout, self._get_size, term=term, enable_cpr=self.enable_cpr
+        )
+
+        with create_pipe_input() as self._input:
+            with create_app_session(input=self._input, output=self._output) as session:
+                self.app_session = session
+                try:
+                    await self.interact(self)
+                except BaseException:
+                    traceback.print_exc()
+                finally:
+                    # Close the connection.
+                    self._chan.close()
+                    self._input.close()
+
+    def terminal_size_changed(
+        self, width: int, height: int, pixwidth: object, pixheight: object
+    ) -> None:
+        # Send resize event to the current application.
+        if self.app_session and self.app_session.app:
+            self.app_session.app._on_resize()
+
+    def data_received(self, data: str, datatype: object) -> None:
+        if self._input is None:
+            # Should not happen.
+            return
+
+        self._input.send_text(data)
+
+
+class PromptToolkitSSHServer(asyncssh.SSHServer):
+    """
+    Run a prompt_toolkit application over an asyncssh server.
+
+    This takes one argument, an `interact` function, which is called for each
+    connection. This should be an asynchronous function that runs the
+    prompt_toolkit applications. This function runs in an `AppSession`, which
+    means that we can have multiple UI interactions concurrently.
+
+    Example usage:
+
+    .. code:: python
+
+        async def interact(ssh_session: PromptToolkitSSHSession) -> None:
+            await yes_no_dialog("my title", "my text").run_async()
+
+            prompt_session = PromptSession()
+            text = await prompt_session.prompt_async("Type something: ")
+            print_formatted_text('You said: ', text)
+
+        server = PromptToolkitSSHServer(interact=interact)
+        loop = get_running_loop()
+        loop.run_until_complete(
+            asyncssh.create_server(
+                lambda: MySSHServer(interact),
+                "",
+                port,
+                server_host_keys=["/etc/ssh/..."],
+            )
+        )
+        loop.run_forever()
+
+    :param enable_cpr: When `True`, the default, try to detect whether the SSH
+        client runs in a terminal that responds to "cursor position requests".
+        That way, we can properly determine how much space there is available
+        for the UI (especially for drop down menus) to render.
+    """
+
+    def __init__(
+        self,
+        interact: Callable[[PromptToolkitSSHSession], Coroutine[Any, Any, None]],
+        *,
+        enable_cpr: bool = True,
+    ) -> None:
+        self.interact = interact
+        self.enable_cpr = enable_cpr
+
+    def begin_auth(self, username: str) -> bool:
+        # No authentication.
+        return False
+
+    def session_requested(self) -> PromptToolkitSSHSession:
+        return PromptToolkitSSHSession(self.interact, enable_cpr=self.enable_cpr)

lib/python3.12/site-packages/prompt_toolkit/contrib/telnet/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .server import TelnetServer
+
+__all__ = [
+    "TelnetServer",
+]

lib/python3.12/site-packages/prompt_toolkit/contrib/telnet/log.py

@@ -0,0 +1,13 @@
+"""
+Python logger for the telnet server.
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__package__)
+
+__all__ = [
+    "logger",
+]

lib/python3.12/site-packages/prompt_toolkit/contrib/telnet/protocol.py

@@ -0,0 +1,209 @@
+"""
+Parser for the Telnet protocol. (Not a complete implementation of the telnet
+specification, but sufficient for a command line interface.)
+
+Inspired by `Twisted.conch.telnet`.
+"""
+
+from __future__ import annotations
+
+import struct
+from typing import Callable, Generator
+
+from .log import logger
+
+__all__ = [
+    "TelnetProtocolParser",
+]
+
+
+def int2byte(number: int) -> bytes:
+    return bytes((number,))
+
+
+# Telnet constants.
+NOP = int2byte(0)
+SGA = int2byte(3)
+
+IAC = int2byte(255)
+DO = int2byte(253)
+DONT = int2byte(254)
+LINEMODE = int2byte(34)
+SB = int2byte(250)
+WILL = int2byte(251)
+WONT = int2byte(252)
+MODE = int2byte(1)
+SE = int2byte(240)
+ECHO = int2byte(1)
+NAWS = int2byte(31)
+LINEMODE = int2byte(34)
+SUPPRESS_GO_AHEAD = int2byte(3)
+
+TTYPE = int2byte(24)
+SEND = int2byte(1)
+IS = int2byte(0)
+
+DM = int2byte(242)
+BRK = int2byte(243)
+IP = int2byte(244)
+AO = int2byte(245)
+AYT = int2byte(246)
+EC = int2byte(247)
+EL = int2byte(248)
+GA = int2byte(249)
+
+
+class TelnetProtocolParser:
+    """
+    Parser for the Telnet protocol.
+    Usage::
+
+        def data_received(data):
+            print(data)
+
+        def size_received(rows, columns):
+            print(rows, columns)
+
+        p = TelnetProtocolParser(data_received, size_received)
+        p.feed(binary_data)
+    """
+
+    def __init__(
+        self,
+        data_received_callback: Callable[[bytes], None],
+        size_received_callback: Callable[[int, int], None],
+        ttype_received_callback: Callable[[str], None],
+    ) -> None:
+        self.data_received_callback = data_received_callback
+        self.size_received_callback = size_received_callback
+        self.ttype_received_callback = ttype_received_callback
+
+        self._parser = self._parse_coroutine()
+        self._parser.send(None)  # type: ignore
+
+    def received_data(self, data: bytes) -> None:
+        self.data_received_callback(data)
+
+    def do_received(self, data: bytes) -> None:
+        """Received telnet DO command."""
+        logger.info("DO %r", data)
+
+    def dont_received(self, data: bytes) -> None:
+        """Received telnet DONT command."""
+        logger.info("DONT %r", data)
+
+    def will_received(self, data: bytes) -> None:
+        """Received telnet WILL command."""
+        logger.info("WILL %r", data)
+
+    def wont_received(self, data: bytes) -> None:
+        """Received telnet WONT command."""
+        logger.info("WONT %r", data)
+
+    def command_received(self, command: bytes, data: bytes) -> None:
+        if command == DO:
+            self.do_received(data)
+
+        elif command == DONT:
+            self.dont_received(data)
+
+        elif command == WILL:
+            self.will_received(data)
+
+        elif command == WONT:
+            self.wont_received(data)
+
+        else:
+            logger.info("command received %r %r", command, data)
+
+    def naws(self, data: bytes) -> None:
+        """
+        Received NAWS. (Window dimensions.)
+        """
+        if len(data) == 4:
+            # NOTE: the first parameter of struct.unpack should be
+            # a 'str' object. Both on Py2/py3. This crashes on OSX
+            # otherwise.
+            columns, rows = struct.unpack("!HH", data)
+            self.size_received_callback(rows, columns)
+        else:
+            logger.warning("Wrong number of NAWS bytes")
+
+    def ttype(self, data: bytes) -> None:
+        """
+        Received terminal type.
+        """
+        subcmd, data = data[0:1], data[1:]
+        if subcmd == IS:
+            ttype = data.decode("ascii")
+            self.ttype_received_callback(ttype)
+        else:
+            logger.warning("Received a non-IS terminal type Subnegotiation")
+
+    def negotiate(self, data: bytes) -> None:
+        """
+        Got negotiate data.
+        """
+        command, payload = data[0:1], data[1:]
+
+        if command == NAWS:
+            self.naws(payload)
+        elif command == TTYPE:
+            self.ttype(payload)
+        else:
+            logger.info("Negotiate (%r got bytes)", len(data))
+
+    def _parse_coroutine(self) -> Generator[None, bytes, None]:
+        """
+        Parser state machine.
+        Every 'yield' expression returns the next byte.
+        """
+        while True:
+            d = yield
+
+            if d == int2byte(0):
+                pass  # NOP
+
+            # Go to state escaped.
+            elif d == IAC:
+                d2 = yield
+
+                if d2 == IAC:
+                    self.received_data(d2)
+
+                # Handle simple commands.
+                elif d2 in (NOP, DM, BRK, IP, AO, AYT, EC, EL, GA):
+                    self.command_received(d2, b"")
+
+                # Handle IAC-[DO/DONT/WILL/WONT] commands.
+                elif d2 in (DO, DONT, WILL, WONT):
+                    d3 = yield
+                    self.command_received(d2, d3)
+
+                # Subnegotiation
+                elif d2 == SB:
+                    # Consume everything until next IAC-SE
+                    data = []
+
+                    while True:
+                        d3 = yield
+
+                        if d3 == IAC:
+                            d4 = yield
+                            if d4 == SE:
+                                break
+                            else:
+                                data.append(d4)
+                        else:
+                            data.append(d3)
+
+                    self.negotiate(b"".join(data))
+            else:
+                self.received_data(d)
+
+    def feed(self, data: bytes) -> None:
+        """
+        Feed data to the parser.
+        """
+        for b in data:
+            self._parser.send(int2byte(b))

lib/python3.12/site-packages/prompt_toolkit/contrib/telnet/server.py

@@ -0,0 +1,428 @@
+"""
+Telnet server.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import socket
+from asyncio import get_running_loop
+from typing import Any, Callable, Coroutine, TextIO, cast
+
+from prompt_toolkit.application.current import create_app_session, get_app
+from prompt_toolkit.application.run_in_terminal import run_in_terminal
+from prompt_toolkit.data_structures import Size
+from prompt_toolkit.formatted_text import AnyFormattedText, to_formatted_text
+from prompt_toolkit.input import PipeInput, create_pipe_input
+from prompt_toolkit.output.vt100 import Vt100_Output
+from prompt_toolkit.renderer import print_formatted_text as print_formatted_text
+from prompt_toolkit.styles import BaseStyle, DummyStyle
+
+from .log import logger
+from .protocol import (
+    DO,
+    ECHO,
+    IAC,
+    LINEMODE,
+    MODE,
+    NAWS,
+    SB,
+    SE,
+    SEND,
+    SUPPRESS_GO_AHEAD,
+    TTYPE,
+    WILL,
+    TelnetProtocolParser,
+)
+
+__all__ = [
+    "TelnetServer",
+]
+
+
+def int2byte(number: int) -> bytes:
+    return bytes((number,))
+
+
+def _initialize_telnet(connection: socket.socket) -> None:
+    logger.info("Initializing telnet connection")
+
+    # Iac Do Linemode
+    connection.send(IAC + DO + LINEMODE)
+
+    # Suppress Go Ahead. (This seems important for Putty to do correct echoing.)
+    # This will allow bi-directional operation.
+    connection.send(IAC + WILL + SUPPRESS_GO_AHEAD)
+
+    # Iac sb
+    connection.send(IAC + SB + LINEMODE + MODE + int2byte(0) + IAC + SE)
+
+    # IAC Will Echo
+    connection.send(IAC + WILL + ECHO)
+
+    # Negotiate window size
+    connection.send(IAC + DO + NAWS)
+
+    # Negotiate terminal type
+    # Assume the client will accept the negotiation with `IAC +  WILL + TTYPE`
+    connection.send(IAC + DO + TTYPE)
+
+    # We can then select the first terminal type supported by the client,
+    # which is generally the best type the client supports
+    # The client should reply with a `IAC + SB  + TTYPE + IS + ttype + IAC + SE`
+    connection.send(IAC + SB + TTYPE + SEND + IAC + SE)
+
+
+class _ConnectionStdout:
+    """
+    Wrapper around socket which provides `write` and `flush` methods for the
+    Vt100_Output output.
+    """
+
+    def __init__(self, connection: socket.socket, encoding: str) -> None:
+        self._encoding = encoding
+        self._connection = connection
+        self._errors = "strict"
+        self._buffer: list[bytes] = []
+        self._closed = False
+
+    def write(self, data: str) -> None:
+        data = data.replace("\n", "\r\n")
+        self._buffer.append(data.encode(self._encoding, errors=self._errors))
+        self.flush()
+
+    def isatty(self) -> bool:
+        return True
+
+    def flush(self) -> None:
+        try:
+            if not self._closed:
+                self._connection.send(b"".join(self._buffer))
+        except OSError as e:
+            logger.warning(f"Couldn't send data over socket: {e}")
+
+        self._buffer = []
+
+    def close(self) -> None:
+        self._closed = True
+
+    @property
+    def encoding(self) -> str:
+        return self._encoding
+
+    @property
+    def errors(self) -> str:
+        return self._errors
+
+
+class TelnetConnection:
+    """
+    Class that represents one Telnet connection.
+    """
+
+    def __init__(
+        self,
+        conn: socket.socket,
+        addr: tuple[str, int],
+        interact: Callable[[TelnetConnection], Coroutine[Any, Any, None]],
+        server: TelnetServer,
+        encoding: str,
+        style: BaseStyle | None,
+        vt100_input: PipeInput,
+        enable_cpr: bool = True,
+    ) -> None:
+        self.conn = conn
+        self.addr = addr
+        self.interact = interact
+        self.server = server
+        self.encoding = encoding
+        self.style = style
+        self._closed = False
+        self._ready = asyncio.Event()
+        self.vt100_input = vt100_input
+        self.enable_cpr = enable_cpr
+        self.vt100_output: Vt100_Output | None = None
+
+        # Create "Output" object.
+        self.size = Size(rows=40, columns=79)
+
+        # Initialize.
+        _initialize_telnet(conn)
+
+        # Create output.
+        def get_size() -> Size:
+            return self.size
+
+        self.stdout = cast(TextIO, _ConnectionStdout(conn, encoding=encoding))
+
+        def data_received(data: bytes) -> None:
+            """TelnetProtocolParser 'data_received' callback"""
+            self.vt100_input.send_bytes(data)
+
+        def size_received(rows: int, columns: int) -> None:
+            """TelnetProtocolParser 'size_received' callback"""
+            self.size = Size(rows=rows, columns=columns)
+            if self.vt100_output is not None and self.context:
+                self.context.run(lambda: get_app()._on_resize())
+
+        def ttype_received(ttype: str) -> None:
+            """TelnetProtocolParser 'ttype_received' callback"""
+            self.vt100_output = Vt100_Output(
+                self.stdout, get_size, term=ttype, enable_cpr=enable_cpr
+            )
+            self._ready.set()
+
+        self.parser = TelnetProtocolParser(data_received, size_received, ttype_received)
+        self.context: contextvars.Context | None = None
+
+    async def run_application(self) -> None:
+        """
+        Run application.
+        """
+
+        def handle_incoming_data() -> None:
+            data = self.conn.recv(1024)
+            if data:
+                self.feed(data)
+            else:
+                # Connection closed by client.
+                logger.info("Connection closed by client. {!r} {!r}".format(*self.addr))
+                self.close()
+
+        # Add reader.
+        loop = get_running_loop()
+        loop.add_reader(self.conn, handle_incoming_data)
+
+        try:
+            # Wait for v100_output to be properly instantiated
+            await self._ready.wait()
+            with create_app_session(input=self.vt100_input, output=self.vt100_output):
+                self.context = contextvars.copy_context()
+                await self.interact(self)
+        finally:
+            self.close()
+
+    def feed(self, data: bytes) -> None:
+        """
+        Handler for incoming data. (Called by TelnetServer.)
+        """
+        self.parser.feed(data)
+
+    def close(self) -> None:
+        """
+        Closed by client.
+        """
+        if not self._closed:
+            self._closed = True
+
+            self.vt100_input.close()
+            get_running_loop().remove_reader(self.conn)
+            self.conn.close()
+            self.stdout.close()
+
+    def send(self, formatted_text: AnyFormattedText) -> None:
+        """
+        Send text to the client.
+        """
+        if self.vt100_output is None:
+            return
+        formatted_text = to_formatted_text(formatted_text)
+        print_formatted_text(
+            self.vt100_output, formatted_text, self.style or DummyStyle()
+        )
+
+    def send_above_prompt(self, formatted_text: AnyFormattedText) -> None:
+        """
+        Send text to the client.
+        This is asynchronous, returns a `Future`.
+        """
+        formatted_text = to_formatted_text(formatted_text)
+        return self._run_in_terminal(lambda: self.send(formatted_text))
+
+    def _run_in_terminal(self, func: Callable[[], None]) -> None:
+        # Make sure that when an application was active for this connection,
+        # that we print the text above the application.
+        if self.context:
+            self.context.run(run_in_terminal, func)
+        else:
+            raise RuntimeError("Called _run_in_terminal outside `run_application`.")
+
+    def erase_screen(self) -> None:
+        """
+        Erase the screen and move the cursor to the top.
+        """
+        if self.vt100_output is None:
+            return
+        self.vt100_output.erase_screen()
+        self.vt100_output.cursor_goto(0, 0)
+        self.vt100_output.flush()
+
+
+async def _dummy_interact(connection: TelnetConnection) -> None:
+    pass
+
+
+class TelnetServer:
+    """
+    Telnet server implementation.
+
+    Example::
+
+        async def interact(connection):
+            connection.send("Welcome")
+            session = PromptSession()
+            result = await session.prompt_async(message="Say something: ")
+            connection.send(f"You said: {result}\n")
+
+        async def main():
+            server = TelnetServer(interact=interact, port=2323)
+            await server.run()
+    """
+
+    def __init__(
+        self,
+        host: str = "127.0.0.1",
+        port: int = 23,
+        interact: Callable[
+            [TelnetConnection], Coroutine[Any, Any, None]
+        ] = _dummy_interact,
+        encoding: str = "utf-8",
+        style: BaseStyle | None = None,
+        enable_cpr: bool = True,
+    ) -> None:
+        self.host = host
+        self.port = port
+        self.interact = interact
+        self.encoding = encoding
+        self.style = style
+        self.enable_cpr = enable_cpr
+
+        self._run_task: asyncio.Task[None] | None = None
+        self._application_tasks: list[asyncio.Task[None]] = []
+
+        self.connections: set[TelnetConnection] = set()
+
+    @classmethod
+    def _create_socket(cls, host: str, port: int) -> socket.socket:
+        # Create and bind socket
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        s.bind((host, port))
+
+        s.listen(4)
+        return s
+
+    async def run(self, ready_cb: Callable[[], None] | None = None) -> None:
+        """
+        Run the telnet server, until this gets cancelled.
+
+        :param ready_cb: Callback that will be called at the point that we're
+            actually listening.
+        """
+        socket = self._create_socket(self.host, self.port)
+        logger.info(
+            "Listening for telnet connections on %s port %r", self.host, self.port
+        )
+
+        get_running_loop().add_reader(socket, lambda: self._accept(socket))
+
+        if ready_cb:
+            ready_cb()
+
+        try:
+            # Run forever, until cancelled.
+            await asyncio.Future()
+        finally:
+            get_running_loop().remove_reader(socket)
+            socket.close()
+
+            # Wait for all applications to finish.
+            for t in self._application_tasks:
+                t.cancel()
+
+            # (This is similar to
+            # `Application.cancel_and_wait_for_background_tasks`. We wait for the
+            # background tasks to complete, but don't propagate exceptions, because
+            # we can't use `ExceptionGroup` yet.)
+            if len(self._application_tasks) > 0:
+                await asyncio.wait(
+                    self._application_tasks,
+                    timeout=None,
+                    return_when=asyncio.ALL_COMPLETED,
+                )
+
+    def start(self) -> None:
+        """
+        Deprecated: Use `.run()` instead.
+
+        Start the telnet server (stop by calling and awaiting `stop()`).
+        """
+        if self._run_task is not None:
+            # Already running.
+            return
+
+        self._run_task = get_running_loop().create_task(self.run())
+
+    async def stop(self) -> None:
+        """
+        Deprecated: Use `.run()` instead.
+
+        Stop a telnet server that was started using `.start()` and wait for the
+        cancellation to complete.
+        """
+        if self._run_task is not None:
+            self._run_task.cancel()
+            try:
+                await self._run_task
+            except asyncio.CancelledError:
+                pass
+
+    def _accept(self, listen_socket: socket.socket) -> None:
+        """
+        Accept new incoming connection.
+        """
+        conn, addr = listen_socket.accept()
+        logger.info("New connection %r %r", *addr)
+
+        # Run application for this connection.
+        async def run() -> None:
+            try:
+                with create_pipe_input() as vt100_input:
+                    connection = TelnetConnection(
+                        conn,
+                        addr,
+                        self.interact,
+                        self,
+                        encoding=self.encoding,
+                        style=self.style,
+                        vt100_input=vt100_input,
+                        enable_cpr=self.enable_cpr,
+                    )
+                    self.connections.add(connection)
+
+                    logger.info("Starting interaction %r %r", *addr)
+                    try:
+                        await connection.run_application()
+                    finally:
+                        self.connections.remove(connection)
+                        logger.info("Stopping interaction %r %r", *addr)
+            except EOFError:
+                # Happens either when the connection is closed by the client
+                # (e.g., when the user types 'control-]', then 'quit' in the
+                # telnet client) or when the user types control-d in a prompt
+                # and this is not handled by the interact function.
+                logger.info("Unhandled EOFError in telnet application.")
+            except KeyboardInterrupt:
+                # Unhandled control-c propagated by a prompt.
+                logger.info("Unhandled KeyboardInterrupt in telnet application.")
+            except BaseException as e:
+                print(f"Got {type(e).__name__}", e)
+                import traceback
+
+                traceback.print_exc()
+            finally:
+                self._application_tasks.remove(task)
+
+        task = get_running_loop().create_task(run())
+        self._application_tasks.append(task)

lib/python3.12/site-packages/prompt_toolkit/cursor_shapes.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import TYPE_CHECKING, Any, Callable, Union
+
+from prompt_toolkit.enums import EditingMode
+from prompt_toolkit.key_binding.vi_state import InputMode
+
+if TYPE_CHECKING:
+    from .application import Application
+
+__all__ = [
+    "CursorShape",
+    "CursorShapeConfig",
+    "SimpleCursorShapeConfig",
+    "ModalCursorShapeConfig",
+    "DynamicCursorShapeConfig",
+    "to_cursor_shape_config",
+]
+
+
+class CursorShape(Enum):
+    # Default value that should tell the output implementation to never send
+    # cursor shape escape sequences. This is the default right now, because
+    # before this `CursorShape` functionality was introduced into
+    # prompt_toolkit itself, people had workarounds to send cursor shapes
+    # escapes into the terminal, by monkey patching some of prompt_toolkit's
+    # internals. We don't want the default prompt_toolkit implementation to
+    # interfere with that. E.g., IPython patches the `ViState.input_mode`
+    # property. See: https://github.com/ipython/ipython/pull/13501/files
+    _NEVER_CHANGE = "_NEVER_CHANGE"
+
+    BLOCK = "BLOCK"
+    BEAM = "BEAM"
+    UNDERLINE = "UNDERLINE"
+    BLINKING_BLOCK = "BLINKING_BLOCK"
+    BLINKING_BEAM = "BLINKING_BEAM"
+    BLINKING_UNDERLINE = "BLINKING_UNDERLINE"
+
+
+class CursorShapeConfig(ABC):
+    @abstractmethod
+    def get_cursor_shape(self, application: Application[Any]) -> CursorShape:
+        """
+        Return the cursor shape to be used in the current state.
+        """
+
+
+AnyCursorShapeConfig = Union[CursorShape, CursorShapeConfig, None]
+
+
+class SimpleCursorShapeConfig(CursorShapeConfig):
+    """
+    Always show the given cursor shape.
+    """
+
+    def __init__(self, cursor_shape: CursorShape = CursorShape._NEVER_CHANGE) -> None:
+        self.cursor_shape = cursor_shape
+
+    def get_cursor_shape(self, application: Application[Any]) -> CursorShape:
+        return self.cursor_shape
+
+
+class ModalCursorShapeConfig(CursorShapeConfig):
+    """
+    Show cursor shape according to the current input mode.
+    """
+
+    def get_cursor_shape(self, application: Application[Any]) -> CursorShape:
+        if application.editing_mode == EditingMode.VI:
+            if application.vi_state.input_mode in {
+                InputMode.NAVIGATION,
+            }:
+                return CursorShape.BLOCK
+            if application.vi_state.input_mode in {
+                InputMode.INSERT,
+                InputMode.INSERT_MULTIPLE,
+            }:
+                return CursorShape.BEAM
+            if application.vi_state.input_mode in {
+                InputMode.REPLACE,
+                InputMode.REPLACE_SINGLE,
+            }:
+                return CursorShape.UNDERLINE
+        elif application.editing_mode == EditingMode.EMACS:
+            # like vi's INSERT
+            return CursorShape.BEAM
+
+        # Default
+        return CursorShape.BLOCK
+
+
+class DynamicCursorShapeConfig(CursorShapeConfig):
+    def __init__(
+        self, get_cursor_shape_config: Callable[[], AnyCursorShapeConfig]
+    ) -> None:
+        self.get_cursor_shape_config = get_cursor_shape_config
+
+    def get_cursor_shape(self, application: Application[Any]) -> CursorShape:
+        return to_cursor_shape_config(self.get_cursor_shape_config()).get_cursor_shape(
+            application
+        )
+
+
+def to_cursor_shape_config(value: AnyCursorShapeConfig) -> CursorShapeConfig:
+    """
+    Take a `CursorShape` instance or `CursorShapeConfig` and turn it into a
+    `CursorShapeConfig`.
+    """
+    if value is None:
+        return SimpleCursorShapeConfig()
+
+    if isinstance(value, CursorShape):
+        return SimpleCursorShapeConfig(value)
+
+    return value

lib/python3.12/site-packages/prompt_toolkit/data_structures.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import NamedTuple
+
+__all__ = [
+    "Point",
+    "Size",
+]
+
+
+class Point(NamedTuple):
+    x: int
+    y: int
+
+
+class Size(NamedTuple):
+    rows: int
+    columns: int

lib/python3.12/site-packages/prompt_toolkit/document.py

@@ -0,0 +1,1182 @@
+"""
+The `Document` that implements all the text operations/querying.
+"""
+
+from __future__ import annotations
+
+import bisect
+import re
+import string
+import weakref
+from typing import Callable, Dict, Iterable, List, NoReturn, Pattern, cast
+
+from .clipboard import ClipboardData
+from .filters import vi_mode
+from .selection import PasteMode, SelectionState, SelectionType
+
+__all__ = [
+    "Document",
+]
+
+
+# Regex for finding "words" in documents. (We consider a group of alnum
+# characters a word, but also a group of special characters a word, as long as
+# it doesn't contain a space.)
+# (This is a 'word' in Vi.)
+_FIND_WORD_RE = re.compile(r"([a-zA-Z0-9_]+|[^a-zA-Z0-9_\s]+)")
+_FIND_CURRENT_WORD_RE = re.compile(r"^([a-zA-Z0-9_]+|[^a-zA-Z0-9_\s]+)")
+_FIND_CURRENT_WORD_INCLUDE_TRAILING_WHITESPACE_RE = re.compile(
+    r"^(([a-zA-Z0-9_]+|[^a-zA-Z0-9_\s]+)\s*)"
+)
+
+# Regex for finding "WORDS" in documents.
+# (This is a 'WORD in Vi.)
+_FIND_BIG_WORD_RE = re.compile(r"([^\s]+)")
+_FIND_CURRENT_BIG_WORD_RE = re.compile(r"^([^\s]+)")
+_FIND_CURRENT_BIG_WORD_INCLUDE_TRAILING_WHITESPACE_RE = re.compile(r"^([^\s]+\s*)")
+
+# Share the Document._cache between all Document instances.
+# (Document instances are considered immutable. That means that if another
+# `Document` is constructed with the same text, it should have the same
+# `_DocumentCache`.)
+_text_to_document_cache: dict[str, _DocumentCache] = cast(
+    Dict[str, "_DocumentCache"],
+    weakref.WeakValueDictionary(),  # Maps document.text to DocumentCache instance.
+)
+
+
+class _ImmutableLineList(List[str]):
+    """
+    Some protection for our 'lines' list, which is assumed to be immutable in the cache.
+    (Useful for detecting obvious bugs.)
+    """
+
+    def _error(self, *a: object, **kw: object) -> NoReturn:
+        raise NotImplementedError("Attempt to modify an immutable list.")
+
+    __setitem__ = _error
+    append = _error
+    clear = _error
+    extend = _error
+    insert = _error
+    pop = _error
+    remove = _error
+    reverse = _error
+    sort = _error
+
+
+class _DocumentCache:
+    def __init__(self) -> None:
+        #: List of lines for the Document text.
+        self.lines: _ImmutableLineList | None = None
+
+        #: List of index positions, pointing to the start of all the lines.
+        self.line_indexes: list[int] | None = None
+
+
+class Document:
+    """
+    This is a immutable class around the text and cursor position, and contains
+    methods for querying this data, e.g. to give the text before the cursor.
+
+    This class is usually instantiated by a :class:`~prompt_toolkit.buffer.Buffer`
+    object, and accessed as the `document` property of that class.
+
+    :param text: string
+    :param cursor_position: int
+    :param selection: :class:`.SelectionState`
+    """
+
+    __slots__ = ("_text", "_cursor_position", "_selection", "_cache")
+
+    def __init__(
+        self,
+        text: str = "",
+        cursor_position: int | None = None,
+        selection: SelectionState | None = None,
+    ) -> None:
+        # Check cursor position. It can also be right after the end. (Where we
+        # insert text.)
+        assert cursor_position is None or cursor_position <= len(text), AssertionError(
+            f"cursor_position={cursor_position!r}, len_text={len(text)!r}"
+        )
+
+        # By default, if no cursor position was given, make sure to put the
+        # cursor position is at the end of the document. This is what makes
+        # sense in most places.
+        if cursor_position is None:
+            cursor_position = len(text)
+
+        # Keep these attributes private. A `Document` really has to be
+        # considered to be immutable, because otherwise the caching will break
+        # things. Because of that, we wrap these into read-only properties.
+        self._text = text
+        self._cursor_position = cursor_position
+        self._selection = selection
+
+        # Cache for lines/indexes. (Shared with other Document instances that
+        # contain the same text.
+        try:
+            self._cache = _text_to_document_cache[self.text]
+        except KeyError:
+            self._cache = _DocumentCache()
+            _text_to_document_cache[self.text] = self._cache
+
+        # XX: For some reason, above, we can't use 'WeakValueDictionary.setdefault'.
+        #     This fails in Pypy3. `self._cache` becomes None, because that's what
+        #     'setdefault' returns.
+        # self._cache = _text_to_document_cache.setdefault(self.text, _DocumentCache())
+        # assert self._cache
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.text!r}, {self.cursor_position!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Document):
+            return False
+
+        return (
+            self.text == other.text
+            and self.cursor_position == other.cursor_position
+            and self.selection == other.selection
+        )
+
+    @property
+    def text(self) -> str:
+        "The document text."
+        return self._text
+
+    @property
+    def cursor_position(self) -> int:
+        "The document cursor position."
+        return self._cursor_position
+
+    @property
+    def selection(self) -> SelectionState | None:
+        ":class:`.SelectionState` object."
+        return self._selection
+
+    @property
+    def current_char(self) -> str:
+        """Return character under cursor or an empty string."""
+        return self._get_char_relative_to_cursor(0) or ""
+
+    @property
+    def char_before_cursor(self) -> str:
+        """Return character before the cursor or an empty string."""
+        return self._get_char_relative_to_cursor(-1) or ""
+
+    @property
+    def text_before_cursor(self) -> str:
+        return self.text[: self.cursor_position :]
+
+    @property
+    def text_after_cursor(self) -> str:
+        return self.text[self.cursor_position :]
+
+    @property
+    def current_line_before_cursor(self) -> str:
+        """Text from the start of the line until the cursor."""
+        _, _, text = self.text_before_cursor.rpartition("\n")
+        return text
+
+    @property
+    def current_line_after_cursor(self) -> str:
+        """Text from the cursor until the end of the line."""
+        text, _, _ = self.text_after_cursor.partition("\n")
+        return text
+
+    @property
+    def lines(self) -> list[str]:
+        """
+        Array of all the lines.
+        """
+        # Cache, because this one is reused very often.
+        if self._cache.lines is None:
+            self._cache.lines = _ImmutableLineList(self.text.split("\n"))
+
+        return self._cache.lines
+
+    @property
+    def _line_start_indexes(self) -> list[int]:
+        """
+        Array pointing to the start indexes of all the lines.
+        """
+        # Cache, because this is often reused. (If it is used, it's often used
+        # many times. And this has to be fast for editing big documents!)
+        if self._cache.line_indexes is None:
+            # Create list of line lengths.
+            line_lengths = map(len, self.lines)
+
+            # Calculate cumulative sums.
+            indexes = [0]
+            append = indexes.append
+            pos = 0
+
+            for line_length in line_lengths:
+                pos += line_length + 1
+                append(pos)
+
+            # Remove the last item. (This is not a new line.)
+            if len(indexes) > 1:
+                indexes.pop()
+
+            self._cache.line_indexes = indexes
+
+        return self._cache.line_indexes
+
+    @property
+    def lines_from_current(self) -> list[str]:
+        """
+        Array of the lines starting from the current line, until the last line.
+        """
+        return self.lines[self.cursor_position_row :]
+
+    @property
+    def line_count(self) -> int:
+        r"""Return the number of lines in this document. If the document ends
+        with a trailing \n, that counts as the beginning of a new line."""
+        return len(self.lines)
+
+    @property
+    def current_line(self) -> str:
+        """Return the text on the line where the cursor is. (when the input
+        consists of just one line, it equals `text`."""
+        return self.current_line_before_cursor + self.current_line_after_cursor
+
+    @property
+    def leading_whitespace_in_current_line(self) -> str:
+        """The leading whitespace in the left margin of the current line."""
+        current_line = self.current_line
+        length = len(current_line) - len(current_line.lstrip())
+        return current_line[:length]
+
+    def _get_char_relative_to_cursor(self, offset: int = 0) -> str:
+        """
+        Return character relative to cursor position, or empty string
+        """
+        try:
+            return self.text[self.cursor_position + offset]
+        except IndexError:
+            return ""
+
+    @property
+    def on_first_line(self) -> bool:
+        """
+        True when we are at the first line.
+        """
+        return self.cursor_position_row == 0
+
+    @property
+    def on_last_line(self) -> bool:
+        """
+        True when we are at the last line.
+        """
+        return self.cursor_position_row == self.line_count - 1
+
+    @property
+    def cursor_position_row(self) -> int:
+        """
+        Current row. (0-based.)
+        """
+        row, _ = self._find_line_start_index(self.cursor_position)
+        return row
+
+    @property
+    def cursor_position_col(self) -> int:
+        """
+        Current column. (0-based.)
+        """
+        # (Don't use self.text_before_cursor to calculate this. Creating
+        # substrings and doing rsplit is too expensive for getting the cursor
+        # position.)
+        _, line_start_index = self._find_line_start_index(self.cursor_position)
+        return self.cursor_position - line_start_index
+
+    def _find_line_start_index(self, index: int) -> tuple[int, int]:
+        """
+        For the index of a character at a certain line, calculate the index of
+        the first character on that line.
+
+        Return (row, index) tuple.
+        """
+        indexes = self._line_start_indexes
+
+        pos = bisect.bisect_right(indexes, index) - 1
+        return pos, indexes[pos]
+
+    def translate_index_to_position(self, index: int) -> tuple[int, int]:
+        """
+        Given an index for the text, return the corresponding (row, col) tuple.
+        (0-based. Returns (0, 0) for index=0.)
+        """
+        # Find start of this line.
+        row, row_index = self._find_line_start_index(index)
+        col = index - row_index
+
+        return row, col
+
+    def translate_row_col_to_index(self, row: int, col: int) -> int:
+        """
+        Given a (row, col) tuple, return the corresponding index.
+        (Row and col params are 0-based.)
+
+        Negative row/col values are turned into zero.
+        """
+        try:
+            result = self._line_start_indexes[row]
+            line = self.lines[row]
+        except IndexError:
+            if row < 0:
+                result = self._line_start_indexes[0]
+                line = self.lines[0]
+            else:
+                result = self._line_start_indexes[-1]
+                line = self.lines[-1]
+
+        result += max(0, min(col, len(line)))
+
+        # Keep in range. (len(self.text) is included, because the cursor can be
+        # right after the end of the text as well.)
+        result = max(0, min(result, len(self.text)))
+        return result
+
+    @property
+    def is_cursor_at_the_end(self) -> bool:
+        """True when the cursor is at the end of the text."""
+        return self.cursor_position == len(self.text)
+
+    @property
+    def is_cursor_at_the_end_of_line(self) -> bool:
+        """True when the cursor is at the end of this line."""
+        return self.current_char in ("\n", "")
+
+    def has_match_at_current_position(self, sub: str) -> bool:
+        """
+        `True` when this substring is found at the cursor position.
+        """
+        return self.text.find(sub, self.cursor_position) == self.cursor_position
+
+    def find(
+        self,
+        sub: str,
+        in_current_line: bool = False,
+        include_current_position: bool = False,
+        ignore_case: bool = False,
+        count: int = 1,
+    ) -> int | None:
+        """
+        Find `text` after the cursor, return position relative to the cursor
+        position. Return `None` if nothing was found.
+
+        :param count: Find the n-th occurrence.
+        """
+        assert isinstance(ignore_case, bool)
+
+        if in_current_line:
+            text = self.current_line_after_cursor
+        else:
+            text = self.text_after_cursor
+
+        if not include_current_position:
+            if len(text) == 0:
+                return None  # (Otherwise, we always get a match for the empty string.)
+            else:
+                text = text[1:]
+
+        flags = re.IGNORECASE if ignore_case else 0
+        iterator = re.finditer(re.escape(sub), text, flags)
+
+        try:
+            for i, match in enumerate(iterator):
+                if i + 1 == count:
+                    if include_current_position:
+                        return match.start(0)
+                    else:
+                        return match.start(0) + 1
+        except StopIteration:
+            pass
+        return None
+
+    def find_all(self, sub: str, ignore_case: bool = False) -> list[int]:
+        """
+        Find all occurrences of the substring. Return a list of absolute
+        positions in the document.
+        """
+        flags = re.IGNORECASE if ignore_case else 0
+        return [a.start() for a in re.finditer(re.escape(sub), self.text, flags)]
+
+    def find_backwards(
+        self,
+        sub: str,
+        in_current_line: bool = False,
+        ignore_case: bool = False,
+        count: int = 1,
+    ) -> int | None:
+        """
+        Find `text` before the cursor, return position relative to the cursor
+        position. Return `None` if nothing was found.
+
+        :param count: Find the n-th occurrence.
+        """
+        if in_current_line:
+            before_cursor = self.current_line_before_cursor[::-1]
+        else:
+            before_cursor = self.text_before_cursor[::-1]
+
+        flags = re.IGNORECASE if ignore_case else 0
+        iterator = re.finditer(re.escape(sub[::-1]), before_cursor, flags)
+
+        try:
+            for i, match in enumerate(iterator):
+                if i + 1 == count:
+                    return -match.start(0) - len(sub)
+        except StopIteration:
+            pass
+        return None
+
+    def get_word_before_cursor(
+        self, WORD: bool = False, pattern: Pattern[str] | None = None
+    ) -> str:
+        """
+        Give the word before the cursor.
+        If we have whitespace before the cursor this returns an empty string.
+
+        :param pattern: (None or compiled regex). When given, use this regex
+            pattern.
+        """
+        if self._is_word_before_cursor_complete(WORD=WORD, pattern=pattern):
+            # Space before the cursor or no text before cursor.
+            return ""
+
+        text_before_cursor = self.text_before_cursor
+        start = self.find_start_of_previous_word(WORD=WORD, pattern=pattern) or 0
+
+        return text_before_cursor[len(text_before_cursor) + start :]
+
+    def _is_word_before_cursor_complete(
+        self, WORD: bool = False, pattern: Pattern[str] | None = None
+    ) -> bool:
+        if pattern:
+            return self.find_start_of_previous_word(WORD=WORD, pattern=pattern) is None
+        else:
+            return (
+                self.text_before_cursor == "" or self.text_before_cursor[-1:].isspace()
+            )
+
+    def find_start_of_previous_word(
+        self, count: int = 1, WORD: bool = False, pattern: Pattern[str] | None = None
+    ) -> int | None:
+        """
+        Return an index relative to the cursor position pointing to the start
+        of the previous word. Return `None` if nothing was found.
+
+        :param pattern: (None or compiled regex). When given, use this regex
+            pattern.
+        """
+        assert not (WORD and pattern)
+
+        # Reverse the text before the cursor, in order to do an efficient
+        # backwards search.
+        text_before_cursor = self.text_before_cursor[::-1]
+
+        if pattern:
+            regex = pattern
+        elif WORD:
+            regex = _FIND_BIG_WORD_RE
+        else:
+            regex = _FIND_WORD_RE
+
+        iterator = regex.finditer(text_before_cursor)
+
+        try:
+            for i, match in enumerate(iterator):
+                if i + 1 == count:
+                    return -match.end(0)
+        except StopIteration:
+            pass
+        return None
+
+    def find_boundaries_of_current_word(
+        self,
+        WORD: bool = False,
+        include_leading_whitespace: bool = False,
+        include_trailing_whitespace: bool = False,
+    ) -> tuple[int, int]:
+        """
+        Return the relative boundaries (startpos, endpos) of the current word under the
+        cursor. (This is at the current line, because line boundaries obviously
+        don't belong to any word.)
+        If not on a word, this returns (0,0)
+        """
+        text_before_cursor = self.current_line_before_cursor[::-1]
+        text_after_cursor = self.current_line_after_cursor
+
+        def get_regex(include_whitespace: bool) -> Pattern[str]:
+            return {
+                (False, False): _FIND_CURRENT_WORD_RE,
+                (False, True): _FIND_CURRENT_WORD_INCLUDE_TRAILING_WHITESPACE_RE,
+                (True, False): _FIND_CURRENT_BIG_WORD_RE,
+                (True, True): _FIND_CURRENT_BIG_WORD_INCLUDE_TRAILING_WHITESPACE_RE,
+            }[(WORD, include_whitespace)]
+
+        match_before = get_regex(include_leading_whitespace).search(text_before_cursor)
+        match_after = get_regex(include_trailing_whitespace).search(text_after_cursor)
+
+        # When there is a match before and after, and we're not looking for
+        # WORDs, make sure that both the part before and after the cursor are
+        # either in the [a-zA-Z_] alphabet or not. Otherwise, drop the part
+        # before the cursor.
+        if not WORD and match_before and match_after:
+            c1 = self.text[self.cursor_position - 1]
+            c2 = self.text[self.cursor_position]
+            alphabet = string.ascii_letters + "0123456789_"
+
+            if (c1 in alphabet) != (c2 in alphabet):
+                match_before = None
+
+        return (
+            -match_before.end(1) if match_before else 0,
+            match_after.end(1) if match_after else 0,
+        )
+
+    def get_word_under_cursor(self, WORD: bool = False) -> str:
+        """
+        Return the word, currently below the cursor.
+        This returns an empty string when the cursor is on a whitespace region.
+        """
+        start, end = self.find_boundaries_of_current_word(WORD=WORD)
+        return self.text[self.cursor_position + start : self.cursor_position + end]
+
+    def find_next_word_beginning(
+        self, count: int = 1, WORD: bool = False
+    ) -> int | None:
+        """
+        Return an index relative to the cursor position pointing to the start
+        of the next word. Return `None` if nothing was found.
+        """
+        if count < 0:
+            return self.find_previous_word_beginning(count=-count, WORD=WORD)
+
+        regex = _FIND_BIG_WORD_RE if WORD else _FIND_WORD_RE
+        iterator = regex.finditer(self.text_after_cursor)
+
+        try:
+            for i, match in enumerate(iterator):
+                # Take first match, unless it's the word on which we're right now.
+                if i == 0 and match.start(1) == 0:
+                    count += 1
+
+                if i + 1 == count:
+                    return match.start(1)
+        except StopIteration:
+            pass
+        return None
+
+    def find_next_word_ending(
+        self, include_current_position: bool = False, count: int = 1, WORD: bool = False
+    ) -> int | None:
+        """
+        Return an index relative to the cursor position pointing to the end
+        of the next word. Return `None` if nothing was found.
+        """
+        if count < 0:
+            return self.find_previous_word_ending(count=-count, WORD=WORD)
+
+        if include_current_position:
+            text = self.text_after_cursor
+        else:
+            text = self.text_after_cursor[1:]
+
+        regex = _FIND_BIG_WORD_RE if WORD else _FIND_WORD_RE
+        iterable = regex.finditer(text)
+
+        try:
+            for i, match in enumerate(iterable):
+                if i + 1 == count:
+                    value = match.end(1)
+
+                    if include_current_position:
+                        return value
+                    else:
+                        return value + 1
+
+        except StopIteration:
+            pass
+        return None
+
+    def find_previous_word_beginning(
+        self, count: int = 1, WORD: bool = False
+    ) -> int | None:
+        """
+        Return an index relative to the cursor position pointing to the start
+        of the previous word. Return `None` if nothing was found.
+        """
+        if count < 0:
+            return self.find_next_word_beginning(count=-count, WORD=WORD)
+
+        regex = _FIND_BIG_WORD_RE if WORD else _FIND_WORD_RE
+        iterator = regex.finditer(self.text_before_cursor[::-1])
+
+        try:
+            for i, match in enumerate(iterator):
+                if i + 1 == count:
+                    return -match.end(1)
+        except StopIteration:
+            pass
+        return None
+
+    def find_previous_word_ending(
+        self, count: int = 1, WORD: bool = False
+    ) -> int | None:
+        """
+        Return an index relative to the cursor position pointing to the end
+        of the previous word. Return `None` if nothing was found.
+        """
+        if count < 0:
+            return self.find_next_word_ending(count=-count, WORD=WORD)
+
+        text_before_cursor = self.text_after_cursor[:1] + self.text_before_cursor[::-1]
+
+        regex = _FIND_BIG_WORD_RE if WORD else _FIND_WORD_RE
+        iterator = regex.finditer(text_before_cursor)
+
+        try:
+            for i, match in enumerate(iterator):
+                # Take first match, unless it's the word on which we're right now.
+                if i == 0 and match.start(1) == 0:
+                    count += 1
+
+                if i + 1 == count:
+                    return -match.start(1) + 1
+        except StopIteration:
+            pass
+        return None
+
+    def find_next_matching_line(
+        self, match_func: Callable[[str], bool], count: int = 1
+    ) -> int | None:
+        """
+        Look downwards for empty lines.
+        Return the line index, relative to the current line.
+        """
+        result = None
+
+        for index, line in enumerate(self.lines[self.cursor_position_row + 1 :]):
+            if match_func(line):
+                result = 1 + index
+                count -= 1
+
+            if count == 0:
+                break
+
+        return result
+
+    def find_previous_matching_line(
+        self, match_func: Callable[[str], bool], count: int = 1
+    ) -> int | None:
+        """
+        Look upwards for empty lines.
+        Return the line index, relative to the current line.
+        """
+        result = None
+
+        for index, line in enumerate(self.lines[: self.cursor_position_row][::-1]):
+            if match_func(line):
+                result = -1 - index
+                count -= 1
+
+            if count == 0:
+                break
+
+        return result
+
+    def get_cursor_left_position(self, count: int = 1) -> int:
+        """
+        Relative position for cursor left.
+        """
+        if count < 0:
+            return self.get_cursor_right_position(-count)
+
+        return -min(self.cursor_position_col, count)
+
+    def get_cursor_right_position(self, count: int = 1) -> int:
+        """
+        Relative position for cursor_right.
+        """
+        if count < 0:
+            return self.get_cursor_left_position(-count)
+
+        return min(count, len(self.current_line_after_cursor))
+
+    def get_cursor_up_position(
+        self, count: int = 1, preferred_column: int | None = None
+    ) -> int:
+        """
+        Return the relative cursor position (character index) where we would be if the
+        user pressed the arrow-up button.
+
+        :param preferred_column: When given, go to this column instead of
+                                 staying at the current column.
+        """
+        assert count >= 1
+        column = (
+            self.cursor_position_col if preferred_column is None else preferred_column
+        )
+
+        return (
+            self.translate_row_col_to_index(
+                max(0, self.cursor_position_row - count), column
+            )
+            - self.cursor_position
+        )
+
+    def get_cursor_down_position(
+        self, count: int = 1, preferred_column: int | None = None
+    ) -> int:
+        """
+        Return the relative cursor position (character index) where we would be if the
+        user pressed the arrow-down button.
+
+        :param preferred_column: When given, go to this column instead of
+                                 staying at the current column.
+        """
+        assert count >= 1
+        column = (
+            self.cursor_position_col if preferred_column is None else preferred_column
+        )
+
+        return (
+            self.translate_row_col_to_index(self.cursor_position_row + count, column)
+            - self.cursor_position
+        )
+
+    def find_enclosing_bracket_right(
+        self, left_ch: str, right_ch: str, end_pos: int | None = None
+    ) -> int | None:
+        """
+        Find the right bracket enclosing current position. Return the relative
+        position to the cursor position.
+
+        When `end_pos` is given, don't look past the position.
+        """
+        if self.current_char == right_ch:
+            return 0
+
+        if end_pos is None:
+            end_pos = len(self.text)
+        else:
+            end_pos = min(len(self.text), end_pos)
+
+        stack = 1
+
+        # Look forward.
+        for i in range(self.cursor_position + 1, end_pos):
+            c = self.text[i]
+
+            if c == left_ch:
+                stack += 1
+            elif c == right_ch:
+                stack -= 1
+
+            if stack == 0:
+                return i - self.cursor_position
+
+        return None
+
+    def find_enclosing_bracket_left(
+        self, left_ch: str, right_ch: str, start_pos: int | None = None
+    ) -> int | None:
+        """
+        Find the left bracket enclosing current position. Return the relative
+        position to the cursor position.
+
+        When `start_pos` is given, don't look past the position.
+        """
+        if self.current_char == left_ch:
+            return 0
+
+        if start_pos is None:
+            start_pos = 0
+        else:
+            start_pos = max(0, start_pos)
+
+        stack = 1
+
+        # Look backward.
+        for i in range(self.cursor_position - 1, start_pos - 1, -1):
+            c = self.text[i]
+
+            if c == right_ch:
+                stack += 1
+            elif c == left_ch:
+                stack -= 1
+
+            if stack == 0:
+                return i - self.cursor_position
+
+        return None
+
+    def find_matching_bracket_position(
+        self, start_pos: int | None = None, end_pos: int | None = None
+    ) -> int:
+        """
+        Return relative cursor position of matching [, (, { or < bracket.
+
+        When `start_pos` or `end_pos` are given. Don't look past the positions.
+        """
+
+        # Look for a match.
+        for pair in "()", "[]", "{}", "<>":
+            A = pair[0]
+            B = pair[1]
+            if self.current_char == A:
+                return self.find_enclosing_bracket_right(A, B, end_pos=end_pos) or 0
+            elif self.current_char == B:
+                return self.find_enclosing_bracket_left(A, B, start_pos=start_pos) or 0
+
+        return 0
+
+    def get_start_of_document_position(self) -> int:
+        """Relative position for the start of the document."""
+        return -self.cursor_position
+
+    def get_end_of_document_position(self) -> int:
+        """Relative position for the end of the document."""
+        return len(self.text) - self.cursor_position
+
+    def get_start_of_line_position(self, after_whitespace: bool = False) -> int:
+        """Relative position for the start of this line."""
+        if after_whitespace:
+            current_line = self.current_line
+            return (
+                len(current_line)
+                - len(current_line.lstrip())
+                - self.cursor_position_col
+            )
+        else:
+            return -len(self.current_line_before_cursor)
+
+    def get_end_of_line_position(self) -> int:
+        """Relative position for the end of this line."""
+        return len(self.current_line_after_cursor)
+
+    def last_non_blank_of_current_line_position(self) -> int:
+        """
+        Relative position for the last non blank character of this line.
+        """
+        return len(self.current_line.rstrip()) - self.cursor_position_col - 1
+
+    def get_column_cursor_position(self, column: int) -> int:
+        """
+        Return the relative cursor position for this column at the current
+        line. (It will stay between the boundaries of the line in case of a
+        larger number.)
+        """
+        line_length = len(self.current_line)
+        current_column = self.cursor_position_col
+        column = max(0, min(line_length, column))
+
+        return column - current_column
+
+    def selection_range(
+        self,
+    ) -> tuple[
+        int, int
+    ]:  # XXX: shouldn't this return `None` if there is no selection???
+        """
+        Return (from, to) tuple of the selection.
+        start and end position are included.
+
+        This doesn't take the selection type into account. Use
+        `selection_ranges` instead.
+        """
+        if self.selection:
+            from_, to = sorted(
+                [self.cursor_position, self.selection.original_cursor_position]
+            )
+        else:
+            from_, to = self.cursor_position, self.cursor_position
+
+        return from_, to
+
+    def selection_ranges(self) -> Iterable[tuple[int, int]]:
+        """
+        Return a list of `(from, to)` tuples for the selection or none if
+        nothing was selected. The upper boundary is not included.
+
+        This will yield several (from, to) tuples in case of a BLOCK selection.
+        This will return zero ranges, like (8,8) for empty lines in a block
+        selection.
+        """
+        if self.selection:
+            from_, to = sorted(
+                [self.cursor_position, self.selection.original_cursor_position]
+            )
+
+            if self.selection.type == SelectionType.BLOCK:
+                from_line, from_column = self.translate_index_to_position(from_)
+                to_line, to_column = self.translate_index_to_position(to)
+                from_column, to_column = sorted([from_column, to_column])
+                lines = self.lines
+
+                if vi_mode():
+                    to_column += 1
+
+                for l in range(from_line, to_line + 1):
+                    line_length = len(lines[l])
+
+                    if from_column <= line_length:
+                        yield (
+                            self.translate_row_col_to_index(l, from_column),
+                            self.translate_row_col_to_index(
+                                l, min(line_length, to_column)
+                            ),
+                        )
+            else:
+                # In case of a LINES selection, go to the start/end of the lines.
+                if self.selection.type == SelectionType.LINES:
+                    from_ = max(0, self.text.rfind("\n", 0, from_) + 1)
+
+                    if self.text.find("\n", to) >= 0:
+                        to = self.text.find("\n", to)
+                    else:
+                        to = len(self.text) - 1
+
+                # In Vi mode, the upper boundary is always included. For Emacs,
+                # that's not the case.
+                if vi_mode():
+                    to += 1
+
+                yield from_, to
+
+    def selection_range_at_line(self, row: int) -> tuple[int, int] | None:
+        """
+        If the selection spans a portion of the given line, return a (from, to) tuple.
+
+        The returned upper boundary is not included in the selection, so
+        `(0, 0)` is an empty selection.  `(0, 1)`, is a one character selection.
+
+        Returns None if the selection doesn't cover this line at all.
+        """
+        if self.selection:
+            line = self.lines[row]
+
+            row_start = self.translate_row_col_to_index(row, 0)
+            row_end = self.translate_row_col_to_index(row, len(line))
+
+            from_, to = sorted(
+                [self.cursor_position, self.selection.original_cursor_position]
+            )
+
+            # Take the intersection of the current line and the selection.
+            intersection_start = max(row_start, from_)
+            intersection_end = min(row_end, to)
+
+            if intersection_start <= intersection_end:
+                if self.selection.type == SelectionType.LINES:
+                    intersection_start = row_start
+                    intersection_end = row_end
+
+                elif self.selection.type == SelectionType.BLOCK:
+                    _, col1 = self.translate_index_to_position(from_)
+                    _, col2 = self.translate_index_to_position(to)
+                    col1, col2 = sorted([col1, col2])
+
+                    if col1 > len(line):
+                        return None  # Block selection doesn't cross this line.
+
+                    intersection_start = self.translate_row_col_to_index(row, col1)
+                    intersection_end = self.translate_row_col_to_index(row, col2)
+
+                _, from_column = self.translate_index_to_position(intersection_start)
+                _, to_column = self.translate_index_to_position(intersection_end)
+
+                # In Vi mode, the upper boundary is always included. For Emacs
+                # mode, that's not the case.
+                if vi_mode():
+                    to_column += 1
+
+                return from_column, to_column
+        return None
+
+    def cut_selection(self) -> tuple[Document, ClipboardData]:
+        """
+        Return a (:class:`.Document`, :class:`.ClipboardData`) tuple, where the
+        document represents the new document when the selection is cut, and the
+        clipboard data, represents whatever has to be put on the clipboard.
+        """
+        if self.selection:
+            cut_parts = []
+            remaining_parts = []
+            new_cursor_position = self.cursor_position
+
+            last_to = 0
+            for from_, to in self.selection_ranges():
+                if last_to == 0:
+                    new_cursor_position = from_
+
+                remaining_parts.append(self.text[last_to:from_])
+                cut_parts.append(self.text[from_:to])
+                last_to = to
+
+            remaining_parts.append(self.text[last_to:])
+
+            cut_text = "\n".join(cut_parts)
+            remaining_text = "".join(remaining_parts)
+
+            # In case of a LINES selection, don't include the trailing newline.
+            if self.selection.type == SelectionType.LINES and cut_text.endswith("\n"):
+                cut_text = cut_text[:-1]
+
+            return (
+                Document(text=remaining_text, cursor_position=new_cursor_position),
+                ClipboardData(cut_text, self.selection.type),
+            )
+        else:
+            return self, ClipboardData("")
+
+    def paste_clipboard_data(
+        self,
+        data: ClipboardData,
+        paste_mode: PasteMode = PasteMode.EMACS,
+        count: int = 1,
+    ) -> Document:
+        """
+        Return a new :class:`.Document` instance which contains the result if
+        we would paste this data at the current cursor position.
+
+        :param paste_mode: Where to paste. (Before/after/emacs.)
+        :param count: When >1, Paste multiple times.
+        """
+        before = paste_mode == PasteMode.VI_BEFORE
+        after = paste_mode == PasteMode.VI_AFTER
+
+        if data.type == SelectionType.CHARACTERS:
+            if after:
+                new_text = (
+                    self.text[: self.cursor_position + 1]
+                    + data.text * count
+                    + self.text[self.cursor_position + 1 :]
+                )
+            else:
+                new_text = (
+                    self.text_before_cursor + data.text * count + self.text_after_cursor
+                )
+
+            new_cursor_position = self.cursor_position + len(data.text) * count
+            if before:
+                new_cursor_position -= 1
+
+        elif data.type == SelectionType.LINES:
+            l = self.cursor_position_row
+            if before:
+                lines = self.lines[:l] + [data.text] * count + self.lines[l:]
+                new_text = "\n".join(lines)
+                new_cursor_position = len("".join(self.lines[:l])) + l
+            else:
+                lines = self.lines[: l + 1] + [data.text] * count + self.lines[l + 1 :]
+                new_cursor_position = len("".join(self.lines[: l + 1])) + l + 1
+                new_text = "\n".join(lines)
+
+        elif data.type == SelectionType.BLOCK:
+            lines = self.lines[:]
+            start_line = self.cursor_position_row
+            start_column = self.cursor_position_col + (0 if before else 1)
+
+            for i, line in enumerate(data.text.split("\n")):
+                index = i + start_line
+                if index >= len(lines):
+                    lines.append("")
+
+                lines[index] = lines[index].ljust(start_column)
+                lines[index] = (
+                    lines[index][:start_column]
+                    + line * count
+                    + lines[index][start_column:]
+                )
+
+            new_text = "\n".join(lines)
+            new_cursor_position = self.cursor_position + (0 if before else 1)
+
+        return Document(text=new_text, cursor_position=new_cursor_position)
+
+    def empty_line_count_at_the_end(self) -> int:
+        """
+        Return number of empty lines at the end of the document.
+        """
+        count = 0
+        for line in self.lines[::-1]:
+            if not line or line.isspace():
+                count += 1
+            else:
+                break
+
+        return count
+
+    def start_of_paragraph(self, count: int = 1, before: bool = False) -> int:
+        """
+        Return the start of the current paragraph. (Relative cursor position.)
+        """
+
+        def match_func(text: str) -> bool:
+            return not text or text.isspace()
+
+        line_index = self.find_previous_matching_line(
+            match_func=match_func, count=count
+        )
+
+        if line_index:
+            add = 0 if before else 1
+            return min(0, self.get_cursor_up_position(count=-line_index) + add)
+        else:
+            return -self.cursor_position
+
+    def end_of_paragraph(self, count: int = 1, after: bool = False) -> int:
+        """
+        Return the end of the current paragraph. (Relative cursor position.)
+        """
+
+        def match_func(text: str) -> bool:
+            return not text or text.isspace()
+
+        line_index = self.find_next_matching_line(match_func=match_func, count=count)
+
+        if line_index:
+            add = 0 if after else 1
+            return max(0, self.get_cursor_down_position(count=line_index) - add)
+        else:
+            return len(self.text_after_cursor)
+
+    # Modifiers.
+
+    def insert_after(self, text: str) -> Document:
+        """
+        Create a new document, with this text inserted after the buffer.
+        It keeps selection ranges and cursor position in sync.
+        """
+        return Document(
+            text=self.text + text,
+            cursor_position=self.cursor_position,
+            selection=self.selection,
+        )
+
+    def insert_before(self, text: str) -> Document:
+        """
+        Create a new document, with this text inserted before the buffer.
+        It keeps selection ranges and cursor position in sync.
+        """
+        selection_state = self.selection
+
+        if selection_state:
+            selection_state = SelectionState(
+                original_cursor_position=selection_state.original_cursor_position
+                + len(text),
+                type=selection_state.type,
+            )
+
+        return Document(
+            text=text + self.text,
+            cursor_position=self.cursor_position + len(text),
+            selection=selection_state,
+        )

lib/python3.12/site-packages/prompt_toolkit/enums.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class EditingMode(Enum):
+    # The set of key bindings that is active.
+    VI = "VI"
+    EMACS = "EMACS"
+
+
+#: Name of the search buffer.
+SEARCH_BUFFER = "SEARCH_BUFFER"
+
+#: Name of the default buffer.
+DEFAULT_BUFFER = "DEFAULT_BUFFER"
+
+#: Name of the system buffer.
+SYSTEM_BUFFER = "SYSTEM_BUFFER"

lib/python3.12/site-packages/prompt_toolkit/filters/__init__.py

@@ -0,0 +1,71 @@
+"""
+Filters decide whether something is active or not (they decide about a boolean
+state). This is used to enable/disable features, like key bindings, parts of
+the layout and other stuff. For instance, we could have a `HasSearch` filter
+attached to some part of the layout, in order to show that part of the user
+interface only while the user is searching.
+
+Filters are made to avoid having to attach callbacks to all event in order to
+propagate state. However, they are lazy, they don't automatically propagate the
+state of what they are observing. Only when a filter is called (it's actually a
+callable), it will calculate its value. So, its not really reactive
+programming, but it's made to fit for this framework.
+
+Filters can be chained using ``&`` and ``|`` operations, and inverted using the
+``~`` operator, for instance::
+
+    filter = has_focus('default') & ~ has_selection
+"""
+
+from __future__ import annotations
+
+from .app import *
+from .base import Always, Condition, Filter, FilterOrBool, Never
+from .cli import *
+from .utils import is_true, to_filter
+
+__all__ = [
+    # app
+    "has_arg",
+    "has_completions",
+    "completion_is_selected",
+    "has_focus",
+    "buffer_has_focus",
+    "has_selection",
+    "has_validation_error",
+    "is_done",
+    "is_read_only",
+    "is_multiline",
+    "renderer_height_is_known",
+    "in_editing_mode",
+    "in_paste_mode",
+    "vi_mode",
+    "vi_navigation_mode",
+    "vi_insert_mode",
+    "vi_insert_multiple_mode",
+    "vi_replace_mode",
+    "vi_selection_mode",
+    "vi_waiting_for_text_object_mode",
+    "vi_digraph_mode",
+    "vi_recording_macro",
+    "emacs_mode",
+    "emacs_insert_mode",
+    "emacs_selection_mode",
+    "shift_selection_mode",
+    "is_searching",
+    "control_is_searchable",
+    "vi_search_direction_reversed",
+    # base.
+    "Filter",
+    "Never",
+    "Always",
+    "Condition",
+    "FilterOrBool",
+    # utils.
+    "is_true",
+    "to_filter",
+]
+
+from .cli import __all__ as cli_all
+
+__all__.extend(cli_all)

lib/python3.12/site-packages/prompt_toolkit/filters/app.py

@@ -0,0 +1,419 @@
+"""
+Filters that accept a `Application` as argument.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from prompt_toolkit.application.current import get_app
+from prompt_toolkit.cache import memoized
+from prompt_toolkit.enums import EditingMode
+
+from .base import Condition
+
+if TYPE_CHECKING:
+    from prompt_toolkit.layout.layout import FocusableElement
+
+
+__all__ = [
+    "has_arg",
+    "has_completions",
+    "completion_is_selected",
+    "has_focus",
+    "buffer_has_focus",
+    "has_selection",
+    "has_suggestion",
+    "has_validation_error",
+    "is_done",
+    "is_read_only",
+    "is_multiline",
+    "renderer_height_is_known",
+    "in_editing_mode",
+    "in_paste_mode",
+    "vi_mode",
+    "vi_navigation_mode",
+    "vi_insert_mode",
+    "vi_insert_multiple_mode",
+    "vi_replace_mode",
+    "vi_selection_mode",
+    "vi_waiting_for_text_object_mode",
+    "vi_digraph_mode",
+    "vi_recording_macro",
+    "emacs_mode",
+    "emacs_insert_mode",
+    "emacs_selection_mode",
+    "shift_selection_mode",
+    "is_searching",
+    "control_is_searchable",
+    "vi_search_direction_reversed",
+]
+
+
+# NOTE: `has_focus` below should *not* be `memoized`. It can reference any user
+#       control. For instance, if we would continuously create new
+#       `PromptSession` instances, then previous instances won't be released,
+#       because this memoize (which caches results in the global scope) will
+#       still refer to each instance.
+def has_focus(value: FocusableElement) -> Condition:
+    """
+    Enable when this buffer has the focus.
+    """
+    from prompt_toolkit.buffer import Buffer
+    from prompt_toolkit.layout import walk
+    from prompt_toolkit.layout.containers import Window, to_container
+    from prompt_toolkit.layout.controls import UIControl
+
+    if isinstance(value, str):
+
+        def test() -> bool:
+            return get_app().current_buffer.name == value
+
+    elif isinstance(value, Buffer):
+
+        def test() -> bool:
+            return get_app().current_buffer == value
+
+    elif isinstance(value, UIControl):
+
+        def test() -> bool:
+            return get_app().layout.current_control == value
+
+    else:
+        value = to_container(value)
+
+        if isinstance(value, Window):
+
+            def test() -> bool:
+                return get_app().layout.current_window == value
+
+        else:
+
+            def test() -> bool:
+                # Consider focused when any window inside this container is
+                # focused.
+                current_window = get_app().layout.current_window
+
+                for c in walk(value):
+                    if isinstance(c, Window) and c == current_window:
+                        return True
+                return False
+
+    @Condition
+    def has_focus_filter() -> bool:
+        return test()
+
+    return has_focus_filter
+
+
+@Condition
+def buffer_has_focus() -> bool:
+    """
+    Enabled when the currently focused control is a `BufferControl`.
+    """
+    return get_app().layout.buffer_has_focus
+
+
+@Condition
+def has_selection() -> bool:
+    """
+    Enable when the current buffer has a selection.
+    """
+    return bool(get_app().current_buffer.selection_state)
+
+
+@Condition
+def has_suggestion() -> bool:
+    """
+    Enable when the current buffer has a suggestion.
+    """
+    buffer = get_app().current_buffer
+    return buffer.suggestion is not None and buffer.suggestion.text != ""
+
+
+@Condition
+def has_completions() -> bool:
+    """
+    Enable when the current buffer has completions.
+    """
+    state = get_app().current_buffer.complete_state
+    return state is not None and len(state.completions) > 0
+
+
+@Condition
+def completion_is_selected() -> bool:
+    """
+    True when the user selected a completion.
+    """
+    complete_state = get_app().current_buffer.complete_state
+    return complete_state is not None and complete_state.current_completion is not None
+
+
+@Condition
+def is_read_only() -> bool:
+    """
+    True when the current buffer is read only.
+    """
+    return get_app().current_buffer.read_only()
+
+
+@Condition
+def is_multiline() -> bool:
+    """
+    True when the current buffer has been marked as multiline.
+    """
+    return get_app().current_buffer.multiline()
+
+
+@Condition
+def has_validation_error() -> bool:
+    "Current buffer has validation error."
+    return get_app().current_buffer.validation_error is not None
+
+
+@Condition
+def has_arg() -> bool:
+    "Enable when the input processor has an 'arg'."
+    return get_app().key_processor.arg is not None
+
+
+@Condition
+def is_done() -> bool:
+    """
+    True when the CLI is returning, aborting or exiting.
+    """
+    return get_app().is_done
+
+
+@Condition
+def renderer_height_is_known() -> bool:
+    """
+    Only True when the renderer knows it's real height.
+
+    (On VT100 terminals, we have to wait for a CPR response, before we can be
+    sure of the available height between the cursor position and the bottom of
+    the terminal. And usually it's nicer to wait with drawing bottom toolbars
+    until we receive the height, in order to avoid flickering -- first drawing
+    somewhere in the middle, and then again at the bottom.)
+    """
+    return get_app().renderer.height_is_known
+
+
+@memoized()
+def in_editing_mode(editing_mode: EditingMode) -> Condition:
+    """
+    Check whether a given editing mode is active. (Vi or Emacs.)
+    """
+
+    @Condition
+    def in_editing_mode_filter() -> bool:
+        return get_app().editing_mode == editing_mode
+
+    return in_editing_mode_filter
+
+
+@Condition
+def in_paste_mode() -> bool:
+    return get_app().paste_mode()
+
+
+@Condition
+def vi_mode() -> bool:
+    return get_app().editing_mode == EditingMode.VI
+
+
+@Condition
+def vi_navigation_mode() -> bool:
+    """
+    Active when the set for Vi navigation key bindings are active.
+    """
+    from prompt_toolkit.key_binding.vi_state import InputMode
+
+    app = get_app()
+
+    if (
+        app.editing_mode != EditingMode.VI
+        or app.vi_state.operator_func
+        or app.vi_state.waiting_for_digraph
+        or app.current_buffer.selection_state
+    ):
+        return False
+
+    return (
+        app.vi_state.input_mode == InputMode.NAVIGATION
+        or app.vi_state.temporary_navigation_mode
+        or app.current_buffer.read_only()
+    )
+
+
+@Condition
+def vi_insert_mode() -> bool:
+    from prompt_toolkit.key_binding.vi_state import InputMode
+
+    app = get_app()
+
+    if (
+        app.editing_mode != EditingMode.VI
+        or app.vi_state.operator_func
+        or app.vi_state.waiting_for_digraph
+        or app.current_buffer.selection_state
+        or app.vi_state.temporary_navigation_mode
+        or app.current_buffer.read_only()
+    ):
+        return False
+
+    return app.vi_state.input_mode == InputMode.INSERT
+
+
+@Condition
+def vi_insert_multiple_mode() -> bool:
+    from prompt_toolkit.key_binding.vi_state import InputMode
+
+    app = get_app()
+
+    if (
+        app.editing_mode != EditingMode.VI
+        or app.vi_state.operator_func
+        or app.vi_state.waiting_for_digraph
+        or app.current_buffer.selection_state
+        or app.vi_state.temporary_navigation_mode
+        or app.current_buffer.read_only()
+    ):
+        return False
+
+    return app.vi_state.input_mode == InputMode.INSERT_MULTIPLE
+
+
+@Condition
+def vi_replace_mode() -> bool:
+    from prompt_toolkit.key_binding.vi_state import InputMode
+
+    app = get_app()
+
+    if (
+        app.editing_mode != EditingMode.VI
+        or app.vi_state.operator_func
+        or app.vi_state.waiting_for_digraph
+        or app.current_buffer.selection_state
+        or app.vi_state.temporary_navigation_mode
+        or app.current_buffer.read_only()
+    ):
+        return False
+
+    return app.vi_state.input_mode == InputMode.REPLACE
+
+
+@Condition
+def vi_replace_single_mode() -> bool:
+    from prompt_toolkit.key_binding.vi_state import InputMode
+
+    app = get_app()
+
+    if (
+        app.editing_mode != EditingMode.VI
+        or app.vi_state.operator_func
+        or app.vi_state.waiting_for_digraph
+        or app.current_buffer.selection_state
+        or app.vi_state.temporary_navigation_mode
+        or app.current_buffer.read_only()
+    ):
+        return False
+
+    return app.vi_state.input_mode == InputMode.REPLACE_SINGLE
+
+
+@Condition
+def vi_selection_mode() -> bool:
+    app = get_app()
+    if app.editing_mode != EditingMode.VI:
+        return False
+
+    return bool(app.current_buffer.selection_state)
+
+
+@Condition
+def vi_waiting_for_text_object_mode() -> bool:
+    app = get_app()
+    if app.editing_mode != EditingMode.VI:
+        return False
+
+    return app.vi_state.operator_func is not None
+
+
+@Condition
+def vi_digraph_mode() -> bool:
+    app = get_app()
+    if app.editing_mode != EditingMode.VI:
+        return False
+
+    return app.vi_state.waiting_for_digraph
+
+
+@Condition
+def vi_recording_macro() -> bool:
+    "When recording a Vi macro."
+    app = get_app()
+    if app.editing_mode != EditingMode.VI:
+        return False
+
+    return app.vi_state.recording_register is not None
+
+
+@Condition
+def emacs_mode() -> bool:
+    "When the Emacs bindings are active."
+    return get_app().editing_mode == EditingMode.EMACS
+
+
+@Condition
+def emacs_insert_mode() -> bool:
+    app = get_app()
+    if (
+        app.editing_mode != EditingMode.EMACS
+        or app.current_buffer.selection_state
+        or app.current_buffer.read_only()
+    ):
+        return False
+    return True
+
+
+@Condition
+def emacs_selection_mode() -> bool:
+    app = get_app()
+    return bool(
+        app.editing_mode == EditingMode.EMACS and app.current_buffer.selection_state
+    )
+
+
+@Condition
+def shift_selection_mode() -> bool:
+    app = get_app()
+    return bool(
+        app.current_buffer.selection_state
+        and app.current_buffer.selection_state.shift_mode
+    )
+
+
+@Condition
+def is_searching() -> bool:
+    "When we are searching."
+    app = get_app()
+    return app.layout.is_searching
+
+
+@Condition
+def control_is_searchable() -> bool:
+    "When the current UIControl is searchable."
+    from prompt_toolkit.layout.controls import BufferControl
+
+    control = get_app().layout.current_control
+
+    return (
+        isinstance(control, BufferControl) and control.search_buffer_control is not None
+    )
+
+
+@Condition
+def vi_search_direction_reversed() -> bool:
+    "When the '/' and '?' key bindings for Vi-style searching have been reversed."
+    return get_app().reverse_vi_search_direction()

lib/python3.12/site-packages/prompt_toolkit/filters/base.py

@@ -0,0 +1,260 @@
+from __future__ import annotations
+
+from abc import ABCMeta, abstractmethod
+from typing import Callable, Iterable, Union
+
+__all__ = ["Filter", "Never", "Always", "Condition", "FilterOrBool"]
+
+
+class Filter(metaclass=ABCMeta):
+    """
+    Base class for any filter to activate/deactivate a feature, depending on a
+    condition.
+
+    The return value of ``__call__`` will tell if the feature should be active.
+    """
+
+    def __init__(self) -> None:
+        self._and_cache: dict[Filter, Filter] = {}
+        self._or_cache: dict[Filter, Filter] = {}
+        self._invert_result: Filter | None = None
+
+    @abstractmethod
+    def __call__(self) -> bool:
+        """
+        The actual call to evaluate the filter.
+        """
+        return True
+
+    def __and__(self, other: Filter) -> Filter:
+        """
+        Chaining of filters using the & operator.
+        """
+        assert isinstance(other, Filter), f"Expecting filter, got {other!r}"
+
+        if isinstance(other, Always):
+            return self
+        if isinstance(other, Never):
+            return other
+
+        if other in self._and_cache:
+            return self._and_cache[other]
+
+        result = _AndList.create([self, other])
+        self._and_cache[other] = result
+        return result
+
+    def __or__(self, other: Filter) -> Filter:
+        """
+        Chaining of filters using the | operator.
+        """
+        assert isinstance(other, Filter), f"Expecting filter, got {other!r}"
+
+        if isinstance(other, Always):
+            return other
+        if isinstance(other, Never):
+            return self
+
+        if other in self._or_cache:
+            return self._or_cache[other]
+
+        result = _OrList.create([self, other])
+        self._or_cache[other] = result
+        return result
+
+    def __invert__(self) -> Filter:
+        """
+        Inverting of filters using the ~ operator.
+        """
+        if self._invert_result is None:
+            self._invert_result = _Invert(self)
+
+        return self._invert_result
+
+    def __bool__(self) -> None:
+        """
+        By purpose, we don't allow bool(...) operations directly on a filter,
+        because the meaning is ambiguous.
+
+        Executing a filter has to be done always by calling it. Providing
+        defaults for `None` values should be done through an `is None` check
+        instead of for instance ``filter1 or Always()``.
+        """
+        raise ValueError(
+            "The truth value of a Filter is ambiguous. Instead, call it as a function."
+        )
+
+
+def _remove_duplicates(filters: list[Filter]) -> list[Filter]:
+    result = []
+    for f in filters:
+        if f not in result:
+            result.append(f)
+    return result
+
+
+class _AndList(Filter):
+    """
+    Result of &-operation between several filters.
+    """
+
+    def __init__(self, filters: list[Filter]) -> None:
+        super().__init__()
+        self.filters = filters
+
+    @classmethod
+    def create(cls, filters: Iterable[Filter]) -> Filter:
+        """
+        Create a new filter by applying an `&` operator between them.
+
+        If there's only one unique filter in the given iterable, it will return
+        that one filter instead of an `_AndList`.
+        """
+        filters_2: list[Filter] = []
+
+        for f in filters:
+            if isinstance(f, _AndList):  # Turn nested _AndLists into one.
+                filters_2.extend(f.filters)
+            else:
+                filters_2.append(f)
+
+        # Remove duplicates. This could speed up execution, and doesn't make a
+        # difference for the evaluation.
+        filters = _remove_duplicates(filters_2)
+
+        # If only one filter is left, return that without wrapping into an
+        # `_AndList`.
+        if len(filters) == 1:
+            return filters[0]
+
+        return cls(filters)
+
+    def __call__(self) -> bool:
+        return all(f() for f in self.filters)
+
+    def __repr__(self) -> str:
+        return "&".join(repr(f) for f in self.filters)
+
+
+class _OrList(Filter):
+    """
+    Result of |-operation between several filters.
+    """
+
+    def __init__(self, filters: list[Filter]) -> None:
+        super().__init__()
+        self.filters = filters
+
+    @classmethod
+    def create(cls, filters: Iterable[Filter]) -> Filter:
+        """
+        Create a new filter by applying an `|` operator between them.
+
+        If there's only one unique filter in the given iterable, it will return
+        that one filter instead of an `_OrList`.
+        """
+        filters_2: list[Filter] = []
+
+        for f in filters:
+            if isinstance(f, _OrList):  # Turn nested _AndLists into one.
+                filters_2.extend(f.filters)
+            else:
+                filters_2.append(f)
+
+        # Remove duplicates. This could speed up execution, and doesn't make a
+        # difference for the evaluation.
+        filters = _remove_duplicates(filters_2)
+
+        # If only one filter is left, return that without wrapping into an
+        # `_AndList`.
+        if len(filters) == 1:
+            return filters[0]
+
+        return cls(filters)
+
+    def __call__(self) -> bool:
+        return any(f() for f in self.filters)
+
+    def __repr__(self) -> str:
+        return "|".join(repr(f) for f in self.filters)
+
+
+class _Invert(Filter):
+    """
+    Negation of another filter.
+    """
+
+    def __init__(self, filter: Filter) -> None:
+        super().__init__()
+        self.filter = filter
+
+    def __call__(self) -> bool:
+        return not self.filter()
+
+    def __repr__(self) -> str:
+        return f"~{self.filter!r}"
+
+
+class Always(Filter):
+    """
+    Always enable feature.
+    """
+
+    def __call__(self) -> bool:
+        return True
+
+    def __or__(self, other: Filter) -> Filter:
+        return self
+
+    def __and__(self, other: Filter) -> Filter:
+        return other
+
+    def __invert__(self) -> Never:
+        return Never()
+
+
+class Never(Filter):
+    """
+    Never enable feature.
+    """
+
+    def __call__(self) -> bool:
+        return False
+
+    def __and__(self, other: Filter) -> Filter:
+        return self
+
+    def __or__(self, other: Filter) -> Filter:
+        return other
+
+    def __invert__(self) -> Always:
+        return Always()
+
+
+class Condition(Filter):
+    """
+    Turn any callable into a Filter. The callable is supposed to not take any
+    arguments.
+
+    This can be used as a decorator::
+
+        @Condition
+        def feature_is_active():  # `feature_is_active` becomes a Filter.
+            return True
+
+    :param func: Callable which takes no inputs and returns a boolean.
+    """
+
+    def __init__(self, func: Callable[[], bool]) -> None:
+        super().__init__()
+        self.func = func
+
+    def __call__(self) -> bool:
+        return self.func()
+
+    def __repr__(self) -> str:
+        return f"Condition({self.func!r})"
+
+
+# Often used as type annotation.
+FilterOrBool = Union[Filter, bool]

lib/python3.12/site-packages/prompt_toolkit/filters/cli.py

@@ -0,0 +1,65 @@
+"""
+For backwards-compatibility. keep this file.
+(Many people are going to have key bindings that rely on this file.)
+"""
+
+from __future__ import annotations
+
+from .app import *
+
+__all__ = [
+    # Old names.
+    "HasArg",
+    "HasCompletions",
+    "HasFocus",
+    "HasSelection",
+    "HasValidationError",
+    "IsDone",
+    "IsReadOnly",
+    "IsMultiline",
+    "RendererHeightIsKnown",
+    "InEditingMode",
+    "InPasteMode",
+    "ViMode",
+    "ViNavigationMode",
+    "ViInsertMode",
+    "ViInsertMultipleMode",
+    "ViReplaceMode",
+    "ViSelectionMode",
+    "ViWaitingForTextObjectMode",
+    "ViDigraphMode",
+    "EmacsMode",
+    "EmacsInsertMode",
+    "EmacsSelectionMode",
+    "IsSearching",
+    "HasSearch",
+    "ControlIsSearchable",
+]
+
+# Keep the original classnames for backwards compatibility.
+HasValidationError = lambda: has_validation_error
+HasArg = lambda: has_arg
+IsDone = lambda: is_done
+RendererHeightIsKnown = lambda: renderer_height_is_known
+ViNavigationMode = lambda: vi_navigation_mode
+InPasteMode = lambda: in_paste_mode
+EmacsMode = lambda: emacs_mode
+EmacsInsertMode = lambda: emacs_insert_mode
+ViMode = lambda: vi_mode
+IsSearching = lambda: is_searching
+HasSearch = lambda: is_searching
+ControlIsSearchable = lambda: control_is_searchable
+EmacsSelectionMode = lambda: emacs_selection_mode
+ViDigraphMode = lambda: vi_digraph_mode
+ViWaitingForTextObjectMode = lambda: vi_waiting_for_text_object_mode
+ViSelectionMode = lambda: vi_selection_mode
+ViReplaceMode = lambda: vi_replace_mode
+ViInsertMultipleMode = lambda: vi_insert_multiple_mode
+ViInsertMode = lambda: vi_insert_mode
+HasSelection = lambda: has_selection
+HasCompletions = lambda: has_completions
+IsReadOnly = lambda: is_read_only
+IsMultiline = lambda: is_multiline
+
+HasFocus = has_focus  # No lambda here! (Has_focus is callable that returns a callable.)
+InEditingMode = in_editing_mode

lib/python3.12/site-packages/prompt_toolkit/filters/utils.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from .base import Always, Filter, FilterOrBool, Never
+
+__all__ = [
+    "to_filter",
+    "is_true",
+]
+
+
+_always = Always()
+_never = Never()
+
+
+_bool_to_filter: dict[bool, Filter] = {
+    True: _always,
+    False: _never,
+}
+
+
+def to_filter(bool_or_filter: FilterOrBool) -> Filter:
+    """
+    Accept both booleans and Filters as input and
+    turn it into a Filter.
+    """
+    if isinstance(bool_or_filter, bool):
+        return _bool_to_filter[bool_or_filter]
+
+    if isinstance(bool_or_filter, Filter):
+        return bool_or_filter
+
+    raise TypeError(f"Expecting a bool or a Filter instance. Got {bool_or_filter!r}")
+
+
+def is_true(value: FilterOrBool) -> bool:
+    """
+    Test whether `value` is True. In case of a Filter, call it.
+
+    :param value: Boolean or `Filter` instance.
+    """
+    return to_filter(value)()

lib/python3.12/site-packages/prompt_toolkit/history.py

@@ -0,0 +1,306 @@
+"""
+Implementations for the history of a `Buffer`.
+
+NOTE: There is no `DynamicHistory`:
+      This doesn't work well, because the `Buffer` needs to be able to attach
+      an event handler to the event when a history entry is loaded. This
+      loading can be done asynchronously and making the history swappable would
+      probably break this.
+"""
+
+from __future__ import annotations
+
+import datetime
+import os
+import threading
+from abc import ABCMeta, abstractmethod
+from asyncio import get_running_loop
+from typing import AsyncGenerator, Iterable, Sequence, Union
+
+__all__ = [
+    "History",
+    "ThreadedHistory",
+    "DummyHistory",
+    "FileHistory",
+    "InMemoryHistory",
+]
+
+
+class History(metaclass=ABCMeta):
+    """
+    Base ``History`` class.
+
+    This also includes abstract methods for loading/storing history.
+    """
+
+    def __init__(self) -> None:
+        # In memory storage for strings.
+        self._loaded = False
+
+        # History that's loaded already, in reverse order. Latest, most recent
+        # item first.
+        self._loaded_strings: list[str] = []
+
+    #
+    # Methods expected by `Buffer`.
+    #
+
+    async def load(self) -> AsyncGenerator[str, None]:
+        """
+        Load the history and yield all the entries in reverse order (latest,
+        most recent history entry first).
+
+        This method can be called multiple times from the `Buffer` to
+        repopulate the history when prompting for a new input. So we are
+        responsible here for both caching, and making sure that strings that
+        were were appended to the history will be incorporated next time this
+        method is called.
+        """
+        if not self._loaded:
+            self._loaded_strings = list(self.load_history_strings())
+            self._loaded = True
+
+        for item in self._loaded_strings:
+            yield item
+
+    def get_strings(self) -> list[str]:
+        """
+        Get the strings from the history that are loaded so far.
+        (In order. Oldest item first.)
+        """
+        return self._loaded_strings[::-1]
+
+    def append_string(self, string: str) -> None:
+        "Add string to the history."
+        self._loaded_strings.insert(0, string)
+        self.store_string(string)
+
+    #
+    # Implementation for specific backends.
+    #
+
+    @abstractmethod
+    def load_history_strings(self) -> Iterable[str]:
+        """
+        This should be a generator that yields `str` instances.
+
+        It should yield the most recent items first, because they are the most
+        important. (The history can already be used, even when it's only
+        partially loaded.)
+        """
+        while False:
+            yield
+
+    @abstractmethod
+    def store_string(self, string: str) -> None:
+        """
+        Store the string in persistent storage.
+        """
+
+
+class ThreadedHistory(History):
+    """
+    Wrapper around `History` implementations that run the `load()` generator in
+    a thread.
+
+    Use this to increase the start-up time of prompt_toolkit applications.
+    History entries are available as soon as they are loaded. We don't have to
+    wait for everything to be loaded.
+    """
+
+    def __init__(self, history: History) -> None:
+        super().__init__()
+
+        self.history = history
+
+        self._load_thread: threading.Thread | None = None
+
+        # Lock for accessing/manipulating `_loaded_strings` and `_loaded`
+        # together in a consistent state.
+        self._lock = threading.Lock()
+
+        # Events created by each `load()` call. Used to wait for new history
+        # entries from the loader thread.
+        self._string_load_events: list[threading.Event] = []
+
+    async def load(self) -> AsyncGenerator[str, None]:
+        """
+        Like `History.load(), but call `self.load_history_strings()` in a
+        background thread.
+        """
+        # Start the load thread, if this is called for the first time.
+        if not self._load_thread:
+            self._load_thread = threading.Thread(
+                target=self._in_load_thread,
+                daemon=True,
+            )
+            self._load_thread.start()
+
+        # Consume the `_loaded_strings` list, using asyncio.
+        loop = get_running_loop()
+
+        # Create threading Event so that we can wait for new items.
+        event = threading.Event()
+        event.set()
+        self._string_load_events.append(event)
+
+        items_yielded = 0
+
+        try:
+            while True:
+                # Wait for new items to be available.
+                # (Use a timeout, because the executor thread is not a daemon
+                # thread. The "slow-history.py" example would otherwise hang if
+                # Control-C is pressed before the history is fully loaded,
+                # because there's still this non-daemon executor thread waiting
+                # for this event.)
+                got_timeout = await loop.run_in_executor(
+                    None, lambda: event.wait(timeout=0.5)
+                )
+                if not got_timeout:
+                    continue
+
+                # Read new items (in lock).
+                def in_executor() -> tuple[list[str], bool]:
+                    with self._lock:
+                        new_items = self._loaded_strings[items_yielded:]
+                        done = self._loaded
+                        event.clear()
+                    return new_items, done
+
+                new_items, done = await loop.run_in_executor(None, in_executor)
+
+                items_yielded += len(new_items)
+
+                for item in new_items:
+                    yield item
+
+                if done:
+                    break
+        finally:
+            self._string_load_events.remove(event)
+
+    def _in_load_thread(self) -> None:
+        try:
+            # Start with an empty list. In case `append_string()` was called
+            # before `load()` happened. Then `.store_string()` will have
+            # written these entries back to disk and we will reload it.
+            self._loaded_strings = []
+
+            for item in self.history.load_history_strings():
+                with self._lock:
+                    self._loaded_strings.append(item)
+
+                for event in self._string_load_events:
+                    event.set()
+        finally:
+            with self._lock:
+                self._loaded = True
+            for event in self._string_load_events:
+                event.set()
+
+    def append_string(self, string: str) -> None:
+        with self._lock:
+            self._loaded_strings.insert(0, string)
+        self.store_string(string)
+
+    # All of the following are proxied to `self.history`.
+
+    def load_history_strings(self) -> Iterable[str]:
+        return self.history.load_history_strings()
+
+    def store_string(self, string: str) -> None:
+        self.history.store_string(string)
+
+    def __repr__(self) -> str:
+        return f"ThreadedHistory({self.history!r})"
+
+
+class InMemoryHistory(History):
+    """
+    :class:`.History` class that keeps a list of all strings in memory.
+
+    In order to prepopulate the history, it's possible to call either
+    `append_string` for all items or pass a list of strings to `__init__` here.
+    """
+
+    def __init__(self, history_strings: Sequence[str] | None = None) -> None:
+        super().__init__()
+        # Emulating disk storage.
+        if history_strings is None:
+            self._storage = []
+        else:
+            self._storage = list(history_strings)
+
+    def load_history_strings(self) -> Iterable[str]:
+        yield from self._storage[::-1]
+
+    def store_string(self, string: str) -> None:
+        self._storage.append(string)
+
+
+class DummyHistory(History):
+    """
+    :class:`.History` object that doesn't remember anything.
+    """
+
+    def load_history_strings(self) -> Iterable[str]:
+        return []
+
+    def store_string(self, string: str) -> None:
+        pass
+
+    def append_string(self, string: str) -> None:
+        # Don't remember this.
+        pass
+
+
+_StrOrBytesPath = Union[str, bytes, "os.PathLike[str]", "os.PathLike[bytes]"]
+
+
+class FileHistory(History):
+    """
+    :class:`.History` class that stores all strings in a file.
+    """
+
+    def __init__(self, filename: _StrOrBytesPath) -> None:
+        self.filename = filename
+        super().__init__()
+
+    def load_history_strings(self) -> Iterable[str]:
+        strings: list[str] = []
+        lines: list[str] = []
+
+        def add() -> None:
+            if lines:
+                # Join and drop trailing newline.
+                string = "".join(lines)[:-1]
+
+                strings.append(string)
+
+        if os.path.exists(self.filename):
+            with open(self.filename, "rb") as f:
+                for line_bytes in f:
+                    line = line_bytes.decode("utf-8", errors="replace")
+
+                    if line.startswith("+"):
+                        lines.append(line[1:])
+                    else:
+                        add()
+                        lines = []
+
+                add()
+
+        # Reverse the order, because newest items have to go first.
+        return reversed(strings)
+
+    def store_string(self, string: str) -> None:
+        # Save to file.
+        with open(self.filename, "ab") as f:
+
+            def write(t: str) -> None:
+                f.write(t.encode("utf-8"))
+
+            write(f"\n# {datetime.datetime.now()}\n")
+            for line in string.split("\n"):
+                write(f"+{line}\n")

lib/python3.12/site-packages/prompt_toolkit/key_binding/__init__.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from .key_bindings import (
+    ConditionalKeyBindings,
+    DynamicKeyBindings,
+    KeyBindings,
+    KeyBindingsBase,
+    merge_key_bindings,
+)
+from .key_processor import KeyPress, KeyPressEvent
+
+__all__ = [
+    # key_bindings.
+    "ConditionalKeyBindings",
+    "DynamicKeyBindings",
+    "KeyBindings",
+    "KeyBindingsBase",
+    "merge_key_bindings",
+    # key_processor
+    "KeyPress",
+    "KeyPressEvent",
+]