update 1.8.2

Author: xulbux

CHANGELOG.md

@@ -22,6 +22,9 @@
 * spaces between a format code and the auto-reset-brackets are no longer allowed, so `[red]␣(text)` will not be automatically reset and output as `␣(text)`
 * added a new class to `ProgressBar` to the `console` module
 * made small performance improvement in `FormatCodes.to_ansi()`
+* added missing docstrings to several public class variables
+* added the missing tests for methods in the `console` module
+* added test for the last two modules that didn't have test until now: `regex` and `system`
 
 ## 20.08.2025 `v1.8.1`
 * **fixed a critical bug which caused the package to not install properly and make the whole library not work**

pyproject.toml

@@ -163,5 +163,7 @@ testpaths = [
   "tests/test_format_codes.py",
   "tests/test_json.py",
   "tests/test_path.py",
+  "tests/test_regex.py",
   "tests/test_string.py",
+  "tests/test_system.py",
 ]

src/xulbux/color.py

@@ -92,9 +92,13 @@ class rgba:
 
     def __init__(self, r: int, g: int, b: int, a: Optional[float] = None, _validate: bool = True):
         self.r: int
+        """The red channel (`0`–`255`)"""
         self.g: int
+        """The green channel (`0`–`255`)"""
         self.b: int
+        """The blue channel (`0`–`255`)"""
         self.a: Optional[float]
+        """The alpha channel (`0.0`–`1.0`) or `None` if not set"""
         if not _validate:
             self.r, self.g, self.b, self.a = r, g, b, a
             return
@@ -291,9 +295,13 @@ class hsla:
 
     def __init__(self, h: int, s: int, l: int, a: Optional[float] = None, _validate: bool = True):
         self.h: int
+        """The hue channel (`0`–`360`)"""
         self.s: int
+        """The saturation channel (`0`–`100`)"""
         self.l: int
+        """The lightness channel (`0`–`100`)"""
         self.a: Optional[float]
+        """The alpha channel (`0.0`–`1.0`) or `None` if not set"""
         if not _validate:
             self.h, self.s, self.l, self.a = h, s, l, a
             return
@@ -496,9 +504,13 @@ def __init__(
         _a: Optional[float] = None,
     ):
         self.r: int
+        """The red channel (`0`–`255`)"""
         self.g: int
+        """The green channel (`0`–`255`)"""
         self.b: int
+        """The blue channel (`0`–`255`)"""
         self.a: Optional[float]
+        """The alpha channel (`0.0`–`1.0`) or `None` if not set"""
         if all(x is not None for x in (_r, _g, _b)):
             self.r, self.g, self.b, self.a = cast(int, _r), cast(int, _g), cast(int, _b), _a
             return

src/xulbux/console.py

@@ -78,7 +78,9 @@ class ArgResult:
 
     def __init__(self, exists: bool, value: Any | list[Any]):
         self.exists: bool = exists
+        """Whether the argument was found or not."""
         self.value: Any = value
+        """The value given with the found argument."""
 
     def __bool__(self):
         return self.exists
@@ -969,55 +971,39 @@ def __init__(
     ):
         self.active: bool = False
         """Whether the progress bar is currently active (intercepting stdout) or not."""
-        self.min_width: int = max(1, min_width)
+        self.min_width: int
         """The min width of the progress bar in chars."""
-        self.max_width: int = max(self.min_width, max_width)
+        self.max_width: int
         """The max width of the progress bar in chars."""
-        self.bar_format: str = bar_format
+        self.bar_format: str
         """The format string used to render the progress bar."""
-        self.limited_bar_format: str = limited_bar_format
+        self.limited_bar_format: str
         """The simplified format string used when the console width is too small."""
-        self.chars: tuple[str, ...] = chars
+        self.chars: tuple[str, ...]
         """A tuple of characters ordered from full to empty progress."""
 
+        self.set_width(min_width, max_width)
+        self.set_bar_format(bar_format, limited_bar_format)
+        self.set_chars(chars)
+
         self._buffer: list[str] = []
         self._original_stdout: Optional[TextIO] = None
         self._current_progress_str: str = ""
         self._last_line_len: int = 0
 
-    def show_progress(self, current: int, total: int, label: Optional[str] = None) -> None:
-        """Show or update the progress bar.\n
-        -----------------------------------------------------------------------------------------
-        - `current` -⠀the current progress value (below 0 or greater than `total` hides the bar)
-        - `total` -⠀the total value representing 100% progress (must be greater than 0)
-        - `label` -⠀an optional label to display alongside the progress bar"""
-        if total <= 0:
-            raise ValueError("Total must be greater than 0.")
-
-        try:
-            if not self.active:
-                self._start_intercepting()
-            self._flush_buffer()
-            self._draw_progress_bar(current, total, label or "")
-            if current < 0 or current > total:
-                self.hide_progress()
-        except Exception:
-            self._emergency_cleanup()
-            raise
-
-    def hide_progress(self) -> None:
-        """Hide the progress bar and restore normal console output."""
-        if self.active:
-            self._clear_progress_line()
-            self._stop_intercepting()
-
     def set_width(self, min_width: Optional[int] = None, max_width: Optional[int] = None) -> None:
         """Set the width of the progress bar.\n
         --------------------------------------------------------------
         - `min_width` -⠀the min width of the progress bar in chars
         - `max_width` -⠀the max width of the progress bar in chars"""
-        self.min_width = self.min_width if min_width is None else max(1, min_width)
-        self.max_width = self.max_width if max_width is None else max(self.min_width, max_width)
+        if min_width is not None:
+            if min_width < 1:
+                raise ValueError("Minimum width must be at least 1.")
+            self.min_width = max(1, min_width)
+        if max_width is not None:
+            if max_width < 1:
+                raise ValueError("Maximum width must be at least 1.")
+            self.max_width = max(self.min_width, max_width)
 
     def set_bar_format(self, bar_format: Optional[str] = None, limited_bar_format: Optional[str] = None) -> None:
         """Set the format string used to render the progress bar.\n
@@ -1032,17 +1018,79 @@ def set_bar_format(self, bar_format: Optional[str] = None, limited_bar_format: O
         --------------------------------------------------------------------------------------------------
         The bar format (also limited) can additionally be formatted with special formatting codes. For
         more detailed information about formatting codes, see the `format_codes` module documentation."""
-        self.bar_format = "{l} |{b}| [b]({c})/{t} [dim](([i]({p}%)))" if bar_format is None else bar_format
-        self.limited_bar_format = "|{b}|" if limited_bar_format is None else limited_bar_format
-
-    def set_chars(self, chars: Optional[tuple[str, ...]] = None) -> None:
+        if bar_format is not None:
+            if not _COMPILED["bar"].search(bar_format):
+                raise ValueError("'bar_format' must contain the '{bar}' or '{b}' placeholder.")
+            self.bar_format = bar_format
+        if limited_bar_format is not None:
+            if not _COMPILED["bar"].search(limited_bar_format):
+                raise ValueError("'limited_bar_format' must contain the '{bar}' or '{b}' placeholder.")
+            self.limited_bar_format = limited_bar_format
+
+    def set_chars(self, chars: tuple[str, ...]) -> None:
         """Set the characters used to render the progress bar.\n
         --------------------------------------------------------------------------
         - `chars` -⠀a tuple of characters ordered from full to empty progress<br>
           The first character represents completely filled sections, intermediate
           characters create smooth transitions, and the last character represents
           empty sections. If None, uses default Unicode block characters."""
-        self.chars = ("█", "▉", "▊", "▋", "▌", "▍", "▎", "▏", " ") if chars is None else chars
+        if len(chars) < 2:
+            raise ValueError("'chars' must contain at least two characters (full and empty).")
+        if not all(len(c) == 1 for c in chars if isinstance(c, str)):
+            raise ValueError("All 'chars' items must be single-character strings.")
+        self.chars = chars
+
+    def show_progress(self, current: int, total: int, label: Optional[str] = None) -> None:
+        """Show or update the progress bar.\n
+        -------------------------------------------------------------------------------------------
+        - `current` -⠀the current progress value (below `0` or greater than `total` hides the bar)
+        - `total` -⠀the total value representing 100% progress (must be greater than `0`)
+        - `label` -⠀an optional label which is inserted at the `{label}` or `{l}` placeholder"""
+        if total <= 0:
+            raise ValueError("Total must be greater than 0.")
+
+        try:
+            if not self.active:
+                self._start_intercepting()
+            self._flush_buffer()
+            self._draw_progress_bar(current, total, label or "")
+            if current < 0 or current > total:
+                self.hide_progress()
+        except Exception:
+            self._emergency_cleanup()
+            raise
+
+    def hide_progress(self) -> None:
+        """Hide the progress bar and restore normal console output."""
+        if self.active:
+            self._clear_progress_line()
+            self._stop_intercepting()
+
+    @contextmanager
+    def progress_context(self, total: int, label: Optional[str] = None) -> Generator[Callable[[int], None], None, None]:
+        """Context manager for automatic cleanup. Returns a function to update progress.\n
+        --------------------------------------------------------------------------------------
+        - `total` -⠀the total value representing 100% progress (must be greater than `0`)
+        - `label` -⠀an optional label which is inserted at the `{label}` or `{l}` placeholder
+        --------------------------------------------------------------------------------------
+        Example usage:
+        ```python
+        with ProgressBar().progress_context(500, "Loading") as update_progress:
+            for i in range(500):
+                # Do some work...
+                update_progress(i)  # Update progress
+        ```"""
+        try:
+
+            def update_progress(current: int) -> None:
+                self.show_progress(current, total, label)
+
+            yield update_progress
+        except Exception:
+            self._emergency_cleanup()
+            raise
+        finally:
+            self.hide_progress()
 
     def _start_intercepting(self) -> None:
         self.active = True
@@ -1132,32 +1180,6 @@ def _redraw_progress_bar(self) -> None:
             self._original_stdout.write(f"{self._current_progress_str}")
             self._original_stdout.flush()
 
-    @contextmanager
-    def progress_context(self, total: int, label: Optional[str] = None) -> Generator[Callable[[int], None], None, None]:
-        """Context manager for automatic cleanup. Returns a function to update progress.\n
-        -----------------------------------------------------------------------------------
-        - `total` -⠀the total value representing 100% progress
-        - `label` -⠀an optional label to display alongside the progress bar
-        -----------------------------------------------------------------------------------
-        Example usage:
-        ```python
-        with ProgressBar().progress_context(500, "Loading") as update_progress:
-            for i in range(501):
-                # Do some work...
-                update_progress(i)  # Update progress
-        ```"""
-        try:
-
-            def update_progress(current: int) -> None:
-                self.show_progress(current, total, label)
-
-            yield update_progress
-        except Exception:
-            self._emergency_cleanup()
-            raise
-        finally:
-            self.hide_progress()
-
 
 class _InterceptedOutput(_io.StringIO):
     """Custom StringIO that captures output and stores it in the progress bar buffer."""

src/xulbux/system.py

@@ -12,7 +12,7 @@ class _IsElevated:
     def __get__(self, obj, owner=None):
         try:
             if _os.name == "nt":
-                return _ctypes.windll.shell32.IsUserAnAdmin() != 0
+                return _ctypes.windll.shell32.IsUserAnAdmin() != 0  # type: ignore[attr-defined]
             elif _os.name == "posix":
                 return _os.geteuid() == 0  # type: ignore[attr-defined]
         except Exception: