Merge release v1.9.7 into main

Merge version 1.9.7 of 'xulbux' into the main branch.

For more info on this update, see the change log:
https://github.com/xulbux/python-lib-xulbux/blob/main/CHANGELOG.md#v1-9-7

Author: xulbux

.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,28 @@
 # <br><b>Changelog</b><br>
 
 
+<span id="v1-9-7" />
+
+## 26.04.2026 `v1.9.7`
+
+* Restructured CLI commands under a single `xulbux-lib` entry point:
+  - `xulbux-lib` shows library info.
+  - `xulbux-lib fc` (*new*) parses and renders a 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.
+* Fixed a small bug in `ProgressBar`, where it would only overwrite and not actually clear the previous line.
+* Added a new constant `ANSI.COLOR_VARIANTS_MAP`, which contains all possible color variants that can be used in formatting.
+* Made it possible to also pass console default colors to `title_bg_color` in `Console.log()`, instead of only custom RGBA or HEXA colors.
+* Added a new format key `link:…` to `FormatCodes`, which allows you to create hyperlinks in the console output with the syntax `[link:URL](display text)`.
+
+**BREAKING CHANGES:**
+* The `ANSI.COLOR_MAP` constant is now a set for better lookup performance, as the color order doesn't matter there.
+* All `Console` methods that allow console default colors as input for their color params, now actually validate the given color, raising an error if it's not valid.
+* The default for `box_bg_color` in `Console.log_box_filled()` is now the console foreground color (`None`) instead of `br:green`.
+
+
 <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-lib`      | Show some information about the library.                         |
+| `xulbux-lib 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",
@@ -116,7 +110,7 @@ keywords = [
 "License" = "https://github.com/xulbux/python-lib-xulbux/blob/main/LICENSE"
 
 [project.scripts]
-xulbux-help = "xulbux.cli.help:show_help"
+xulbux-lib = "xulbux.cli:main"
 
 [tool.flake8]
 max-complexity = 12
@@ -158,3 +152,4 @@ testpaths = [
 [tool.pyright]
 include = ["src", "tests"]
 typeCheckingMode = "strict"
+reportPrivateUsage = "none"

setup.py

@@ -6,9 +6,15 @@
 import os
 
 
+PROJECT_ROOT = Path(__file__).parent
+PROJECT_SRC = PROJECT_ROOT / "src" / "xulbux"
+
+
 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
 
@@ -18,17 +24,16 @@ def generate_stubs_for_package():
 
     try:
         skip_stubgen = {
-            Path("src/xulbux/base/types.py"),  # COMPLEX TYPE DEFINITIONS
-            Path("src/xulbux/__init__.py"),  # PRESERVE PACKAGE METADATA CONSTANTS
+            PROJECT_SRC / "base" / "types.py",  # COMPLEX TYPE DEFINITIONS
+            PROJECT_SRC / "__init__.py",  # PRESERVE PACKAGE METADATA CONSTANTS
         }
 
-        src_dir = Path("src/xulbux")
         generated_count = 0
         skipped_count = 0
 
-        for py_file in src_dir.rglob("*.py"):
+        for py_file in PROJECT_SRC.rglob("*.py"):
             pyi_file = py_file.with_suffix(".pyi")
-            rel_path = py_file.relative_to(src_dir.parent)
+            rel_path = py_file.relative_to(PROJECT_SRC.parent)
 
             if py_file in skip_stubgen:
                 pyi_file.write_text(py_file.read_text(encoding="utf-8"), encoding="utf-8")
@@ -41,13 +46,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:
@@ -65,6 +66,11 @@ def generate_stubs_for_package():
         print(f"[WARNING] Could not generate stubs:\n  {fmt_error}\n")
 
 
+def delete_project_stub_files():
+    deleted = [f for f in PROJECT_SRC.rglob("*.pyi") if f.unlink() or True]
+    print(f"\nCleaned up {len(deleted)} stub file(s) from project directory.\n")
+
+
 ext_modules = []
 
 # OPTIONALLY USE MYPYC COMPILATION
@@ -90,3 +96,5 @@ def generate_stubs_for_package():
     name="xulbux",
     ext_modules=ext_modules,
 )
+
+delete_project_stub_files()

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/__init__.py

@@ -97,8 +97,12 @@ def seq(cls, placeholders: int = 1, /) -> FormattableString:
     SEQ_BG_COLOR: Final[FormattableString] = CHAR + START + "48" + SEP + "2" + SEP + "{}" + SEP + "{}" + SEP + "{}" + END
     """ANSI escape sequence with three placeholders for setting the RGB background color."""
 
-    COLOR_MAP: Final[tuple[str, ...]] = (
-        ########### DEFAULT CONSOLE COLOR NAMES ############
+    SEQ_LINK_OPEN: Final[FormattableString] = CHAR + "]8;;{}" + CHAR + "\\"
+    """OSC 8 hyperlink opening sequence with a placeholder for the URL."""
+    SEQ_LINK_CLOSE: Final[str] = CHAR + "]8;;" + CHAR + "\\"
+    """OSC 8 hyperlink closing sequence."""
+
+    COLOR_MAP: Final[set[str]] = {
         "black",
         "red",
         "green",
@@ -107,9 +111,29 @@ def seq(cls, placeholders: int = 1, /) -> FormattableString:
         "magenta",
         "cyan",
         "white",
-    )
+    }
     """The standard terminal color names."""
 
+    COLOR_VARIANTS_MAP: Final[set[str]] = COLOR_MAP | {
+        "br:black",
+        "br:red",
+        "br:green",
+        "br:yellow",
+        "br:blue",
+        "br:magenta",
+        "br:cyan",
+        "br:white",
+        "bright:black",
+        "bright:red",
+        "bright:green",
+        "bright:yellow",
+        "bright:blue",
+        "bright:magenta",
+        "bright:cyan",
+        "bright:white",
+    }
+    """All color variants that can be used in formatting."""
+
     CODES_MAP: Final[dict[str | tuple[str, ...], int]] = {
         ################# SPECIFIC RESETS ##################
         "_": 0,

src/xulbux/base/consts.py

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