PyTermGUI 7.7.4__py3-none-any.whl → 7.8.1__py3-none-any.whl

CHANGELOG.md

@@ -1,11 +1,45 @@
-## [7.7.3] - 2024-12-29
+## [7.8.1] - 2026-09-10
 
 ### Bugfixes
 
-- Fix getch mapping for Windows keys
+- Fix multiline input navigation and joining lines with Backspace
+
+## [7.8.0] - 2026-08-10
+
+### Additions
+
+- Add grapheme-aware wrapping with correct widths for CJK and emoji sequences
+- Preserve ANSI styles and hyperlinks when wrapping text
+- Document terminal compatibility and the project's archived status
+
+### Bugfixes
+
+- Fix terminal clearing, synchronized frame recording, and resize handling
+- Fix multiline input cursor placement and nested container scrolling
+- Fix uneven splitter columns and automatically sized scrollable windows
+- Fix ANSI bright magenta, cyan, and white color mappings
+- Fix cursor-home and erase sequences in ANSI exports
+- Avoid busy-waiting for input on Windows
+
+### Maintenance
+
+- Modernize linting and packaging configuration
+- Remove obsolete project assets and tooling
 
 <!-- HATCH README END -->
 
+## [7.7.4] - 2025-03-31
+
+### Bugfixes
+
+- Fix rapid input to \_GetchLinux
+
+## [7.7.3] - 2024-12-29
+
+### Bugfixes
+
+- Fix getch mapping for Windows keys
+
 ## [7.7.2] - 2024-08-31
 
 ### Additions
@@ -416,6 +450,8 @@
 
 <!-- HATCH URI DEFINITIONS START -->
 
+[7.8.0]: https://github.com/bczsalba/pytermgui/compare/v7.7.4...v7.8.0
+[7.7.4]: https://github.com/bczsalba/pytermgui/compare/v7.7.3...v7.7.4
 [7.7.3]: https://github.com/bczsalba/pytermgui/compare/v7.7.2...v7.7.3
 [7.7.2]: https://github.com/bczsalba/pytermgui/compare/v7.7.1...v7.7.2
 [7.7.1]: https://github.com/bczsalba/pytermgui/compare/v7.7.0...v7.7.1

README.md

@@ -1,5 +1,3 @@
-<!--![title](https://github.com/bczsalba/pytermgui/raw/master/assets/title.png)-->
-
 ![title](https://github.com/bczsalba/pytermgui/raw/master/assets/readme/screenshot.png)
 
 > Python TUI framework with mouse support, modular widget system, customizable and rapid terminal markup language and more!
@@ -12,26 +10,20 @@ pip3 install pytermgui
    <a href="https://pypi.org/project/pytermgui">
       <img alt="PyPi project" src="https://img.shields.io/pypi/v/pytermgui?color=brightgreen">
    </a>
-    <a href="https://github.com/bczsalba/pytermgui/blob/master/utils/create_badge.py">
-      <img alt="Code quality" src="https://raw.githubusercontent.com/bczsalba/pytermgui/master/assets/badges/quality.svg">
-   </a>
-   <a href="http://ptg.bczsalba.com/">
-      <img src="https://img.shields.io/badge/documentation-up%20to%20date-brightgreen">
+   <a href="https://ptg.bczsalba.com/">
+      <img src="https://img.shields.io/badge/documentation-gray">
    </a>
    <a href="https://github.com/bczsalba/pytermgui/actions/workflows/pytest.yml">
       <img src="https://github.com/bczsalba/pytermgui/actions/workflows/pytest.yml/badge.svg">
    </a>
  </p>
- <p align=center>
-   <a href="https://discord.gg/g4bqMvpG4U">
-      <img src="https://img.shields.io/discord/999374285686706367?label=join%20our%20discord">
-   </a>
 </p>
 
-## Notice
+<hr>
 
-A much better, more complete version of PTG's core ideas now exists over at [Shade 40](https://github.com/shade40). While PTG is not yet fully obsolete,
-those libraries will be the primary focus of development going forward.
+## Archival notice
+
+PyTermGUI is no longer in development. The latest release will remain available, alongside its documentation. The MIT license allows for free modification of the library, as long as you include credit to its original author. Thank you for everything.
 
 <hr>
 
@@ -64,6 +56,16 @@ Additionally, there are a couple of neat tools to make your general Python devel
 - A pretty printer for both the REPL and IPython
 - A way to create SVG and HTML screenshots of your terminal
 
+### Terminal compatibility
+
+PyTermGUI relies on ANSI virtual-terminal sequences for rendering, cursor reports,
+keyboard input, and mouse input. On Windows, support depends on the terminal emulator's
+ANSI compatibility. [Windows Terminal](https://github.com/microsoft/terminal) supports
+the expected cursor and mouse protocols, while the legacy Windows Console Host
+(`conhost.exe`) may provide reduced functionality. This does not depend on whether
+PowerShell or Command Prompt is running inside the emulator. Mouse support also depends
+on the emulator forwarding the requested events.
+
 <!-- HATCH README END -->
 
 ## Examples
@@ -181,9 +183,9 @@ We use algorithms based on human vision to convert and downgrade colors when the
 
 ## Questions? See the docs!
 
-Pretty much every single name in the library, private or public, has an insightful dockstring attached to it, and we are accumulating a growing amount of walkthrough-based documentations articles. See 'em all on the [doc website](https://ptg.bczsalba.com)!
+Pretty much every name in the library, private or public, has an insightful docstring attached to it, alongside walkthrough-based documentation articles. See them all on the [documentation website](https://ptg.bczsalba.com)!
 
 
-## Contributions, issues et al.
+## Project status
 
-If you have any problems using the library, feel free to open up a discussion or raise an issue ticket. If you would prefer to hack on the library yourself, see the [contribution guidelines](https://github.com/bczsalba/pytermgui/blob/master/CONTRIBUTING.md). Pull requests are encouraged, but make sure you aren't trying to fix an issue that others are already working on, for your own sake. :slightly_smiling_face:
+PyTermGUI has reached its final release and is no longer under active development. The repository and its documentation are retained as an archive for existing users.

pytermgui/__init__.py

@@ -40,7 +40,7 @@ if "-m" in sys.argv:  # pragma: no cover
 
     warnings.filterwarnings("ignore")
 
-__version__ = "7.7.4"
+__version__ = "7.8.1"
 
 
 def auto(data: Any, **widget_args: Any) -> Optional[Widget | list[Splitter]]:

pytermgui/animations.py

@@ -23,7 +23,7 @@ from typing import TYPE_CHECKING, Any, Callable
 if TYPE_CHECKING:
     from .widgets import Widget
 else:
-    Widget = Any
+    Widget = Any  # pylint: disable=invalid-name
 
 __all__ = ["Animator", "FloatAnimation", "AttrAnimation", "animator", "is_animated"]
 

pytermgui/ansi_interface.py

@@ -116,7 +116,7 @@ def clear(what: str = "screen") -> None:
     commands = {
         "eos": "\x1b[0J",
         "bos": "\x1b[1J",
-        "screen": "\x1b[2J",
+        "screen": "\x1b[H\x1b[2J",
         "eol": "\x1b[0K",
         "bol": "\x1b[1K",
         "line": "\x1b[2K",

pytermgui/colors.py

@@ -68,9 +68,9 @@ XTERM_NAMED_COLORS = {
     10: "ansi-bright-green",
     11: "ansi-bright-yellow",
     12: "ansi-bright-blue",
-    14: "ansi-bright-magenta",
-    15: "ansi-bright-cyan",
-    16: "ansi-bright-white",
+    13: "ansi-bright-magenta",
+    14: "ansi-bright-cyan",
+    15: "ansi-bright-white",
 }
 
 NAMED_COLORS = {

pytermgui/exporters.py

@@ -273,7 +273,7 @@ def token_to_css(token: Token, invert: bool = False) -> str:
 
 # We take this many arguments for future proofing and customization, not much we can
 # do about it.
-def to_html(  # pylint: disable=too-many-arguments, too-many-locals
+def to_html(  # pylint: disable=too-many-arguments, too-many-locals, R0917
     obj: Widget | StyledText | str,
     prefix: str | None = None,
     inline_styles: bool = False,
@@ -441,7 +441,7 @@ def _make_tag(tagname: str, content: str = "", **attrs) -> str:
 
 # This is a bit of a beast of a function, but it does the job and IMO reducing it
 # into parts would just make our lives more complicated.
-def to_svg(  # pylint: disable=too-many-locals, too-many-arguments, too-many-statements, R0912
+def to_svg(  # pylint: disable=too-many-locals, too-many-arguments, too-many-statements, R0912, R0917
     obj: Widget | StyledText | str,
     prefix: str | None = None,
     chrome: bool = True,

pytermgui/file_loaders.py

@@ -131,14 +131,14 @@ from . import widgets as widgets_m
 from .markup import tim
 from .serialization import Serializer
 
-YAML_ERROR = None
+_yaml_error = None
 
 try:
     import yaml
 except ImportError as import_error:
     # yaml is explicitly checked to be None later
     yaml = None  # type: ignore
-    YAML_ERROR = import_error
+    _yaml_error = import_error
 
 
 __all__ = ["WidgetNamespace", "FileLoader", "YamlLoader", "JsonLoader"]
@@ -412,10 +412,10 @@ class YamlLoader(FileLoader):
     def __init__(self, serializer: Serializer | None = None) -> None:
         """Initialize object, check for installation of PyYAML."""
 
-        if YAML_ERROR is not None:
+        if _yaml_error is not None:
             raise RuntimeError(
                 "YAML implementation module not found. Please install `PyYAML` to use `YamlLoader`."
-            ) from YAML_ERROR
+            ) from _yaml_error
 
         super().__init__()
 

pytermgui/helpers.py

@@ -4,8 +4,8 @@ from __future__ import annotations
 
 from typing import Iterator
 
-from .markup import tokenize_ansi
-from .markup.parsing import LINK_TEMPLATE, PARSERS
+from wcwidth import wrap as wcwidth_wrap
+
 from .regex import real_length
 
 __all__ = [
@@ -13,17 +13,14 @@ __all__ = [
 ]
 
 
-def break_line(  # pylint: disable=too-many-branches
+def break_line(
     line: str, limit: int, non_first_limit: int | None = None, fill: str | None = None
 ) -> Iterator[str]:
     """Breaks a line into a `list[str]` with maximum `limit` length per line.
 
-    It keeps ongoing ANSI sequences between lines, and inserts a reset sequence
-    at the end of each style-containing line.
-
-    At the moment it splits strings exactly on the limit, and not on word
-    boundaries. That functionality would be preferred, so it will end up being
-    implemented at some point.
+    Uses wcwidth.wrap() for proper word-boundary breaking, grapheme cluster
+    handling, and wide character support. ANSI sequences are preserved and
+    propagated across line breaks.
 
     Args:
         line: The line to split. May or may not contain ANSI sequences.
@@ -31,83 +28,33 @@ def break_line(  # pylint: disable=too-many-branches
             non-printing sequences.
         non_first_limit: The limit after the first line. If not given, defaults
             to `limit`.
+        fill: Optional character to pad lines to the limit width.
     """
 
     if line in ["", "\x1b[0m"]:
         yield ""
         return
 
-    def _pad_and_link(line: str, link: str | None) -> str:
-        count = limit - real_length(line)
-
-        if link is not None:
-            line = LINK_TEMPLATE.format(uri=link, label=line)
-
+    def _pad_line(text: str, width: int) -> str:
         if fill is None:
-            return line
-
-        line += count * fill
-
-        return line
+            return text
 
-    used = 0
-    current = ""
-    sequences = ""
+        count = width - real_length(text)
+        if count > 0:
+            return text + count * fill
+        return text
 
     if non_first_limit is None:
         non_first_limit = limit
 
-    parsers = PARSERS
-    link = None
-
-    for token in tokenize_ansi(line):
-        if token.is_plain():
-            for char in token.value:
-                if char == "\n" or used >= limit:
-                    if sequences != "":
-                        current += "\x1b[0m"
-
-                    yield _pad_and_link(current, link)
-                    link = None
-
-                    current = sequences
-                    used = 0
-
-                    limit = non_first_limit
-
-                if char != "\n":
-                    current += char
-                    used += 1
-
-            # If the link wasn't yielded along with its token, remove and add it
-            # to current manually.
-            if link is not None:
-                current = current[: -len(token.value)]
-                current += LINK_TEMPLATE.format(uri=link, label=token.value)
-                link = None
-
-            continue
-
-        if token.value == "/":
-            sequences = "\x1b[0m"
-
-            if len(current) > 0:
-                current += sequences
-
+    for segment in line.split("\n"):
+        if not segment:
+            yield _pad_line("", limit)
+            limit = non_first_limit
             continue
 
-        if token.is_hyperlink():
-            link = token.value
-            continue
-
-        sequence = parsers[type(token)](token, {}, lambda: line)  # type: ignore
-        sequences += sequence
-        current += sequence
-
-    if current == "":
-        return
-
-    if sequences != "" and not current.endswith("\x1b[0m"):
-        current += "\x1b[0m"
+        wrapped = wcwidth_wrap(segment, limit)
 
-    yield _pad_and_link(current, link)
+        for wrapped_line in wrapped:
+            yield _pad_line(wrapped_line, limit)
+            limit = non_first_limit

pytermgui/input.py

@@ -5,10 +5,6 @@ Credits:
 
 - Original getch implementation: [Danny Yoo](https://code.activestate.com/recipes/134892)
 - Modern additions & idea:       [kcsaff](https://github.com/kcsaff/getkey)
-
-Note that the original link seems to no longer be active, but an archive can be found
-on [GitHub](https://github.com/ActiveState/code/tree/master/recipes/Python/
-134892_getchlike_unbuffered_character_reading_stdboth).
 """
 
 # pylint doesn't see the C source
@@ -134,7 +130,7 @@ class _GetchUnix:
 
         descriptor = sys.stdin.fileno()
         old_settings = termios.tcgetattr(descriptor)
-        tty.setcbreak(descriptor)
+        tty.setcbreak(descriptor, termios.TCSANOW)
 
         try:
             yield self._read(1)

pytermgui/inspector.py

@@ -175,7 +175,7 @@ def inspect(target: object, **inspector_args: Any) -> Inspector:
 class Inspector(Container):
     """A widget to inspect any Python object."""
 
-    def __init__(  # pylint: disable=too-many-arguments
+    def __init__(  # pylint: disable=too-many-arguments, R0917
         self,
         target: object = None,
         show_private: bool = False,

pytermgui/markup/macros.py

@@ -9,7 +9,7 @@ from .parsing import parse
 
 DEFAULT_MACROS = {}
 
-MarkupLanguage = Any
+MarkupLanguage = Any  # pylint: disable=invalid-name
 
 
 MacroTemplate = TypeVar("MacroTemplate")

pytermgui/markup/parsing.py

@@ -211,6 +211,11 @@ def tokenize_ansi(  # pylint: disable=too-many-locals, too-many-branches, too-ma
         if cursor < start:
             yield PlainToken(text[cursor:start])
 
+        if matchobj.groups()[4] is not None:
+            cursor = end
+            yield ClearToken("/~")
+            continue
+
         if link_osc != (None, None):
             cursor = end
             uri, label = link_osc
@@ -225,6 +230,9 @@ def tokenize_ansi(  # pylint: disable=too-many-locals, too-many-branches, too-ma
 
         cursor = end
 
+        if full.endswith(("J", "K")):
+            continue
+
         code = ""
 
         # Position
@@ -233,9 +241,7 @@ def tokenize_ansi(  # pylint: disable=too-many-locals, too-many-branches, too-ma
         if posmatch is not None:
             ypos, xpos = posmatch.groups()
             if not ypos and not xpos:
-                raise ValueError(
-                    f"Cannot parse cursor when no position is supplied. Match: {posmatch!r}"
-                )
+                ypos = xpos = "1"
 
             yield CursorToken(content, int(ypos) or None, int(xpos) or None)
             continue
@@ -481,7 +487,7 @@ def optimize_tokens(tokens: list[Token]) -> Iterator[Token]:
             applied.append(tkn)
             yield tkn
 
-    def _remove_redundant_color(token: Token) -> None:
+    def _remove_redundant_color(token: Token, new: Color) -> None:
         """Removes non-functional colors.
 
         These happen in the following ways:
@@ -513,7 +519,7 @@ def optimize_tokens(tokens: list[Token]) -> Iterator[Token]:
         if Token.is_color(token):
             new = token.color
 
-            _remove_redundant_color(token)
+            _remove_redundant_color(token, new)
 
             if not any(token.markup == applied.markup for applied in current_tag_group):
                 current_tag_group.append(token)

pytermgui/palettes.py

@@ -241,23 +241,18 @@ class Palette:
             for shadenumber in range(-SHADE_COUNT, SHADE_COUNT + 1):
                 if shadenumber > 0:
                     shadeindex = f"+{shadenumber}"
-                    blend_color = white
-                    blend_multiplier = 1
+                    blended = color.blend(
+                        white, SHADE_INCREMENT * shadenumber
+                    )
 
                 elif shadenumber == 0:
                     shadeindex = ""
-
-                else:
-                    shadeindex = str(shadenumber)
-                    blend_color = black
-                    blend_multiplier = -1
-
-                if shadenumber == 0:
                     blended = color
 
                 else:
+                    shadeindex = str(shadenumber)
                     blended = color.blend(
-                        blend_color, blend_multiplier * SHADE_INCREMENT * shadenumber
+                        black, -SHADE_INCREMENT * shadenumber
                     )
 
                 data[f"{name}{shadeindex}"] = blended

pytermgui/regex.py

@@ -7,8 +7,12 @@ from typing import Match
 from wcwidth import wcswidth
 
 RE_LINK = re.compile(r"(?:\x1b\]8;;([^\\]*)\x1b\\([^\\]*?)\x1b\]8;;\x1b\\)")
-RE_ANSI_NEW = re.compile(rf"(\x1b\[(.*?)[mH])|{RE_LINK.pattern}|(\x1b_G(.*?)\x1b\\)")
-RE_ANSI = re.compile(r"(?:\x1b\[(.*?)[mH])|(?:\x1b\](.*?)\x1b\\)|(?:\x1b_G(.*?)\x1b\\)")
+RE_ANSI_NEW = re.compile(
+    rf"(\x1b\[(.*?)[mHJK])|{RE_LINK.pattern}|(\x1b\]8;;\x1b\\)|(\x1b_G(.*?)\x1b\\)"
+)
+RE_ANSI = re.compile(
+    r"(?:\x1b\[(.*?)[mHJK])|(?:\x1b\](.*?)\x1b\\)|(?:\x1b_G(.*?)\x1b\\)"
+)
 RE_MACRO = re.compile(r"(![a-z0-9_\-]+)(?:\(([\w\/\.?\-=:]+)\))?")
 RE_MARKUP = re.compile(r"((\\*)\[([^\[\]]*)\])")
 RE_POSITION = re.compile(r"\x1b\[(\d*?)(?:;(\d*))?H")

pytermgui/term.py

@@ -8,6 +8,7 @@ import errno
 import os
 import signal
 import sys
+import threading
 import time
 from contextlib import contextmanager
 from datetime import datetime
@@ -126,7 +127,7 @@ class Recorder:
         with open(filename, "w", encoding="utf-8") as file:
             file.write(self.export_html(prefix=prefix, inline_styles=inline_styles))
 
-    def save_svg(  # pylint: disable=too-many-arguments
+    def save_svg(  # pylint: disable=too-many-arguments, R0917
         self,
         filename: str | None = None,
         prefix: str | None = None,
@@ -263,6 +264,9 @@ class Terminal:  # pylint: disable=too-many-instance-attributes
 
         self._listeners: dict[int, list[Callable[..., Any]]] = {}
 
+        # Async-signal-safe resize mechanism
+        self._resize_pending = threading.Event()
+
         if hasattr(signal, "SIGWINCH"):
             signal.signal(signal.SIGWINCH, self._update_size)
         else:
@@ -278,16 +282,16 @@ class Terminal:  # pylint: disable=too-many-instance-attributes
             ["" for _ in range(self.width)] for y in range(self.height)
         ]
 
-    def _window_terminal_resize(self):
+    def _window_terminal_resize(self) -> None:
         from time import sleep  # pylint: disable=import-outside-toplevel
 
         _previous = get_terminal_size()
         while True:
             _next = get_terminal_size()
             if _previous != _next:
-                self._update_size()
+                self._resize_pending.set()
                 _previous = _next
-            sleep(0.001)
+            sleep(0.01)
 
     def __fancy_repr__(self) -> Generator[FancyYield, None, None]:
         """Returns a cool looking repr."""
@@ -348,17 +352,34 @@ class Terminal:  # pylint: disable=too-many-instance-attributes
         return (size[0], size[1])
 
     def _update_size(self, *_: Any) -> None:
-        """Resize terminal when SIGWINCH occurs, and call listeners."""
+        """Signal handler for SIGWINCH - ONLY sets flag (async-signal-safe)."""
 
-        if hasattr(self, "resolution"):
-            del self.resolution
+        self._resize_pending.set()
 
-        self.size = self._get_size()
+    def process_pending_resize(self) -> bool:
+        """Process pending resize event if one is queued.
+
+        Call this periodically from the main event loop.
+
+        :returns: True if a resize was processed.
+        """
+        if not self._resize_pending.is_set():
+            return False
+
+        self._resize_pending.clear()
+
+        # Check __dict__ directly to avoid triggering the cached_property getter,
+        # which uses signals and can only run in the main thread
+        if "resolution" in self.__dict__:
+            del self.__dict__["resolution"]
 
+        self.size = self._get_size()
         self._call_listener(self.RESIZE, self.size)
 
         # Wipe the screen in case anything got messed up
-        self.write("\x1b[2J")
+        self.write("\x1b[H\x1b[2J")
+
+        return True
 
     @property
     def width(self) -> int:
@@ -454,15 +475,21 @@ class Terminal:  # pylint: disable=too-many-instance-attributes
         buffer = StringIO()
 
         try:
-            with self.no_record():
-                self.write("\x1b[?2026h")
+            # Write directly to stream to avoid write()'s auto-clear behavior
+            self._stream.write("\x1b[?2026h")
             yield buffer
 
         finally:
-            self.write(buffer.getvalue())
-            with self.no_record():
-                self.write("\x1b[?2026l")
-            self.flush()
+            content = buffer.getvalue()
+            self._stream.write(content)
+
+            # Frame contents bypass write() so they are sent atomically to the output
+            # stream. Forward the visual content to an active recorder explicitly.
+            if self._recorder is not None:
+                self._recorder.write(content)
+
+            self._stream.write("\x1b[?2026l")
+            self._stream.flush()
 
     @staticmethod
     def isatty() -> bool:
@@ -532,6 +559,7 @@ class Terminal:  # pylint: disable=too-many-instance-attributes
 
             return sliced
 
+        # Truncate pending buffer on clear (may help on Windows)
         if "\x1b[2J" in data:
             self.clear_stream()
 
@@ -546,8 +574,7 @@ class Terminal:  # pylint: disable=too-many-instance-attributes
 
                 maximum = self.width - xpos
 
-                if xpos < self.origin[0]:
-                    xpos = self.origin[0]
+                xpos = max(xpos, self.origin[0])
 
                 sliced = _slice(data, maximum) if len(data) > maximum else data
 
@@ -565,7 +592,11 @@ class Terminal:  # pylint: disable=too-many-instance-attributes
             self._stream.flush()
 
     def clear_stream(self) -> None:
-        """Clears (truncates) the terminal's stream."""
+        """Clears the terminal screen.
+
+        Attempts to truncate any buffered stream data (may work on Windows),
+        then moves cursor to home position and clears the entire screen.
+        """
 
         try:
             self._stream.truncate(0)
@@ -574,7 +605,7 @@ class Terminal:  # pylint: disable=too-many-instance-attributes
             if error.errno != errno.EINVAL and os.name != "nt":
                 raise
 
-        self._stream.write("\x1b[2J")
+        self._stream.write("\x1b[H\x1b[2J")
 
     def print(
         self,