make type corrections, add docstrings to dunder methods, rename constant, add new helper methods & add new class properties

Author: xulbux

CHANGELOG.md

@@ -18,13 +18,22 @@
 <span id="v1-9-3" />
 
 ## ... `v1.9.3` Big Update 🚀
+
 * Added a new method `Color.str_to_hsla()` to parse HSLA colors from strings.
-* Changed the default syntax colors for `Data.to_str()` and therefore also `Data.print()` to console default colors.
+* Changed the default syntax highlighting for `Data.to_str()` and therefore also `Data.print()` to use console default colors.
+* Added the missing but needed dunder methods to the `Args` and `ArgResult` classes and the `rgba`, `hsla` and `hexa` color objects for better usability and type checking.
+* Added three new methods to `Args`:
+  - `get()` returns the argument result for a given alias, or a default value if not found
+  - `existing()` yields only the existing arguments as tuples of `(alias, ArgResult)`
+  - `missing()` yields only the missing arguments as tuples of `(alias, ArgResult)`
 * Added a new attribute `is_positional` to `ArgResult`, which indicates whether the argument is a positional argument or not.
+* The `ArgResult` class now also has a `dict()` method, which returns the argument result as a dictionary.
+* Added new properties `is_tty` and `supports_color` to the `Console` class, `home` to the `Path` class and `is_win` to the `System` class.
 * Added the option to add format specifiers to the `{current}`, `{total}` and `{percentage}` placeholders in the `bar_format` and `limited_bar_format` of `ProgressBar`.
 * Finally fixed the `C901 'Console.get_args' is too complex (39)` linting error by refactoring the method into its own helper class.
+* Changed the string- and repr-representations of the `rgba` and `hsla` color objects and newly implemented it for the `Args` and `ArgResult` classes.
 * Made internal, global constants, which's values never change, into `Final` constants for better type checking.
-* The names of all internal classes and methods are all noi longer prefixed with a double underscore (`__`), but a single underscore (`_`) instead.
+* The names of all internal classes and methods are all no longer prefixed with a double underscore (`__`), but a single underscore (`_`) instead.
 * Changed all methods defined as `@staticmethod` to `@classmethod` where applicable, to improve inheritance capabilities.
 * Adjusted the whole library's type hints to be way more strict and accurate, using `mypy` as static type checker.
 * Change the class-property definitions to be defined via `metaclass` and using `@property` decorators, to make them compatible with `mypyc`.
@@ -35,13 +44,15 @@
 
 **BREAKING CHANGES:**
 * Renamed `Data.to_str()` to `Data.render()`, since that describes its functionality better (*especially with the syntax highlighting option*).
+* Renamed the constant `ANSI.ESCAPED_CHAR` to `ANSI.CHAR_ESCAPED` for better consistency with the other constant names.
 * Removed the general `Pattern` and `Match` type aliases from the `base.types` module (*they are pointless since you should always use a specific type and not "type1 OR typeB"*).
 * Removed the `_` prefix from the param `_syntax_highlighting` in `Data.render()`, since it's no longer just for internal use.
 
 
 <span id="v1-9-2" />
 
 ## 16.12.2025 `v1.9.2`
+
 * Added a new class `LazyRegex` to the `regex` module, which is used to define regex patterns that are only compiled when they are used for the first time.
 * Removed unnecessary character escaping in the precompiled regex patterns in the `console` module.
 * Removed all the runtime type-checks that can also be checked using static type-checking tools, since you're supposed to use type checkers in modern python anyway, and to improve performance.
@@ -64,6 +75,7 @@
 <span id="v1-9-1" />
 
 ## 26.11.2025 `v1.9.1`
+
 * Unified the module and class docstring styles throughout the whole library.
 * Moved the Protocol `ProgressUpdater` from the `console` module to the `types` module.
 * Added throttling to the `ProgressBar` update methods to impact the actual process' performance as little as possible.
@@ -79,6 +91,7 @@
 <span id="v1-9-0" />
 
 ## 21.11.2025 `v1.9.0` Big Update 🚀
+
 * Standardized the docstrings for all public methods in the whole library to use the same style and structure.
 * Replaced left over single quotes with double quotes for consistency.
 * Fixed a bug inside `Data.remove_empty_items()`, where types other than strings where passed to `String.is_empty()`, which caused an exception.
@@ -218,7 +231,7 @@
 ## 17.06.2025 `v1.7.2`
 
 * The `Console.w`, `Console.h` and `Console.wh` class properties now return a default size if there is no console, instead of throwing an error.
-* It wasn't actually possible to use default console-colors (*e.g.* `"red"`, `"green"`, ...) for the color params in `Console.log()` so that option was completely removed again.
+* It wasn't actually possible to use default console-colors (*e.g.* `"red"`, `"green"`, …) for the color params in `Console.log()` so that option was completely removed again.
 * Upgraded the speed of `FormatCodes.to_ansi()` by adding the internal ability to skip the `default_color` validation.
 * Fixed type hints for the whole library.
 * Fixed a small bug in `Console.pause_exit()`, where the key, pressed to unpause wasn't suppressed, so it was written into the next console input after unpausing.
@@ -232,7 +245,7 @@
 * Added a new method `Console.log_box_bordered()`, which does the same as `Console.log_box_filled()`, but with a border instead of a background color.
 * The module `xx_format_codes` now treats the `[*]` to-default-color-reset as a normal full-reset, when no `default_color` is set, instead of just counting it as an invalid format code.
 * Fixed bug where entering a color as HEX integer in the color params of the methods `Console.log()`, `Console.log_box_filled()` and `Console.log_box_bordered()` would not work, because it was not properly converted to a format code.
-* You can now use default console colors (*e.g.* `"red"`, `"green"`, ...) for the color params in `Console.log()`.
+* You can now use default console colors (*e.g.* `"red"`, `"green"`, …) for the color params in `Console.log()`.
 * The methods `Console.log_box_filled()` and `Console.log_box_bordered()` no longer right-strip spaces, so you can make multiple log boxes the same width, by adding spaces to the end of the text.
 
 **BREAKING CHANGES:**
@@ -798,7 +811,7 @@ from XulbuX import rgb, hsl, hexa
   <thead>
     <tr>
       <th>Features</th>
-      <th>class, type, function, ...</th>
+      <th>class, type, function, …</th>
     </tr>
   </thead>
   <tbody>

src/xulbux/base/consts.py

@@ -76,7 +76,7 @@ class CHARS:
 class ANSI:
     """Constants and utilities for ANSI escape code sequences."""
 
-    ESCAPED_CHAR: Final = "\\x1b"
+    CHAR_ESCAPED: Final = r"\x1b"
     """Printable ANSI escape character."""
     CHAR: Final = "\x1b"
     """ANSI escape character."""

src/xulbux/color.py

@@ -66,6 +66,7 @@ def __init__(self, r: int, g: int, b: int, a: Optional[float] = None, _validate:
         self.a = None if a is None else (1.0 if a > 1.0 else float(a))
 
     def __len__(self) -> int:
+        """The number of components in the color (3 or 4)."""
         return 3 if self.a is None else 4
 
     def __iter__(self) -> Iterator:
@@ -74,17 +75,21 @@ def __iter__(self) -> Iterator:
     def __getitem__(self, index: int) -> int | float:
         return ((self.r, self.g, self.b) + (() if self.a is None else (self.a, )))[index]
 
+    def __eq__(self, other: object) -> bool:
+        """Check if two `rgba` objects are the same color."""
+        if not isinstance(other, rgba):
+            return False
+        return (self.r, self.g, self.b, self.a) == (other.r, other.g, other.b, other.a)
+
+    def __ne__(self, other: object) -> bool:
+        """Check if two `rgba` objects are different colors."""
+        return not self.__eq__(other)
+
     def __repr__(self) -> str:
         return f"rgba({self.r}, {self.g}, {self.b}{'' if self.a is None else f', {self.a}'})"
 
     def __str__(self) -> str:
-        return f"({self.r}, {self.g}, {self.b}{'' if self.a is None else f', {self.a}'})"
-
-    def __eq__(self, other: "rgba") -> bool:  # type: ignore[override]
-        if not isinstance(other, rgba):
-            return False
-        else:
-            return (self.r, self.g, self.b, self.a) == (other.r, other.g, other.b, other.a)
+        return self.__repr__()
 
     def dict(self) -> dict:
         """Returns the color components as a dictionary with keys `"r"`, `"g"`, `"b"` and optionally `"a"`."""
@@ -325,6 +330,7 @@ def __init__(self, h: int, s: int, l: int, a: Optional[float] = None, _validate:
         self.a = None if a is None else (1.0 if a > 1.0 else float(a))
 
     def __len__(self) -> int:
+        """The number of components in the color (3 or 4)."""
         return 3 if self.a is None else 4
 
     def __iter__(self) -> Iterator:
@@ -333,17 +339,21 @@ def __iter__(self) -> Iterator:
     def __getitem__(self, index: int) -> int | float:
         return ((self.h, self.s, self.l) + (() if self.a is None else (self.a, )))[index]
 
+    def __eq__(self, other: object) -> bool:
+        """Check if two `hsla` objects are the same color."""
+        if not isinstance(other, hsla):
+            return False
+        return (self.h, self.s, self.l, self.a) == (other.h, other.s, other.l, other.a)
+
+    def __ne__(self, other: object) -> bool:
+        """Check if two `hsla` objects are different colors."""
+        return not self.__eq__(other)
+
     def __repr__(self) -> str:
-        return f'hsla({self.h}°, {self.s}%, {self.l}%{"" if self.a is None else f", {self.a}"})'
+        return f"hsla({self.h}°, {self.s}%, {self.l}%{'' if self.a is None else f', {self.a}'})"
 
     def __str__(self) -> str:
-        return f'({self.h}°, {self.s}%, {self.l}%{"" if self.a is None else f", {self.a}"})'
-
-    def __eq__(self, other: "hsla") -> bool:  # type: ignore[override]
-        if not isinstance(other, hsla):
-            return False
-        else:
-            return (self.h, self.s, self.l, self.a) == (other.h, other.s, other.l, other.a)
+        return self.__repr__()
 
     def dict(self) -> dict:
         """Returns the color components as a dictionary with keys `"h"`, `"s"`, `"l"` and optionally `"a"`."""
@@ -617,6 +627,7 @@ def __init__(
             raise TypeError(f"The 'color' parameter must be a string or integer, got {type(color)}")
 
     def __len__(self) -> int:
+        """The number of components in the color (3 or 4)."""
         return 3 if self.a is None else 4
 
     def __iter__(self) -> Iterator:
@@ -627,18 +638,21 @@ def __getitem__(self, index: int) -> str | int:
         return ((f"{self.r:02X}", f"{self.g:02X}", f"{self.b:02X}") \
                 + (() if self.a is None else (f"{int(self.a * 255):02X}", )))[index]
 
+    def __eq__(self, other: object) -> bool:
+        """Check if two `hexa` objects are the same color."""
+        if not isinstance(other, hexa):
+            return False
+        return (self.r, self.g, self.b, self.a) == (other.r, other.g, other.b, other.a)
+
+    def __ne__(self, other: object) -> bool:
+        """Check if two `hexa` objects are different colors."""
+        return not self.__eq__(other)
+
     def __repr__(self) -> str:
-        return f'hexa(#{self.r:02X}{self.g:02X}{self.b:02X}{"" if self.a is None else f"{int(self.a * 255):02X}"})'
+        return f"hexa(#{self.r:02X}{self.g:02X}{self.b:02X}{'' if self.a is None else f'{int(self.a * 255):02X}'})"
 
     def __str__(self) -> str:
-        return f'#{self.r:02X}{self.g:02X}{self.b:02X}{"" if self.a is None else f"{int(self.a * 255):02X}"}'
-
-    def __eq__(self, other: "hexa") -> bool:  # type: ignore[override]
-        """Returns whether the other color is equal to this one."""
-        if not isinstance(other, hexa):
-            return False
-        else:
-            return (self.r, self.g, self.b, self.a) == (other.r, other.g, other.b, other.a)
+        return f"#{self.r:02X}{self.g:02X}{self.b:02X}{'' if self.a is None else f'{int(self.a * 255):02X}'}"
 
     def dict(self) -> dict:
         """Returns the color components as a dictionary with hex string values for keys `"r"`, `"g"`, `"b"` and optionally `"a"`."""