Merge release v1.9.8 into main

.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

CHANGELOG.md

@@ -15,6 +15,21 @@
 # <br><b>Changelog</b><br>
 
 
+<span id="v1-9-8" />
+
+## … `v1.9.8`
+
+* Unified all error messages throughout the whole library, to always pass the given value if the error is caused by that value being invalid.
+* Added a new param `allow_space_value` to `Console.get_args()` and made `flag_value_sep` optional, which allows you to specify whether flags should be able to receive their values with a space in between (*e.g.* `--flag value` instead of just `--flag=value`).
+* Reformat all docstrings of the whole library.
+
+**BREAKING CHANGES:**
+* Renamed `r`, `g`, `b` and `a` to `red`, `green`, `blue` and `alpha` everywhere in the library, to follow the no-single-letter-names convention.
+* Renamed `h`, `s` and `l` to `hue`, `sat` and `light` everywhere in the library, to follow the no-single-letter-names convention.
+* Renamed the `Console.w` and `Console.h` properties to `Console.width` and `Console.height`, to follow the no-single-letter-names convention.
+* Removed the `background:` and `bright:` prefixes from the library, so now you can just use the `bg:` and `br:` ones, for consistency.
+
+
 <span id="v1-9-7" />
 
 ## 26.04.2026 `v1.9.7`

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,28 +17,28 @@ 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.                          |
+| `xulbux-lib fc`   | Parse and render a string's format codes as ANSI terminal output. |
 
 <br>
 
@@ -131,7 +131,7 @@ from xulbux.color import rgba, hsla, hexa
     <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>
+        special formatting codes, which are then converted to ANSI codes for pretty terminal output.</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>

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" }]

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")
 
 

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"
 

src/xulbux/base/consts.py

@@ -90,6 +90,7 @@ class ANSI:
     @classmethod
     def seq(cls, placeholders: int = 1, /) -> FormattableString:
         """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
@@ -123,14 +124,6 @@ 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."""
 

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)

src/xulbux/base/types.py

@@ -40,24 +40,24 @@
 
 class _RgbaObj(Protocol):
     """Protocol for rgba-like color objects (structurally matches `rgba`)."""
-    r: int
-    g: int
-    b: int
-    a: Optional[float]
+    red: int
+    green: int
+    blue: int
+    alpha: Optional[float]
 
 class _HslaObj(Protocol):
     """Protocol for hsla-like color objects (structurally matches `hsla`)."""
-    h: int
-    s: int
-    l: int
-    a: Optional[float]
+    hue: int
+    sat: int
+    light: int
+    alpha: Optional[float]
 
 class _HexaObj(Protocol):
     """Protocol for hexa-like color objects (structurally matches `hexa`)."""
-    r: int
-    g: int
-    b: int
-    a: Optional[float]
+    red: int
+    green: int
+    blue: int
+    alpha: Optional[float]
 
 Rgba: TypeAlias = Union[
     tuple[Int_0_255, Int_0_255, Int_0_255],
@@ -118,24 +118,24 @@ class ArgData(TypedDict):
 
 class RgbaDict(TypedDict):
     """Dictionary schema for RGBA color components."""
-    r: Int_0_255
-    g: Int_0_255
-    b: Int_0_255
-    a: Optional[Float_0_1]
+    red: Int_0_255
+    green: Int_0_255
+    blue: Int_0_255
+    alpha: Optional[Float_0_1]
 
 class HslaDict(TypedDict):
     """Dictionary schema for HSLA color components."""
-    h: Int_0_360
-    s: Int_0_100
-    l: Int_0_100
-    a: Optional[Float_0_1]
+    hue: Int_0_360
+    sat: Int_0_100
+    light: Int_0_100
+    alpha: Optional[Float_0_1]
 
 class HexaDict(TypedDict):
     """Dictionary schema for HEXA color components."""
-    r: str
-    g: str
-    b: str
-    a: Optional[str]
+    red: str
+    green: str
+    blue: str
+    alpha: Optional[str]
 
 class MissingLibsMsgs(TypedDict):
     """Configuration schema for custom messages in `System.check_libs()` when checking library dependencies."""
@@ -146,7 +146,7 @@ class MissingLibsMsgs(TypedDict):
 ################################################## Protocol ##################################################
 
 class ProgressUpdater(Protocol):
-    """Protocol for a progress updater function used in console progress bars."""
+    """Protocol for a progress updater function used in terminal progress bars."""
 
     def __call__(self, current: Optional[int] = None, label: Optional[str] = None) -> None:
         """Update the current progress value and/or label."""

src/xulbux/cli/__init__.py

@@ -3,6 +3,7 @@
 
 def main() -> None:
     """Main entry point for the `xulbux-lib` CLI command."""
+
     match sys.argv[1] if len(sys.argv) > 1 else "":
         case "fc":
             from .tools import render_format_codes

src/xulbux/cli/help.py

@@ -10,23 +10,27 @@
 
 def get_latest_version() -> Optional[str]:
     """Fetches the latest version of the library from PyPI."""
+
     with _request.urlopen(URL) as response:
         if response.status == 200:
-            data = _json.load(response)
-            return data["info"]["version"]
+            return _json.load(response)["info"]["version"]
         else:
             raise HTTPError(URL, response.status, "Failed to fetch latest version info", response.headers, None)
 
 
 def is_latest_version() -> Optional[bool]:
-    """Checks if the currently installed version of the
+    """Checks if the currently installed version of the<br>
     library is the latest one available on PyPI."""
+
     try:
         if (latest := get_latest_version()) in {"", None}:
             return None
+
         latest_v_parts = tuple(int(part) for part in (latest or "").lower().lstrip("v").split("."))
         installed_v_parts = tuple(int(part) for part in __version__.lower().lstrip("v").split("."))
+
         return latest_v_parts <= installed_v_parts
+
     except Exception:
         return None
 
@@ -82,7 +86,9 @@ def is_latest_version() -> Optional[bool]:
 
 
 def show_help() -> None:
-    """CLI command function for `xulbux-lib` command, which shows some information about the library."""
-    FormatCodes._config_console()
+    """CLI command function for `xulbux-lib` command,<br>
+    which shows some information about the library."""
+
+    FormatCodes._config_terminal()
     print(CLI_HELP)
     Console.pause_exit("  [dim](Press any key to exit...)\n\n", pause=True)

src/xulbux/cli/tools.py

@@ -3,14 +3,17 @@
 
 
 def render_format_codes():
-    """CLI command function for `xulbux-lib fc` command, which allows you to parse
-    and render a given string's format codes as ANSI console output."""
+    """CLI command function for `xulbux-lib fc` command, which allows you to parse<br>
+    and render a given string's format codes as ANSI terminal output."""
+
     args = Console.get_args({"input": "before"})
     vals = args.input.values[1:]  # EXCLUDE THE COMMAND ITSELF
 
     if not vals:
-        FormatCodes.print("\n[_|i|dim]Provide a string to parse and render\n"
-                          "its format codes as ANSI console output.[_]\n")
+        FormatCodes.print(
+            "\n[_|i|dim]Provide a string to parse and render\n"
+            "its format codes as ANSI terminal output.[_]\n"
+        )
 
     else:
         ansi = FormatCodes.to_ansi("".join(vals))