xulbux 1.8.2__py3-none-any.whl → 1.8.3__py3-none-any.whl

xulbux/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.8.2"
+__version__ = "1.8.3"
 
 __author__ = "XulbuX"
 __email__ = "xulbux.real@gmail.com"

xulbux/cli/help.py

@@ -20,8 +20,8 @@ def get_latest_version() -> Optional[str]:
 
 def is_latest_version() -> Optional[bool]:
     try:
-        latest = get_latest_version()
-        if latest in ("", None): return None
+        if (latest := get_latest_version()) in ("", None):
+            return None
         latest_v_parts = tuple(int(part) for part in latest.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

xulbux/console.py

@@ -10,7 +10,7 @@ from .format_codes import FormatCodes, _COMPILED as _FC_COMPILED
 from .string import String
 from .color import Color, Rgba, Hexa
 
-from typing import Generator, Callable, Optional, Literal, Mapping, Pattern, TypeVar, TextIO, Any, cast
+from typing import Generator, TypedDict, Callable, Optional, Literal, Mapping, Pattern, TypeVar, TextIO, Any, overload, cast, Protocol
 from prompt_toolkit.key_binding import KeyPressEvent, KeyBindings
 from prompt_toolkit.validation import ValidationError, Validator
 from prompt_toolkit.styles import Style
@@ -27,6 +27,10 @@ import io as _io
 
 
 _COMPILED: dict[str, Pattern] = {  # PRECOMPILE REGULAR EXPRESSIONS
+    "hr": _re.compile(r"(?i)\{hr\}"),
+    "hr_no_nl": _re.compile(r"(?i)(?<!\n){hr}(?!\n)"),
+    "hr_r_nl": _re.compile(r"(?i)(?<!\n){hr}(?=\n)"),
+    "hr_l_nl": _re.compile(r"(?i)(?<=\n){hr}(?!\n)"),
     "label": _re.compile(r"(?i)\{(?:label|l)\}"),
     "bar": _re.compile(r"(?i)\{(?:bar|b)\}"),
     "current": _re.compile(r"(?i)\{(?:current|c)\}"),
@@ -69,6 +73,11 @@ class _ConsoleUser:
         return _os.getenv("USER") or _os.getenv("USERNAME") or _getpass.getuser()
 
 
+class _ArgConfigWithDefault(TypedDict):
+    flags: list[str] | tuple[str, ...]
+    default: Any
+
+
 class ArgResult:
     """Represents the result of a parsed command-line argument and contains the following attributes:
     - `exists` -⠀if the argument was found or not
@@ -146,8 +155,10 @@ class Console:
 
     @staticmethod
     def get_args(
-        find_args: Mapping[str, list[str] | tuple[str, ...] | dict[str, list[str] | tuple[str, ...] | Any]
-                           | Literal["before", "after"]],
+        find_args: Mapping[
+            str,
+            list[str] | tuple[str, ...] | _ArgConfigWithDefault | Literal["before", "after"],
+        ],
         allow_spaces: bool = False
     ) -> Args:
         """Will search for the specified arguments in the command line
@@ -241,8 +252,11 @@ class Console:
             elif isinstance(config, dict):
                 if "flags" not in config:
                     raise ValueError(f"Invalid configuration for alias '{alias}'. Dictionary must contain a 'flags' key.")
-                flags = config["flags"]
-                default_value = config.get("default")
+                if "default" not in config:
+                    raise ValueError(
+                        f"Invalid configuration for alias '{alias}'. Dictionary must contain a 'default' key. Use a simple list/tuple if no default value is needed."
+                    )
+                flags, default_value = config["flags"], config["default"]
                 if not isinstance(flags, (list, tuple)):
                     raise ValueError(f"Invalid 'flags' for alias '{alias}'. Must be a list or tuple.")
                 results[alias] = {"exists": False, "value": default_value}
@@ -269,14 +283,14 @@ class Console:
                 if first_flag_pos is None:
                     first_flag_pos = i
                 # CHECK IF THIS FLAG HAS A VALUE FOLLOWING IT
-                flag_has_value = (i + 1 < args_len and not args[i + 1].startswith("-") and args[i + 1] not in arg_lookup)
+                flag_has_value = (i + 1 < args_len and args[i + 1] not in arg_lookup)
                 if flag_has_value:
                     if not allow_spaces:
                         last_flag_with_value_pos = i + 1
                     else:
                         # FIND THE END OF THE MULTI-WORD VALUE
                         j = i + 1
-                        while j < args_len and not args[j].startswith("-") and args[j] not in arg_lookup:
+                        while j < args_len and args[j] not in arg_lookup:
                             j += 1
                         last_flag_with_value_pos = j - 1
 
@@ -286,7 +300,7 @@ class Console:
                 before_args = []
                 end_pos = first_flag_pos if first_flag_pos is not None else args_len
                 for i in range(end_pos):
-                    if not args[i].startswith("-"):
+                    if args[i] not in arg_lookup:
                         before_args.append(String.to_type(args[i]))
                 if before_args:
                     results[alias]["value"] = before_args
@@ -300,7 +314,7 @@ class Console:
             if alias:
                 results[alias]["exists"] = True
                 value_found_after_flag = False
-                if i + 1 < args_len and not args[i + 1].startswith("-"):
+                if i + 1 < args_len and args[i + 1] not in arg_lookup:
                     if not allow_spaces:
                         results[alias]["value"] = String.to_type(args[i + 1])
                         i += 1
@@ -308,7 +322,7 @@ class Console:
                     else:
                         value_parts = []
                         j = i + 1
-                        while j < args_len and not args[j].startswith("-"):
+                        while j < args_len and args[j] not in arg_lookup:
                             value_parts.append(args[j])
                             j += 1
                         if value_parts:
@@ -316,7 +330,7 @@ class Console:
                             i = j - 1
                             value_found_after_flag = True
                 if not value_found_after_flag:
-                    results[alias]["value"] = True
+                    results[alias]["value"] = None
             i += 1
 
         # COLLECT "after" POSITIONAL ARGUMENTS
@@ -335,7 +349,7 @@ class Console:
                         start_pos = last_flag_pos + 1
 
                 for i in range(start_pos, args_len):
-                    if not args[i].startswith("-") and args[i] not in arg_lookup:
+                    if args[i] not in arg_lookup:
                         after_args.append(String.to_type(args[i]))
 
                 if after_args:
@@ -346,9 +360,9 @@ class Console:
 
     @staticmethod
     def pause_exit(
+        prompt: object = "",
         pause: bool = True,
         exit: bool = False,
-        prompt: object = "",
         exit_code: int = 0,
         reset_ansi: bool = False,
     ) -> None:
@@ -473,13 +487,15 @@ class Console:
         default_color: Optional[Rgba | Hexa] = None,
         pause: bool = False,
         exit: bool = False,
+        exit_code: int = 0,
+        reset_ansi: bool = True,
     ) -> None:
         """A preset for `log()`: `DEBUG` log message with the options to pause
         at the message and exit the program after the message was printed.
         If `active` is false, no debug message will be printed."""
         if active:
             Console.log("DEBUG", prompt, format_linebreaks, start, end, COLOR.YELLOW, default_color)
-            Console.pause_exit(pause, exit)
+            Console.pause_exit("", pause=pause, exit=exit, exit_code=exit_code, reset_ansi=reset_ansi)
 
     @staticmethod
     def info(
@@ -490,11 +506,13 @@ class Console:
         default_color: Optional[Rgba | Hexa] = None,
         pause: bool = False,
         exit: bool = False,
+        exit_code: int = 0,
+        reset_ansi: bool = True,
     ) -> None:
         """A preset for `log()`: `INFO` log message with the options to pause
         at the message and exit the program after the message was printed."""
         Console.log("INFO", prompt, format_linebreaks, start, end, COLOR.BLUE, default_color)
-        Console.pause_exit(pause, exit)
+        Console.pause_exit("", pause=pause, exit=exit, exit_code=exit_code, reset_ansi=reset_ansi)
 
     @staticmethod
     def done(
@@ -505,11 +523,13 @@ class Console:
         default_color: Optional[Rgba | Hexa] = None,
         pause: bool = False,
         exit: bool = False,
+        exit_code: int = 0,
+        reset_ansi: bool = True,
     ) -> None:
         """A preset for `log()`: `DONE` log message with the options to pause
         at the message and exit the program after the message was printed."""
         Console.log("DONE", prompt, format_linebreaks, start, end, COLOR.TEAL, default_color)
-        Console.pause_exit(pause, exit)
+        Console.pause_exit("", pause=pause, exit=exit, exit_code=exit_code, reset_ansi=reset_ansi)
 
     @staticmethod
     def warn(
@@ -520,11 +540,13 @@ class Console:
         default_color: Optional[Rgba | Hexa] = None,
         pause: bool = False,
         exit: bool = False,
+        exit_code: int = 1,
+        reset_ansi: bool = True,
     ) -> None:
         """A preset for `log()`: `WARN` log message with the options to pause
         at the message and exit the program after the message was printed."""
         Console.log("WARN", prompt, format_linebreaks, start, end, COLOR.ORANGE, default_color)
-        Console.pause_exit(pause, exit)
+        Console.pause_exit("", pause=pause, exit=exit, exit_code=exit_code, reset_ansi=reset_ansi)
 
     @staticmethod
     def fail(
@@ -535,12 +557,13 @@ class Console:
         default_color: Optional[Rgba | Hexa] = None,
         pause: bool = False,
         exit: bool = True,
+        exit_code: int = 1,
         reset_ansi: bool = True,
     ) -> None:
         """A preset for `log()`: `FAIL` log message with the options to pause
         at the message and exit the program after the message was printed."""
         Console.log("FAIL", prompt, format_linebreaks, start, end, COLOR.RED, default_color)
-        Console.pause_exit(pause, exit, reset_ansi=reset_ansi)
+        Console.pause_exit("", pause=pause, exit=exit, exit_code=exit_code, reset_ansi=reset_ansi)
 
     @staticmethod
     def exit(
@@ -551,12 +574,13 @@ class Console:
         default_color: Optional[Rgba | Hexa] = None,
         pause: bool = False,
         exit: bool = True,
+        exit_code: int = 0,
         reset_ansi: bool = True,
     ) -> None:
         """A preset for `log()`: `EXIT` log message with the options to pause
         at the message and exit the program after the message was printed."""
         Console.log("EXIT", prompt, format_linebreaks, start, end, COLOR.MAGENTA, default_color)
-        Console.pause_exit(pause, exit, reset_ansi=reset_ansi)
+        Console.pause_exit("", pause=pause, exit=exit, exit_code=exit_code, reset_ansi=reset_ansi)
 
     @staticmethod
     def log_box_filled(
@@ -611,7 +635,7 @@ class Console:
         w_padding: int = 1,
         w_full: bool = False,
         indent: int = 0,
-        _border_chars: Optional[tuple[str, str, str, str, str, str, str, str]] = None,
+        _border_chars: Optional[tuple[str, str, str, str, str, str, str, str, str, str, str]] = None,
     ) -> None:
         """Will print a bordered box, containing a formatted log message:
         - `*values` -⠀the box content (each value is on a new line)
@@ -624,15 +648,17 @@ class Console:
         - `w_full` -⠀whether to make the box be the full console width or not
         - `indent` -⠀the indentation of the box (in chars)
         - `_border_chars` -⠀define your own border characters set (overwrites `border_type`)\n
-        ---------------------------------------------------------------------------------------
+        ---------------------------------------------------------------------------------------------
+        You can insert horizontal rules to split the box content by using `{hr}` in the `*values`.\n
+        ---------------------------------------------------------------------------------------------
         The box content can be formatted with special formatting codes. For more detailed
         information about formatting codes, see `format_codes` module documentation.\n
-        ---------------------------------------------------------------------------------------
+        ---------------------------------------------------------------------------------------------
         The `border_type` can be one of the following:
-        - `"standard" = ('┌', '─', '┐', '│', '┘', '─', '└', '│')`
-        - `"rounded" = ('╭', '─', '╮', '│', '╯', '─', '╰', '│')`
-        - `"strong" = ('┏', '━', '┓', '┃', '┛', '━', '┗', '┃')`
-        - `"double" = ('╔', '═', '╗', '║', '╝', '═', '╚', '║')`\n
+        - `"standard" = ('┌', '─', '┐', '│', '┘', '─', '└', '│', '├', '─', '┤')`
+        - `"rounded" = ('╭', '─', '╮', '│', '╯', '─', '╰', '│', '├', '─', '┤')`
+        - `"strong" = ('┏', '━', '┓', '┃', '┛', '━', '┗', '┃', '┣', '━', '┫')`
+        - `"double" = ('╔', '═', '╗', '║', '╝', '═', '╚', '║', '╠', '═', '╣')`\n
         The order of the characters is always:
         1. top-left corner
         2. top border
@@ -641,27 +667,31 @@ class Console:
         5. bottom-right corner
         6. bottom border
         7. bottom-left corner
-        8. left border"""
+        8. left border
+        9. left horizontal rule connector
+        10. horizontal rule
+        11. right horizontal rule connector"""
         borders = {
-            "standard": ('┌', '─', '┐', '│', '┘', '─', '└', '│'),
-            "rounded": ('╭', '─', '╮', '│', '╯', '─', '╰', '│'),
-            "strong": ('┏', '━', '┓', '┃', '┛', '━', '┗', '┃'),
-            "double": ('╔', '═', '╗', '║', '╝', '═', '╚', '║'),
+            "standard": ('┌', '─', '┐', '│', '┘', '─', '└', '│', '├', '─', '┤'),
+            "rounded": ('╭', '─', '╮', '│', '╯', '─', '╰', '│', '├', '─', '┤'),
+            "strong": ('┏', '━', '┓', '┃', '┛', '━', '┗', '┃', '┣', '━', '┫'),
+            "double": ('╔', '═', '╗', '║', '╝', '═', '╚', '║', '╠', '═', '╣'),
         }
         border_chars = borders.get(border_type, borders["standard"]) if _border_chars is None else _border_chars
-        lines, unfmt_lines, max_line_len = Console.__prepare_log_box(values, default_color)
+        lines, unfmt_lines, max_line_len = Console.__prepare_log_box(values, default_color, has_rules=True)
         pad_w_full = (Console.w - (max_line_len + (2 * w_padding)) - (len(border_chars[1] * 2))) if w_full else 0
         if border_style is not None and Color.is_valid(border_style):
             border_style = Color.to_hexa(border_style)
         spaces_l = " " * indent
         border_l = f"[{border_style}]{border_chars[7]}[*]"
         border_r = f"[{border_style}]{border_chars[3]}[_]"
+        border_t = f"{spaces_l}[{border_style}]{border_chars[0]}{border_chars[1] * (Console.w - (len(border_chars[1] * 2)) if w_full else max_line_len + (2 * w_padding))}{border_chars[2]}[_]"
+        border_b = f"{spaces_l}[{border_style}]{border_chars[6]}{border_chars[5] * (Console.w - (len(border_chars[5] * 2)) if w_full else max_line_len + (2 * w_padding))}{border_chars[4]}[_]"
+        h_rule = f"{spaces_l}[{border_style}]{border_chars[8]}{border_chars[9] * (Console.w - (len(border_chars[9] * 2)) if w_full else max_line_len + (2 * w_padding))}{border_chars[10]}[_]"
         lines = [
-            f"{spaces_l}{border_l}{' ' * w_padding}{line}[_]" + " " *
+            h_rule if _COMPILED["hr"].match(line) else f"{spaces_l}{border_l}{' ' * w_padding}{line}[_]" + " " *
             ((w_padding + max_line_len - len(unfmt)) + pad_w_full) + border_r for line, unfmt in zip(lines, unfmt_lines)
         ]
-        border_t = f"{spaces_l}[{border_style}]{border_chars[0]}{border_chars[1] * (Console.w - (len(border_chars[1] * 2)) if w_full else max_line_len + (2 * w_padding))}{border_chars[2]}[_]"
-        border_b = f"{spaces_l}[{border_style}]{border_chars[6]}{border_chars[5] * (Console.w - (len(border_chars[1] * 2)) if w_full else max_line_len + (2 * w_padding))}{border_chars[4]}[_]"
         FormatCodes.print(
             f"{start}{border_t}[_]\n" + "\n".join(lines) + f"\n{border_b}[_]",
             default_color=default_color,
@@ -673,9 +703,42 @@ class Console:
     def __prepare_log_box(
         values: tuple[object, ...],
         default_color: Optional[Rgba | Hexa] = None,
+        has_rules: bool = False,
     ) -> tuple[list[str], list[tuple[str, tuple[tuple[int, str], ...]]], int]:
         """Prepares the log box content and returns it along with the max line length."""
-        lines = [line for val in values for line in str(val).splitlines()]
+        if has_rules:
+            lines = []
+            for val in values:
+                val_str, result_parts, current_pos = str(val), [], 0
+                for match in _COMPILED["hr"].finditer(val_str):
+                    start, end = match.span()
+                    should_split_before = start > 0 and val_str[start - 1] != '\n'
+                    should_split_after = end < len(val_str) and val_str[end] != '\n'
+
+                    if should_split_before:
+                        if start > current_pos:
+                            result_parts.append(val_str[current_pos:start])
+                        if should_split_after:
+                            result_parts.append(match.group())
+                            current_pos = end
+                        else:
+                            current_pos = start
+                    else:
+                        if should_split_after:
+                            result_parts.append(val_str[current_pos:end])
+                            current_pos = end
+
+                if current_pos < len(val_str):
+                    result_parts.append(val_str[current_pos:])
+
+                if not result_parts:
+                    result_parts.append(val_str)
+
+                for part in result_parts:
+                    lines.extend(part.splitlines())
+        else:
+            lines = [line for val in values for line in str(val).splitlines()]
+
         unfmt_lines = [FormatCodes.remove_formatting(line, default_color) for line in lines]
         max_line_len = max(len(line) for line in unfmt_lines)
         return lines, cast(list[tuple[str, tuple[tuple[int, str], ...]]], unfmt_lines), max_line_len
@@ -755,7 +818,7 @@ class Console:
         mask_char: Optional[str] = None,
         min_len: Optional[int] = None,
         max_len: Optional[int] = None,
-        allowed_chars: str = CHARS.ALL,  #type: ignore[assignment]
+        allowed_chars: str = CHARS.ALL,  # type: ignore[assignment]
         allow_paste: bool = True,
         validator: Optional[Callable[[str], Optional[str]]] = None,
         default_val: Optional[T] = None,
@@ -825,7 +888,8 @@ class Console:
 
         def process_insert_text(text: str) -> tuple[str, set[str]]:
             removed_chars = set()
-            if not text: return "", removed_chars
+            if not text:
+                return "", removed_chars
             processed_text = "".join(c for c in text if ord(c) >= 32)
             if allowed_chars != CHARS.ALL:
                 filtered_text = ""
@@ -846,8 +910,8 @@ class Console:
         def insert_text_event(event: KeyPressEvent) -> None:
             nonlocal result_text, filtered_chars
             try:
-                insert_text = event.data
-                if not insert_text: return
+                if not (insert_text := event.data):
+                    return
                 buffer = event.app.current_buffer
                 cursor_pos = buffer.cursor_position
                 insert_text, filtered_chars = process_insert_text(insert_text)
@@ -928,7 +992,8 @@ class Console:
         FormatCodes.print(end, end="")
 
         if result_text in ("", None):
-            if has_default: return default_val
+            if has_default:
+                return default_val
             result_text = ""
 
         if output_type == str:
@@ -937,10 +1002,30 @@ class Console:
             try:
                 return output_type(result_text)  # type: ignore[call-arg]
             except (ValueError, TypeError):
-                if has_default: return default_val
+                if has_default:
+                    return default_val
                 raise
 
 
+class _ProgressUpdater(Protocol):
+    """Protocol for progress update function with proper type hints."""
+
+    @overload
+    def __call__(self, current: int) -> None:
+        """Update the current progress value."""
+        ...
+
+    @overload
+    def __call__(self, current: int, label: str) -> None:
+        """Update both current progress value and label."""
+        ...
+
+    @overload
+    def __call__(self, *, label: str) -> None:
+        """Update the progress label only (keyword-only)."""
+        ...
+
+
 class ProgressBar:
     """A console progress bar with smooth transitions and customizable appearance.\n
     -------------------------------------------------------------------------------------------------
@@ -1067,23 +1152,69 @@ class ProgressBar:
             self._stop_intercepting()
 
     @contextmanager
-    def progress_context(self, total: int, label: Optional[str] = None) -> Generator[Callable[[int], None], None, None]:
+    def progress_context(self, total: int, label: Optional[str] = None) -> Generator[_ProgressUpdater, 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
-        --------------------------------------------------------------------------------------
+        ----------------------------------------------------------------------------------------------------
+        The returned callable accepts keyword arguments. At least one of these parameters must be provided:
+        - `current` -⠀update the current progress value
+        - `label` -⠀update the progress label\n
+
         Example usage:
         ```python
-        with ProgressBar().progress_context(500, "Loading") as update_progress:
-            for i in range(500):
+        with ProgressBar().progress_context(500, "Loading...") as update_progress:
+            update_progress(0)  # Show empty bar at start
+
+            for i in range(400):
                 # Do some work...
                 update_progress(i)  # Update progress
+
+            update_progress(label="Finalizing...")  # Update label
+
+            for i in range(400, 500):
+                # Do some work...
+                update_progress(i, f"Finalizing ({i})")  # Update both
         ```"""
+        current_progress = 0
+        current_label = label
+
         try:
 
-            def update_progress(current: int) -> None:
-                self.show_progress(current, total, label)
+            def update_progress(*args, **kwargs) -> None:  # TYPE HINTS DEFINED IN '_ProgressUpdater' PROTOCOL
+                """Update the progress bar's current value and/or label."""
+                nonlocal current_progress, current_label
+                current = label = None
+
+                if len(args) > 2:
+                    raise TypeError(f"update_progress() takes at most 2 positional arguments ({len(args)} given)")
+                elif len(args) >= 1:
+                    current = args[0]
+                    if len(args) >= 2:
+                        label = args[1]
+
+                if "current" in kwargs:
+                    if current is not None:
+                        raise TypeError("update_progress() got multiple values for argument 'current'")
+                    current = kwargs["current"]
+                if "label" in kwargs:
+                    if label is not None:
+                        raise TypeError("update_progress() got multiple values for argument 'label'")
+                    label = kwargs["label"]
+
+                if unexpected := set(kwargs.keys()) - {"current", "label"}:
+                    raise TypeError(f"update_progress() got unexpected keyword argument(s): {', '.join(unexpected)}")
+
+                if current is None and label is None:
+                    raise TypeError("At least one of 'current' or 'label' must be provided")
+
+                if current is not None:
+                    current_progress = current
+                if label is not None:
+                    current_label = label
+
+                self.show_progress(current_progress, total, current_label)
 
             yield update_progress
         except Exception:

xulbux/data.py

@@ -24,11 +24,14 @@ class Data:
             except UnicodeDecodeError:
                 pass
             return {key: _base64.b64encode(data).decode("utf-8"), "encoding": "base64"}
-        raise TypeError("Unsupported data type")
+        raise TypeError(f"Unsupported data type '{type(data)}'")
 
     @staticmethod
     def deserialize_bytes(obj: dict[str, str]) -> bytes | bytearray:
-        """Converts a JSON-compatible bytes/bytearray format (dictionary) back to its original type."""
+        """Tries to converts a JSON-compatible bytes/bytearray format (dictionary) back to its original type.\n
+        --------------------------------------------------------------------------------------------------------
+        If the serialized object was created with `Data.serialize_bytes()`, it will work.
+        If it fails to decode the data, it will raise a `ValueError`."""
         for key in ("bytes", "bytearray"):
             if key in obj and "encoding" in obj:
                 if obj["encoding"] == "utf-8":
@@ -36,9 +39,9 @@ class Data:
                 elif obj["encoding"] == "base64":
                     data = _base64.b64decode(obj[key].encode("utf-8"))
                 else:
-                    raise ValueError("Unknown encoding method")
+                    raise ValueError(f"Unknown encoding method '{obj['encoding']}'")
                 return bytearray(data) if key == "bytearray" else data
-        raise ValueError("Invalid serialized data")
+        raise ValueError(f"Invalid serialized data: {obj}")
 
     @staticmethod
     def chars_count(data: DataStructure) -> int:
@@ -387,7 +390,7 @@ class Data:
 
         valid_entries = [(path_id, new_val) for path_id, new_val in update_values.items()]
         if not valid_entries:
-            raise ValueError(f"No valid update_values found in dictionary: {update_values}")
+            raise ValueError(f"No valid 'update_values' found in dictionary: {update_values}")
         for path_id, new_val in valid_entries:
             path = Data.__sep_path_id(path_id)
             data = update_nested(data, path, new_val)
@@ -581,7 +584,7 @@ class Data:
     @staticmethod
     def __sep_path_id(path_id: str) -> list[int]:
         if path_id.count(">") != 1:
-            raise ValueError(f"Invalid path ID: {path_id}")
+            raise ValueError(f"Invalid path ID '{path_id}'")
         id_part_len = int(path_id.split(">")[0])
         path_ids_str = path_id.split(">")[1]
         return [int(path_ids_str[i:i + id_part_len]) for i in range(0, len(path_ids_str), id_part_len)]

xulbux/format_codes.py

@@ -166,6 +166,7 @@ from typing import Optional, cast
 import ctypes as _ctypes
 import regex as _rx
 import sys as _sys
+import os as _os
 import re as _re
 
 
@@ -419,11 +420,16 @@ class FormatCodes:
         global _CONSOLE_ANSI_CONFIGURED
         if not _CONSOLE_ANSI_CONFIGURED:
             _sys.stdout.flush()
-            kernel32 = _ctypes.windll.kernel32
-            h = kernel32.GetStdHandle(-11)
-            mode = _ctypes.c_ulong()
-            kernel32.GetConsoleMode(h, _ctypes.byref(mode))
-            kernel32.SetConsoleMode(h, mode.value | 0x0004)
+            if _os.name == "nt":
+                try:
+                    # ENABLE VT100 MODE ON WINDOWS TO BE ABLE TO USE ANSI CODES
+                    kernel32 = _ctypes.windll.kernel32
+                    h = kernel32.GetStdHandle(-11)
+                    mode = _ctypes.c_ulong()
+                    kernel32.GetConsoleMode(h, _ctypes.byref(mode))
+                    kernel32.SetConsoleMode(h, mode.value | 0x0004)
+                except Exception:
+                    pass
             _CONSOLE_ANSI_CONFIGURED = True
 
     @staticmethod

xulbux/json.py

@@ -134,7 +134,7 @@ class Json:
                             current[idx] = [] if next_key.isdigit() else {}
                         current = current[idx]
                     else:
-                        raise TypeError(f"Cannot navigate through {type(current).__name__}")
+                        raise TypeError(f"Cannot navigate through '{type(current).__name__}'")
             return data_obj
 
         update = {}

xulbux/path.py

@@ -46,7 +46,7 @@ class Path:
         raise_error: bool = False,
         use_closest_match: bool = False,
     ) -> Optional[str]:
-        """Tries to locate and extend a relative path to an absolute path.\n
+        """Tries to resolve and extend a relative path to an absolute path.\n
         --------------------------------------------------------------------------------
         If the `rel_path` couldn't be located in predefined directories, it will be
         searched in the `search_in` directory/s. If the `rel_path` is still not found,

xulbux/system.py

@@ -1,3 +1,6 @@
+from .format_codes import FormatCodes
+from .console import Console
+
 from typing import Optional
 import subprocess as _subprocess
 import platform as _platform
@@ -67,11 +70,25 @@ class System:
             raise NotImplementedError(f"Restart not implemented for `{system}`")
 
     @staticmethod
-    def check_libs(lib_names: list[str], install_missing: bool = False, confirm_install: bool = True) -> Optional[list[str]]:
-        """Checks if the given list of libraries are installed. If not:
-        - If `install_missing` is false, the missing libraries will be returned as a list.
-        - If `install_missing` is true, the missing libraries will be installed.
-        - If `confirm_install` is true, the user will first be asked if they want to install the missing libraries."""
+    def check_libs(
+        lib_names: list[str],
+        install_missing: bool = False,
+        missing_libs_msgs: tuple[str, str] = (
+            "The following required libraries are missing:",
+            "Do you want to install them now?",
+        ),
+        confirm_install: bool = True,
+    ) -> Optional[list[str]]:
+        """Checks if the given list of libraries are installed and optionally installs missing libraries.\n
+        ------------------------------------------------------------------------------------------------------------
+        - `lib_names` -⠀a list of library names to check
+        - `install_missing` -⠀whether to directly missing libraries will be installed automatically using pip
+        - `missing_libs_msgs` -⠀two messages: the first one is displayed when missing libraries are found,
+          the second one is the confirmation message before installing missing libraries
+        - `confirm_install` -⠀whether the user will be asked for confirmation before installing missing libraries\n
+        ------------------------------------------------------------------------------------------------------------
+        If some libraries are missing or they could not be installed, their names will be returned as a list.
+        If all libraries are installed (or were installed successfully), `None` will be returned."""
         missing = []
         for lib in lib_names:
             try:
@@ -83,14 +100,22 @@ class System:
         elif not install_missing:
             return missing
         if confirm_install:
-            print("The following required libraries are missing:")
+            FormatCodes.print(f"[b]({missing_libs_msgs[0]})")
             for lib in missing:
-                print(f"- {lib}")
-            if input("Do you want to install them now (Y/n):  ").strip().lower() not in ("", "y", "yes"):
-                raise ImportError("Missing required libraries.")
+                FormatCodes.print(f" [dim](•) [i]{lib}[_i]")
+            print()
+            if not Console.confirm(missing_libs_msgs[1], end="\n"):
+                return missing
         try:
-            _subprocess.check_call([_sys.executable, "-m", "pip", "install"] + missing)
-            return None
+            for lib in missing:
+                try:
+                    _subprocess.check_call([_sys.executable, "-m", "pip", "install", lib])
+                    missing.remove(lib)
+                except _subprocess.CalledProcessError:
+                    pass
+            if len(missing) == 0:
+                return None
+            return missing
         except _subprocess.CalledProcessError:
             return missing
 

{xulbux-1.8.2.dist-info → xulbux-1.8.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xulbux
-Version: 1.8.2
+Version: 1.8.3
 Summary: A Python library which includes lots of helpful classes, types, and functions aiming to make common programming tasks simpler.
 Author-email: XulbuX <xulbux.real@gmail.com>
 Maintainer-email: XulbuX <xulbux.real@gmail.com>

xulbux-1.8.3.dist-info/RECORD

@@ -0,0 +1,20 @@
+xulbux/__init__.py,sha256=qGusxHHAnHPl-qVU9Rj1_WaOOlNCf_cRbyCUTF0wvBM,935
+xulbux/code.py,sha256=CLA3wh6mTvcXTlQgBeFaaLIBciHvXWqVM56rAtfO-JE,6102
+xulbux/color.py,sha256=tTNH30Wf2QNmyopKz4LADdels_TDzDMCptCtm76KkNo,50375
+xulbux/console.py,sha256=5Z7pHp6hNXSHpN5YVQnGWhw5USZR9AJ7xKjN98ssuLE,63288
+xulbux/data.py,sha256=U9T3lLEzas3A5V8Z0jPKnTy8WPhBmmF2bit8J4VkeB8,31219
+xulbux/env_path.py,sha256=HGOSffdIDubzczsXe6umyqotrzqhIW83QBkISAamXT8,4157
+xulbux/file.py,sha256=7pa0-WS_DpXq7HRB1fLS6Acd9CM-ozXPpNJvMqCW4fw,2624
+xulbux/format_codes.py,sha256=kT1vn8_aaOelzkhy2NYcCJPX_n_LHFRVaXbeDLA1Ir8,25020
+xulbux/json.py,sha256=Lo8vraQ3c-BoKFNYbXCdcJndh8tSsP4CMoYoEKarrmc,7450
+xulbux/path.py,sha256=_Xm4k5aOk2CGZ_ErMbnJPzonF03L8pq8nT8Wy44l8Qo,7674
+xulbux/regex.py,sha256=_BtMHRDNcD9zF4SL87dQuUVZcYGfZx9H5YNSDiEtzm8,8059
+xulbux/string.py,sha256=QaTo0TQ9m_2USNgQNaVw5ivQt-A1E-e5x8OpIB3xIlY,5561
+xulbux/system.py,sha256=CAV-mpTGEJ-0VWVRnTqWqhIsqS1HrIlM3LZOcTz9YBU,7793
+xulbux/base/consts.py,sha256=HwgI_Cr_U2QznezN17SP1j-gpyf3tsbu_KHMd8aKzyw,5918
+xulbux/cli/help.py,sha256=iKSEm1zEmng-BpfEa9xYvnIsTnJbZ_sRvMk4NtavwGY,4403
+xulbux-1.8.3.dist-info/METADATA,sha256=C67KKJKYblIESkTwM3Gyh9jlFtWQ4ToRUaY8wORdhAM,11042
+xulbux-1.8.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+xulbux-1.8.3.dist-info/entry_points.txt,sha256=aYh89GfiBOB8vw2VPgC6rhBinhnJoAL1kig-3lq_zkg,58
+xulbux-1.8.3.dist-info/top_level.txt,sha256=FkK4EZajwfP36fnlrPaR98OrEvZpvdEOdW1T5zTj6og,7
+xulbux-1.8.3.dist-info/RECORD,,

xulbux-1.8.2.dist-info/RECORD

@@ -1,20 +0,0 @@
-xulbux/__init__.py,sha256=NnqeQz_8_t4bkghp5qN3vQEm_Dff6AJBghJsTUVUaks,935
-xulbux/code.py,sha256=CLA3wh6mTvcXTlQgBeFaaLIBciHvXWqVM56rAtfO-JE,6102
-xulbux/color.py,sha256=tTNH30Wf2QNmyopKz4LADdels_TDzDMCptCtm76KkNo,50375
-xulbux/console.py,sha256=b9B1lQzAl5OEhmIlCbTyCyu_WRZwMVOuI-v1GfGtxzo,57308
-xulbux/data.py,sha256=hB9JxrSC7_6kelJ_TwOaapNrlig-jiyNZS3YoiJX8F8,30884
-xulbux/env_path.py,sha256=HGOSffdIDubzczsXe6umyqotrzqhIW83QBkISAamXT8,4157
-xulbux/file.py,sha256=7pa0-WS_DpXq7HRB1fLS6Acd9CM-ozXPpNJvMqCW4fw,2624
-xulbux/format_codes.py,sha256=UwJOH3JJebylYd-MclDvKOG72fhuku63JzZU_eUzMtA,24764
-xulbux/json.py,sha256=Ei5FdCjfM0FrrAEBmuuTcexl7mUY4eirXr-QPct2OS0,7448
-xulbux/path.py,sha256=lLAEVZrW0TAwCewlONFVQcQ_8tVn9LTJZVOZpeGvE5s,7673
-xulbux/regex.py,sha256=_BtMHRDNcD9zF4SL87dQuUVZcYGfZx9H5YNSDiEtzm8,8059
-xulbux/string.py,sha256=QaTo0TQ9m_2USNgQNaVw5ivQt-A1E-e5x8OpIB3xIlY,5561
-xulbux/system.py,sha256=uCjQhqlfOoLkEBdjWn5cLCEnaI4Ac3o9cwRKev07eWI,6612
-xulbux/base/consts.py,sha256=HwgI_Cr_U2QznezN17SP1j-gpyf3tsbu_KHMd8aKzyw,5918
-xulbux/cli/help.py,sha256=wlDTjFhyWQucywMGDmrYIjYn1TV__TwMlYzeSCkQ__U,4403
-xulbux-1.8.2.dist-info/METADATA,sha256=h7DU1OI_NtZNXoq6pFPP1dQhYnDlcbdEbaSsgYajXdc,11042
-xulbux-1.8.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-xulbux-1.8.2.dist-info/entry_points.txt,sha256=aYh89GfiBOB8vw2VPgC6rhBinhnJoAL1kig-3lq_zkg,58
-xulbux-1.8.2.dist-info/top_level.txt,sha256=FkK4EZajwfP36fnlrPaR98OrEvZpvdEOdW1T5zTj6og,7
-xulbux-1.8.2.dist-info/RECORD,,