Merge release v1.9.8 into main

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

@@ -44,8 +44,8 @@ jobs:
 
       - name: Lint with flake8
         run: |
-          python -m flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-          python -m flake8 . --exit-zero --max-complexity=12 --statistics
+          python -m flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics --exclude=build
+          python -m flake8 . --exit-zero --max-complexity=12 --statistics --exclude=build
 
       - name: Type check with pyright
         run: |

.style.yapf

@@ -1,19 +1,19 @@
 [style]
+ALLOW_SPLIT_BEFORE_DICT_VALUE = true
 BASED_ON_STYLE = pep8
+BLANK_LINE_BEFORE_NESTED_CLASS_OR_DEF = 1
+BLANK_LINES_BETWEEN_TOP_LEVEL_IMPORTS_AND_VARIABLES = 2
+COALESCE_BRACKETS = true
 COLUMN_LIMIT = 127
-ALLOW_SPLIT_BEFORE_DICT_VALUE = true
-SPLIT_BEFORE_FIRST_ARGUMENT = true
-SPLIT_BEFORE_LOGICAL_OPERATOR = true
-SPLIT_BEFORE_BITWISE_OPERATOR = true
-SPLIT_BEFORE_ARITHMETIC_OPERATOR = true
-SPLIT_BEFORE_DOT = true
-SPLIT_COMPLEX_COMPREHENSION = false
 DEDENT_CLOSING_BRACKETS = true
-INDENT_CLOSING_BRACKETS = false
-COALESCE_BRACKETS = true
-EACH_DICT_ENTRY_ON_SEPARATE_LINE = false
-BLANK_LINES_BETWEEN_TOP_LEVEL_IMPORTS_AND_VARIABLES = 2
 DISABLE_SPLIT_LIST_WITH_COMMENT = true
+EACH_DICT_ENTRY_ON_SEPARATE_LINE = false
+INDENT_CLOSING_BRACKETS = false
 SPACES_AROUND_SUBSCRIPT_COLON = false
 SPACES_BEFORE_COMMENT = 2
-BLANK_LINE_BEFORE_NESTED_CLASS_OR_DEF = 1
+SPLIT_BEFORE_ARITHMETIC_OPERATOR = true
+SPLIT_BEFORE_BITWISE_OPERATOR = true
+SPLIT_BEFORE_DOT = true
+SPLIT_BEFORE_FIRST_ARGUMENT = true
+SPLIT_BEFORE_LOGICAL_OPERATOR = true
+SPLIT_COMPLEX_COMPREHENSION = false

README.md

@@ -3,7 +3,7 @@
 [![](https://img.shields.io/pypi/v/xulbux?style=flat&labelColor=404560&color=7075FF)](https://pypi.org/project/xulbux) [![](https://img.shields.io/pepy/dt/xulbux?style=flat&labelColor=404560&color=7075FF)](https://clickpy.clickhouse.com/dashboard/xulbux) [![](https://img.shields.io/github/license/xulbux/python-lib-xulbux?style=flat&labelColor=405555&color=70FFEE)](https://github.com/xulbux/python-lib-xulbux/blob/main/LICENSE) [![](https://img.shields.io/github/last-commit/xulbux/python-lib-xulbux?style=flat&labelColor=554045&color=FF6065)](https://github.com/xulbux/python-lib-xulbux/commits) [![](https://img.shields.io/github/issues/xulbux/python-lib-xulbux?style=flat&labelColor=554045&color=FF6065)](https://github.com/xulbux/python-lib-xulbux/issues) [![](https://img.shields.io/github/stars/xulbux/python-lib-xulbux?label=★&style=flat&labelColor=604A40&color=FF9673)](https://github.com/xulbux/python-lib-xulbux/stargazers)
 
 **`xulbux`** is a library that contains many useful classes, types, and functions,
-ranging from console logging and working with colors to file management and system operations.
+ranging from terminal logging and working with colors to file management and system operations.
 The library is designed to simplify common programming tasks and improve code readability through its collection of tools.
 
 For precise information about the library, see the library's [**documentation**](https://github.com/xulbux/python-lib-xulbux/wiki).<br>
@@ -17,39 +17,42 @@ For the libraries latest changes and updates, see the [**change log**](https://g
 
 ## Installation
 
-Run the following commands in a console with administrator privileges, so the actions take effect for all users.
+Run the following commands in a terminal with administrator privileges, so the actions take effect for all users.
 
 Install the library and all its dependencies with the command:
-```console
+
+```shell
 pip install xulbux
 ```
 
 Upgrade the library and all its dependencies to their latest available version with the command:
-```console
+
+```shell
 pip install --upgrade xulbux
 ```
 
 <br>
 
 ## CLI Commands
 
-When the library is installed, the following commands are available in the console:
+When the library is installed, the following commands are available in the terminal:
 
-| 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. |
+| Command      | Description                              |
+| :----------- | :--------------------------------------- |
+| `xulbux-lib` | Show some information about the library. |
 
 <br>
 
 ## Usage
 
 Import the full library under the alias `xx`, so its modules and main classes are accessible with `xx.module.Class`, `xx.MainClass.method()`:
+
 ```python
 import xulbux as xx
 ```
 
 So you don't have to import the full library under an alias, you can also import only certain parts of the library's contents:
+
 ```python
 # LIBRARY SUB MODULES
 from xulbux.base.consts import COLOR, CHARS, ANSI
@@ -104,12 +107,12 @@ from xulbux.color import rgba, hsla, hexa
     </tr>
     <tr>
       <td><a href="https://github.com/xulbux/python-lib-xulbux/wiki/color"><img src="https://img.shields.io/badge/color-B272FC?style=for-the-badge" alt="color"></a></td>
-      <td><code>rgba</code> <code>hsla</code> <code>hexa</code> <code>Color</code> classes, which include methods to work with<br>
+      <td><code>rgba</code> <code>hsla</code> <code>hexa</code> <code>Color</code> classes, which include methods to work with<br>
         colors in various formats.</td>
     </tr>
     <tr>
       <td><a href="https://github.com/xulbux/python-lib-xulbux/wiki/console"><img src="https://img.shields.io/badge/console-B272FC?style=for-the-badge" alt="console"></a></td>
-      <td><code>Console</code> <code>ProgressBar</code> classes, which include methods for logging<br>
+      <td><code>Console</code> <code>ProgressBar</code> classes, which include methods for logging<br>
         and other actions within the console.</td>
     </tr>
     <tr>
@@ -130,8 +133,9 @@ from xulbux.color import rgba, hsla, hexa
     </tr>
     <tr>
       <td><a href="https://github.com/xulbux/python-lib-xulbux/wiki/format_codes"><img src="https://img.shields.io/badge/format__codes-B272FC?style=for-the-badge" alt="format_codes"></a></td>
-      <td><code>FormatCodes</code> class, which includes methods to print and work with strings that contain<br>
-        special formatting codes, which are then converted to ANSI codes for pretty console output.</td>
+      <td><code>Format</code> (<i>alias</i> <code>F</code>) <code>FormatCodes</code> (<i>alias</i> <code>FC</code>) <code>Term</code> classes for building richly formatted<br>
+        terminal output via a typed, operator-based syntax and for emitting common cursor- and<br>
+        screen-control sequences.</td>
     </tr>
     <tr>
       <td><a href="https://github.com/xulbux/python-lib-xulbux/wiki/json"><img src="https://img.shields.io/badge/json-B272FC?style=for-the-badge" alt="json"></a></td>
@@ -159,6 +163,7 @@ from xulbux.color import rgba, hsla, hexa
 ## Example Usage
 
 This is what it could look like using this library for a simple but ultra good-looking color converter:
+
 ```python
 from xulbux.base.consts import COLOR, CHARS
 from xulbux.color import hexa

pyproject.toml

@@ -5,14 +5,16 @@ requires = [
   "mypy>=1.19.0",
   "mypy-extensions>=1.1.0",
   # TYPES FOR MyPy
+  "types-setuptools",
   "types-regex",
+  "types-toml",
   "prompt_toolkit>=3.0.41",
 ]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "xulbux"
-version = "1.9.7"
+version = "1.9.8"
 description = "A Python library to simplify common programming tasks."
 readme = "README.md"
 authors = [{ name = "XulbuX", email = "xulbux.real@gmail.com" }]
@@ -117,7 +119,11 @@ max-complexity = 12
 max-line-length = 127
 select = ["E", "F", "W", "C90"]
 extend-ignore = ["E124", "E203", "E266", "E502", "W503"]
-per-file-ignores = ["__init__.py:F403,F405", "types.py:E302,E305"]
+per-file-ignores = [
+  "__init__.py:F403,F405",
+  "src/xulbux/base/types.py:E302,E305",
+  "src/xulbux/cli/help.py:E501",
+]
 
 [tool.setuptools]
 package-dir = { "" = "src" }
@@ -132,22 +138,7 @@ xulbux = ["py.typed", "*.pyi", "**/*.pyi"]
 minversion = "7.0"
 addopts = "-ra -q"
 pythonpath = ["src"]
-testpaths = [
-  "tests/test_code.py",
-  "tests/test_color_types.py",
-  "tests/test_color.py",
-  "tests/test_console.py",
-  "tests/test_data.py",
-  "tests/test_env_path.py",
-  "tests/test_file_sys.py",
-  "tests/test_file.py",
-  "tests/test_format_codes.py",
-  "tests/test_json.py",
-  "tests/test_metadata_consistency.py",
-  "tests/test_regex.py",
-  "tests/test_string.py",
-  "tests/test_system.py",
-]
+testpaths = ["tests/test_*.py"]
 
 [tool.pyright]
 include = ["src", "tests"]

setup.py

@@ -61,8 +61,8 @@ def generate_stubs_for_package():
 
         print(f"\nStub generation complete. ({generated_count} generated, {skipped_count} copied)\n")
 
-    except Exception as e:
-        fmt_error = "\n  ".join(str(e).splitlines())
+    except Exception as exc:
+        fmt_error = "\n  ".join(str(exc).splitlines())
         print(f"[WARNING] Could not generate stubs:\n  {fmt_error}\n")
 
 
@@ -73,8 +73,13 @@ def delete_project_stub_files():
 
 ext_modules = []
 
+# ONLY COMPILE AND GENERATE STUBS WHEN ACTUALLY BUILDING, NOT DURING METADATA-ONLY
+# PHASES (egg_info, dist_info) THAT PIP INVOKES AS PART OF PEP 517 PREPARATION.
+_BUILD_COMMANDS = {"bdist_wheel", "build_ext", "build", "develop", "editable_wheel", "install"}
+_is_building = bool(set(sys.argv[1:]) & _BUILD_COMMANDS)
+
 # OPTIONALLY USE MYPYC COMPILATION
-if os.environ.get("XULBUX_USE_MYPYC", "1") == "1":
+if os.environ.get("XULBUX_USE_MYPYC", "1") == "1" and _is_building:
     try:
         from mypyc.build import mypycify
 
@@ -97,4 +102,5 @@ def delete_project_stub_files():
     ext_modules=ext_modules,
 )
 
-delete_project_stub_files()
+if _is_building:
+    delete_project_stub_files()

src/xulbux/__init__.py

@@ -1,5 +1,5 @@
 __package_name__ = "xulbux"
-__version__ = "1.9.7"
+__version__ = "1.9.8"
 __description__ = "A Python library to simplify common programming tasks."
 __status__ = "Production/Stable"
 
@@ -25,6 +25,7 @@
     "File",
     "FileSys",
     "FormatCodes",
+    "deprFormatCodes",
     "Json",
     "Regex",
     "String",
@@ -39,6 +40,7 @@
 from .file import File
 from .file_sys import FileSys
 from .format_codes import FormatCodes
+from .depr_format_codes import deprFormatCodes
 from .json import Json
 from .regex import Regex
 from .string import String

src/xulbux/base/consts.py

@@ -80,26 +80,32 @@ class ANSI:
     """Printable ANSI escape character."""
     CHAR: Final = "\x1b"
     """ANSI escape character."""
+
     START: Final = "["
-    """Start of an ANSI escape sequence."""
+    """**DEPRECATED** – only used by `depr_format_codes`. Will be removed together with that module.\n
+    Start of an ANSI escape sequence."""
     SEP: Final = ";"
-    """Separator between ANSI escape sequence parts."""
+    """**DEPRECATED** – only used by `depr_format_codes`. Will be removed together with that module.\n
+    Separator between ANSI escape sequence parts."""
     END: Final = "m"
-    """End of an ANSI escape sequence."""
+    """**DEPRECATED** – only used by `depr_format_codes`. Will be removed together with that module.\n
+    End of an ANSI escape sequence."""
 
     @classmethod
     def seq(cls, placeholders: int = 1, /) -> FormattableString:
-        """Generates an ANSI escape sequence with the specified number of placeholders."""
+        """**DEPRECATED** – only used by `depr_format_codes`. Will be removed together with that module.\n
+        Generates an ANSI escape sequence with the specified number of placeholders."""
+
         return cls.CHAR + cls.START + cls.SEP.join(["{}" for _ in range(placeholders)]) + cls.END
 
-    SEQ_COLOR: Final[FormattableString] = CHAR + START + "38" + SEP + "2" + SEP + "{}" + SEP + "{}" + SEP + "{}" + END
-    """ANSI escape sequence with three placeholders for setting the RGB text color."""
-    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."""
+    SEQ_FG_COLOR: Final[FormattableString] = f"{CHAR}[38;2;{{}};{{}};{{}}m"
+    """RGB foreground color sequence with placeholders for red, green, and blue values."""
+    SEQ_BG_COLOR: Final[FormattableString] = f"{CHAR}[48;2;{{}};{{}};{{}}m"
+    """RGB background color sequence with placeholders for red, green, and blue values."""
 
-    SEQ_LINK_OPEN: Final[FormattableString] = CHAR + "]8;;{}" + CHAR + "\\"
+    SEQ_LINK_OPEN: Final[FormattableString] = f"{CHAR}]8;;{{}}{CHAR}\\"
     """OSC 8 hyperlink opening sequence with a placeholder for the URL."""
-    SEQ_LINK_CLOSE: Final[str] = CHAR + "]8;;" + CHAR + "\\"
+    SEQ_LINK_CLOSE: Final[str] = f"{CHAR}]8;;{CHAR}\\"
     """OSC 8 hyperlink closing sequence."""
 
     COLOR_MAP: Final[set[str]] = {
@@ -112,7 +118,8 @@ def seq(cls, placeholders: int = 1, /) -> FormattableString:
         "cyan",
         "white",
     }
-    """The standard terminal color names."""
+    """**DEPRECATED** – only used by `depr_format_codes`. Will be removed together with that module.\n
+    The standard terminal color names."""
 
     COLOR_VARIANTS_MAP: Final[set[str]] = COLOR_MAP | {
         "br:black",
@@ -123,16 +130,9 @@ def seq(cls, placeholders: int = 1, /) -> FormattableString:
         "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."""
+    """**DEPRECATED** – only used by `depr_format_codes`. Will be removed together with that module.\n
+    All color variants that can be used in formatting."""
 
     CODES_MAP: Final[dict[str | tuple[str, ...], int]] = {
         ################# SPECIFIC RESETS ##################
@@ -193,4 +193,5 @@ def seq(cls, placeholders: int = 1, /) -> FormattableString:
         "bg:br:cyan": 106,
         "bg:br:white": 107,
     }
-    """Dictionary mapping format keys to their corresponding ANSI code numbers."""
+    """**DEPRECATED** – only used by `depr_format_codes`. Will be removed together with that module.\n
+    Dictionary mapping format keys to their corresponding ANSI code numbers."""

src/xulbux/base/decorators.py

@@ -18,8 +18,9 @@ def mypyc_attr(**kwargs: Any) -> Callable[[T], T]:
     or acts as a no-op decorator when `mypy_extensions` is not installed.\n
     This allows the use of `mypyc` compilation hints for compiling without making
     `mypy_extensions` a required dependency.\n
-    -----------------------------------------------------------------------------------------
-    - `**kwargs` -⠀keyword arguments to pass to `mypy_extensions.mypyc_attr` if available"""
+    -------------------------------------------------------------------------------------------
+    *   `**kwargs` – keyword arguments to pass to `mypy_extensions.mypyc_attr` if available"""
+
     try:
         from mypy_extensions import mypyc_attr as _mypyc_attr
         return _mypyc_attr(**kwargs)