Merge release v1.9.7 into main

.github/workflows/build-and-publish.yml

@@ -1,7 +1,7 @@
 # THIS WORKFLOW WILL BUILD WHEELS FOR ALL MAJOR PLATFORMS AND UPLOAD THEM TO PYPI
 
 # TO BUILD AND INSTALL LOCALLY FOR TESTING, RUN THE FOLLOWING COMMAND:
-# pip install "/path/to/python-lib-xulbux" --no-deps --no-cache-dir --force-reinstall --no-build-isolation
+# py -m pip install "/path/to/python-lib-xulbux" --no-deps --no-cache-dir --force-reinstall -vv
 
 # TO CREATE A NEW RELEASE, TAG A COMMIT WITH THE FOLLOWING FORMAT:
 # git tag v1.X.Y
@@ -36,8 +36,7 @@ jobs:
         env:
           CIBW_BUILD: cp310-* cp311-* cp312-* cp313-* cp314-*
           CIBW_SKIP: "*-musllinux_*"
-          CIBW_BEFORE_BUILD: pip install setuptools>=80.0.0 wheel>=0.45.0 mypy>=1.19.0 mypy-extensions>=1.1.0 types-regex types-keyboard prompt_toolkit>=3.0.41
-          CIBW_BUILD_FRONTEND: "pip; args: --no-build-isolation"
+          CIBW_BUILD_FRONTEND: pip
           CIBW_ENVIRONMENT: XULBUX_USE_MYPYC=1
 
       - name: Verify wheels were built

.github/workflows/test-and-lint.yml

@@ -39,7 +39,7 @@ jobs:
       - name: Install project and dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e .[dev]
+          pip install .[dev]
           pip install flake8 flake8-pyproject pyright pytest
 
       - name: Lint with flake8

CHANGELOG.md

@@ -15,6 +15,17 @@
 # <br><b>Changelog</b><br>
 
 
+<span id="v1-9-7" />
+
+## ... `v1.9.7`
+
+* Created a new CLI command `xulbux-fc`, which allows you to parse and render a given string's format codes as ANSI console output.
+* Added `.get()` method to `ParsedArgData` for safe index access on parsed argument values.
+* Added missing `__init__.py` files to the `base` and `cli` subpackages.
+* Fixed `ModuleNotFoundError` caused by `mypyc` compiling `__init__.py` files, which broke subpackage imports.
+* Simplified CI workflows to use `pip`'s build isolation instead of manually specifying build dependencies.
+
+
 <span id="v1-9-6" />
 
 ## 13.04.2026 `v1.9.6`

README.md

@@ -34,9 +34,11 @@ pip install --upgrade xulbux
 ## CLI Commands
 
 When the library is installed, the following commands are available in the console:
-| Command       | Description                              |
-| :------------ | :--------------------------------------- |
-| `xulbux-help` | shows some information about the library |
+
+| Command       | Description                                                      |
+| :------------ | :--------------------------------------------------------------- |
+| `xulbux-help` | Show some information about the library.                         |
+| `xulbux-fc`   | Parse and render a string's format codes as ANSI console output. |
 
 <br>
 

pyproject.toml

@@ -1,32 +1,26 @@
 [build-system]
-# SAME BUILD-DEPS ALSO NEED TO BE SPECIFIED IN CIBW_BEFORE_BUILD IN .github/workflows/build-and-publish.yml
 requires = [
   "setuptools>=80.0.0",
   "wheel>=0.45.0",
   "mypy>=1.19.0",
   "mypy-extensions>=1.1.0",
   # TYPES FOR MyPy
   "types-regex",
-  "types-keyboard",
   "prompt_toolkit>=3.0.41",
 ]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "xulbux"
-version = "1.9.6"
+version = "1.9.7"
 description = "A Python library to simplify common programming tasks."
 readme = "README.md"
 authors = [{ name = "XulbuX", email = "xulbux.real@gmail.com" }]
 maintainers = [{ name = "XulbuX", email = "xulbux.real@gmail.com" }]
 license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.10.0"
-dependencies = [
-  "keyboard>=0.13.5",
-  "prompt_toolkit>=3.0.41",
-  "regex>=2023.10.3",
-]
+dependencies = ["prompt_toolkit>=3.0.41", "regex>=2023.10.3"]
 optional-dependencies = { dev = [
   "flake8-pyproject>=1.2.3",
   "flake8>=6.1.0",
@@ -117,6 +111,7 @@ keywords = [
 
 [project.scripts]
 xulbux-help = "xulbux.cli.help:show_help"
+xulbux-fc = "xulbux.cli.tools:render_format_codes"
 
 [tool.flake8]
 max-complexity = 12

setup.py

@@ -9,6 +9,8 @@
 def find_python_files(directory: str) -> list[str]:
     python_files: list[str] = []
     for file in Path(directory).rglob("*.py"):
+        if file.name == "__init__.py":
+            continue
         python_files.append(str(file))
     return python_files
 
@@ -41,13 +43,9 @@ def generate_stubs_for_package():
                 or str(Path(sys.executable).parent / ("stubgen.exe" if sys.platform == "win32" else "stubgen"))
             )
             result = subprocess.run(
-                [stubgen_exe,
-                 str(py_file),
-                 "-o", "src",
-                 "--include-private",
-                 "--export-less"],
+                [stubgen_exe, str(py_file), "-o", "src", "--include-private", "--export-less"],
                 capture_output=True,
-                text=True
+                text=True,
             )
 
             if result.returncode == 0:

src/xulbux/__init__.py

@@ -1,5 +1,5 @@
 __package_name__ = "xulbux"
-__version__ = "1.9.6"
+__version__ = "1.9.7"
 __description__ = "A Python library to simplify common programming tasks."
 __status__ = "Production/Stable"
 
@@ -12,7 +12,6 @@
 
 __requires_python__ = ">=3.10.0"
 __dependencies__ = [
-    "keyboard>=0.13.5",
     "prompt_toolkit>=3.0.41",
     "regex>=2023.10.3",
 ]

src/xulbux/base/exceptions.py

@@ -4,6 +4,8 @@
 
 from .decorators import mypyc_attr
 
+# yapf: disable
+
 
 ################################################## FILE ##################################################
 

src/xulbux/base/types.py

@@ -5,6 +5,8 @@
 from typing import Annotated, TypeAlias, TypedDict, Optional, Protocol, Literal, Union, Any
 from pathlib import Path
 
+# yapf: disable
+
 
 ################################################## Annotated ##################################################
 

src/xulbux/cli/tools.py

@@ -0,0 +1,22 @@
+from ..format_codes import FormatCodes
+from ..console import Console
+
+
+def render_format_codes():
+    args = Console.get_args({"input": "before"})
+
+    if not args.input.values:
+        FormatCodes.print("\n[_|i|dim]Provide a string to parse and render\n"
+                          "its format codes as ANSI console output.[_]\n")
+
+    else:
+        ansi = FormatCodes.to_ansi("".join(args.input.values))
+        ansi_escaped = FormatCodes.escape_ansi(ansi)
+        ansi_stripped = FormatCodes.remove_ansi(ansi)
+
+        print(f"\n{ansi}\n")
+
+        if len(ansi) != len(ansi_stripped):
+            FormatCodes.print(f"[_|i|dim]{ansi_escaped}[_]\n")
+        else:
+            FormatCodes.print("[_|i|dim](The provided string doesn't contain any valid format codes.)\n")

src/xulbux/console.py

@@ -23,7 +23,6 @@
 import prompt_toolkit as _pt
 import subprocess as _subprocess
 import threading as _threading
-import keyboard as _keyboard
 import getpass as _getpass
 import ctypes as _ctypes
 import shutil as _shutil
@@ -98,6 +97,17 @@ def dict(self) -> ArgData:
         """Returns the argument result as a dictionary."""
         return ArgData(exists=self.exists, is_pos=self.is_pos, values=self.values, flag=self.flag)
 
+    def get(self, index: int, /, default: Optional[str] = None) -> Optional[str]:
+        """Safely access a value from the `values` list by index.\n
+        -------------------------------------------------------------------
+        - `index` -⠀the index of the value to access
+        - `default` -⠀the fallback value if the index is out of range\n
+        -------------------------------------------------------------------
+        Returns the value at `index` if it exists, otherwise `default`."""
+        if 0 <= index < len(self.values):
+            return self.values[index]
+        return default
+
 
 @mypyc_attr(native_class=False)
 class ParsedArgs:
@@ -347,7 +357,7 @@ def pause_exit(
         if reset_ansi:
             FormatCodes.print("[_]", end="")
         if pause:
-            _keyboard.read_key(suppress=True)
+            cls._read_single_key()
         if exit:
             _sys.exit(exit_code)
 
@@ -971,6 +981,27 @@ def input(
                     return default_val
                 raise
 
+    @staticmethod
+    def _read_single_key() -> None:
+        """Wait for a single key press without requiring elevated privileges.<br>
+        Falls back to reading a line when stdin is not a TTY (e.g. piped input)."""
+        if not _sys.stdin.isatty():
+            _sys.stdin.readline()
+            return
+        if _sys.platform == "win32":
+            import msvcrt as _msvcrt
+            _msvcrt.getch()
+        else:
+            import tty as _tty  # type: ignore[import-not-found]
+            import termios as _termios  # type: ignore[import-not-found]
+            fd = _sys.stdin.fileno()
+            old_settings = _termios.tcgetattr(fd)  # type: ignore[attr-defined]
+            try:
+                _tty.setraw(fd)  # type: ignore[attr-defined]
+                _sys.stdin.read(1)
+            finally:
+                _termios.tcsetattr(fd, _termios.TCSADRAIN, old_settings)  # type: ignore[attr-defined]
+
     @classmethod
     def _add_back_removed_parts(cls, split_string: list[str], removals: tuple[tuple[int, str], ...], /) -> list[str]:
         """Adds back the removed parts into the split string parts at their original positions."""

src/xulbux/data.py

@@ -232,12 +232,15 @@ def remove_comments(
         if len(comment_start) == 0:
             raise ValueError("The 'comment_start' parameter string must not be empty.")
 
-        return cast(DataObj, _DataRemoveCommentsHelper(
-            data,
-            comment_start=comment_start,
-            comment_end=comment_end,
-            comment_sep=comment_sep,
-        )())
+        return cast(
+            DataObj,
+            _DataRemoveCommentsHelper(
+                data,
+                comment_start=comment_start,
+                comment_end=comment_end,
+                comment_sep=comment_sep,
+            )()
+        )
 
     @classmethod
     def is_equal(