xulbux 1.6.9__py3-none-any.whl → 1.7.1__py3-none-any.whl

xulbux/xx_console.py

@@ -8,10 +8,10 @@ For more detailed information about formatting codes, see the the `xx_format_cod
 from ._consts_ import COLOR, CHARS
 from .xx_format_codes import FormatCodes, _COMPILED
 from .xx_string import String
-from .xx_color import Color, rgba, hexa
+from .xx_color import Color, Rgba, Hexa
 
 from prompt_toolkit.key_binding.key_bindings import KeyBindings
-from typing import Optional, Any
+from typing import Optional, Literal, Mapping, Any, cast
 import prompt_toolkit as _prompt_toolkit
 import pyperclip as _pyperclip
 import keyboard as _keyboard
@@ -48,25 +48,31 @@ class _ConsoleUser:
 
 
 class ArgResult:
-    """Exists: if the argument was found or not\n
-    Value: the value from behind the found argument"""
+    """Represents the result of a parsed command-line argument and contains the following attributes:
+    - `exists` -⠀if the argument was found or not
+    - `value` -⠀the value given with the found argument\n
+    --------------------------------------------------------------------------------------------------------
+    When the `ArgResult` instance is accessed as a boolean it will correspond to the `exists` attribute."""
 
     def __init__(self, exists: bool, value: Any):
-        self.exists = exists
-        self.value = value
+        self.exists: bool = exists
+        self.value: Any = value
 
     def __bool__(self):
         return self.exists
 
 
 class Args:
-    """Stores found command arguments under their aliases with their results."""
+    """Container for parsed command-line arguments, allowing attribute-style access.
+    For example, if an argument `foo` was parsed, it can be accessed via `args.foo`.
+    Each such attribute (e.g. `args.foo`) is an instance of `ArgResult`."""
 
-    def __init__(self, **kwargs):
-        for key, value in kwargs.items():
-            if not key.isidentifier():
-                raise TypeError(f"Argument alias '{key}' is invalid. It must be a valid Python variable name.")
-            setattr(self, key, ArgResult(**value))
+    def __init__(self, **kwargs: dict[str, Any]):
+        for alias_name, data_dict in kwargs.items():
+            if not alias_name.isidentifier():
+                raise TypeError(f"Argument alias '{alias_name}' is invalid. It must be a valid Python variable name.")
+            arg_result_instance = ArgResult(exists=data_dict["exists"], value=data_dict["value"])
+            setattr(self, alias_name, arg_result_instance)
 
     def __len__(self):
         return len(vars(self))
@@ -74,6 +80,9 @@ class Args:
     def __contains__(self, key):
         return hasattr(self, key)
 
+    def __getattr__(self, name: str) -> ArgResult:
+        raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+
     def __getitem__(self, key):
         if isinstance(key, int):
             return list(self.__iter__())[key]
@@ -103,19 +112,18 @@ class Args:
 
 class Console:
 
-    w: int = _ConsoleWidth()
+    w: int = _ConsoleWidth()  # type: ignore[assignment]
     """The width of the console in characters."""
-    h: int = _ConsoleHeight()
+    h: int = _ConsoleHeight()  # type: ignore[assignment]
     """The height of the console in lines."""
-    wh: tuple[int, int] = _ConsoleSize()
-    """A tuple with the width and height of
-    the console in characters and lines."""
-    usr: str = _ConsoleUser()
+    wh: tuple[int, int] = _ConsoleSize()  # type: ignore[assignment]
+    """A tuple with the width and height of the console in characters and lines."""
+    usr: str = _ConsoleUser()  # type: ignore[assignment]
     """The name of the current user."""
 
     @staticmethod
     def get_args(
-        find_args: dict[str, list[str] | tuple[str, ...] | dict[str, list[str] | tuple[str, ...] | Any]],
+        find_args: Mapping[str, list[str] | tuple[str, ...] | dict[str, list[str] | tuple[str, ...] | Any]],
         allow_spaces: bool = False
     ) -> Args:
         """Will search for the specified arguments in the command line
@@ -249,8 +257,8 @@ class Console:
         format_linebreaks: bool = True,
         start: str = "",
         end: str = "\n",
-        title_bg_color: hexa | rgba = None,
-        default_color: hexa | rgba = None,
+        title_bg_color: Optional[Rgba | Hexa] = None,
+        default_color: Optional[Rgba | Hexa] = None,
         _console_tabsize: int = 8,
     ) -> None:
         """Will print a formatted log message:
@@ -267,12 +275,20 @@ class Console:
         information about formatting codes, see `xx_format_codes` module documentation."""
         title = "" if title is None else title.strip().upper()
         title_len, tab_len = len(title) + 4, _console_tabsize - ((len(title) + 4) % _console_tabsize)
-        title_color = "_color" if not title_bg_color else Color.text_color_for_on_bg(title_bg_color)
+        if title_bg_color is not None and Color.is_valid(title_bg_color):
+            title_bg_color = Color.to_hexa(title_bg_color)
+            title_color = Color.text_color_for_on_bg(title_bg_color)
+        else:
+            title_color = "_color" if title_bg_color is None else "#000"
         if format_linebreaks:
             clean_prompt, removals = FormatCodes.remove_formatting(str(prompt), get_removals=True, _ignore_linebreaks=True)
             prompt_lst = (String.split_count(l, Console.w - (title_len + tab_len)) for l in str(clean_prompt).splitlines())
-            prompt_lst = (item for lst in prompt_lst for item in (lst if isinstance(lst, list) else [lst]))
-            prompt = f"\n{' ' * title_len}\t".join(Console.__add_back_removed_parts(list(prompt_lst), removals))
+            prompt_lst = (
+                item for lst in prompt_lst for item in ([""] if lst == [] else (lst if isinstance(lst, list) else [lst]))
+            )
+            prompt = f"\n{' ' * title_len}\t".join(
+                Console.__add_back_removed_parts(list(prompt_lst), cast(tuple[tuple[int, str], ...], removals))
+            )
         else:
             prompt = str(prompt)
         if title == "":
@@ -328,8 +344,8 @@ class Console:
         format_linebreaks: bool = True,
         start: str = "",
         end: str = "\n",
-        title_bg_color: hexa | rgba = COLOR.yellow,
-        default_color: hexa | rgba = COLOR.text,
+        title_bg_color: Rgba | Hexa = COLOR.yellow,
+        default_color: Rgba | Hexa = COLOR.text,
         pause: bool = False,
         exit: bool = False,
     ) -> None:
@@ -346,8 +362,8 @@ class Console:
         format_linebreaks: bool = True,
         start: str = "",
         end: str = "\n",
-        title_bg_color: hexa | rgba = COLOR.blue,
-        default_color: hexa | rgba = COLOR.text,
+        title_bg_color: Rgba | Hexa = COLOR.blue,
+        default_color: Rgba | Hexa = COLOR.text,
         pause: bool = False,
         exit: bool = False,
     ) -> None:
@@ -362,8 +378,8 @@ class Console:
         format_linebreaks: bool = True,
         start: str = "",
         end: str = "\n",
-        title_bg_color: hexa | rgba = COLOR.teal,
-        default_color: hexa | rgba = COLOR.text,
+        title_bg_color: Rgba | Hexa = COLOR.teal,
+        default_color: Rgba | Hexa = COLOR.text,
         pause: bool = False,
         exit: bool = False,
     ) -> None:
@@ -378,8 +394,8 @@ class Console:
         format_linebreaks: bool = True,
         start: str = "",
         end: str = "\n",
-        title_bg_color: hexa | rgba = COLOR.orange,
-        default_color: hexa | rgba = COLOR.text,
+        title_bg_color: Rgba | Hexa = COLOR.orange,
+        default_color: Rgba | Hexa = COLOR.text,
         pause: bool = False,
         exit: bool = False,
     ) -> None:
@@ -394,8 +410,8 @@ class Console:
         format_linebreaks: bool = True,
         start: str = "",
         end: str = "\n",
-        title_bg_color: hexa | rgba = COLOR.red,
-        default_color: hexa | rgba = COLOR.text,
+        title_bg_color: Rgba | Hexa = COLOR.red,
+        default_color: Rgba | Hexa = COLOR.text,
         pause: bool = False,
         exit: bool = True,
         reset_ansi=True,
@@ -411,8 +427,8 @@ class Console:
         format_linebreaks: bool = True,
         start: str = "",
         end: str = "\n",
-        title_bg_color: hexa | rgba = COLOR.magenta,
-        default_color: hexa | rgba = COLOR.text,
+        title_bg_color: Rgba | Hexa = COLOR.magenta,
+        default_color: Rgba | Hexa = COLOR.text,
         pause: bool = False,
         exit: bool = True,
         reset_ansi=True,
@@ -423,18 +439,18 @@ class Console:
         Console.pause_exit(pause, exit, reset_ansi=reset_ansi)
 
     @staticmethod
-    def log_box(
+    def log_box_filled(
         *values: object,
         start: str = "",
         end: str = "\n",
-        box_bg_color: str | hexa | rgba = "green",
-        default_color: hexa | rgba = "#000",
+        box_bg_color: Rgba | Hexa = "green",
+        default_color: Rgba | Hexa = "#000",
         w_padding: int = 2,
         w_full: bool = False,
     ) -> None:
-        """Will print a box, containing a formatted log message:
+        """Will print a box with a colored background, containing a formatted log message:
         - `*values` -⠀the box content (each value is on a new line)
-        - `start` -⠀something to print before the log box is printed
+        - `start` -⠀something to print before the log box is printed (e.g. `\\n`)
         - `end` -⠀something to print after the log box is printed (e.g. `\\n`)
         - `box_bg_color` -⠀the background color of the box
         - `default_color` -⠀the default text color of the `*values`
@@ -443,30 +459,107 @@ class Console:
         -----------------------------------------------------------------------------------
         The box content can be formatted with special formatting codes. For more detailed
         information about formatting codes, see `xx_format_codes` module documentation."""
-        lines = [line.rstrip() for val in values for line in val.splitlines()]
-        unfmt_lines = [FormatCodes.remove_formatting(line) for line in lines]
-        max_line_len = max(len(line) for line in unfmt_lines)
+        lines, unfmt_lines, max_line_len = Console.__prepare_log_box(values, default_color)
         pad_w_full = (Console.w - (max_line_len + (2 * w_padding))) if w_full else 0
+        if box_bg_color is not None and Color.is_valid(box_bg_color):
+            box_bg_color = Color.to_hexa(box_bg_color)
         lines = [
             f"[bg:{box_bg_color}]{' ' * w_padding}{line}" + " " *
-            ((w_padding + max_line_len - len(unfmt)) + pad_w_full) + "[_bg]" for line, unfmt in zip(lines, unfmt_lines)
+            ((w_padding + max_line_len - len(unfmt)) + pad_w_full) + "[*]" for line, unfmt in zip(lines, unfmt_lines)
         ]
         pady = " " * (Console.w if w_full else max_line_len + (2 * w_padding))
         FormatCodes.print(
-            f"{start}[bg:{box_bg_color}]{pady}[_bg]\n"
+            f"{start}[bg:{box_bg_color}]{pady}[*]\n"
             + _COMPILED["formatting"].sub(lambda m: f"{m.group(0)}[bg:{box_bg_color}]", "\n".join(lines))
-            + f"\n[bg:{box_bg_color}]{pady}[_bg]",
+            + f"\n[bg:{box_bg_color}]{pady}[_]",
+            default_color=default_color or "#000",
+            sep="\n",
+            end=end,
+        )
+
+    @staticmethod
+    def log_box_bordered(
+        *values: object,
+        start: str = "",
+        end: str = "\n",
+        border_type: Literal["standard", "rounded", "strong", "double"] = "rounded",
+        border_style: str | Rgba | Hexa = f"dim|{COLOR.gray}",
+        default_color: Optional[Rgba | Hexa] = None,
+        w_padding: int = 1,
+        w_full: bool = False,
+        _border_chars: Optional[tuple[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)
+        - `start` -⠀something to print before the log box is printed (e.g. `\\n`)
+        - `end` -⠀something to print after the log box is printed (e.g. `\\n`)
+        - `border_type` -⠀one of the predefined border character sets
+        - `default_color` -⠀the default text color of the `*values`
+        - `w_padding` -⠀the horizontal padding (in chars) to the box content
+        - `w_full` -⠀whether to make the box be the full console width or not
+        - `_border_chars` -⠀define your own border characters set (overwrites `border_type`)\n
+        ---------------------------------------------------------------------------------------
+        The box content can be formatted with special formatting codes. For more detailed
+        information about formatting codes, see `xx_format_codes` module documentation.\n
+        ---------------------------------------------------------------------------------------
+        The `border_type` can be one of the following:
+        - `"standard" = ('┌', '─', '┐', '│', '┘', '─', '└', '│')`
+        - `"rounded" = ('╭', '─', '╮', '│', '╯', '─', '╰', '│')`
+        - `"strong" = ('┏', '━', '┓', '┃', '┛', '━', '┗', '┃')`
+        - `"double" = ('╔', '═', '╗', '║', '╝', '═', '╚', '║')`\n
+        The order of the characters is always:
+        1. top-left corner
+        2. top border
+        3. top-right corner
+        4. right border
+        5. bottom-right corner
+        6. bottom border
+        7. bottom-left corner
+        8. left border"""
+        borders = {
+            "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)
+        print(unfmt_lines)
+        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)
+        border_l = f"[{border_style}]{border_chars[7]}[*]"
+        border_r = f"[{border_style}]{border_chars[3]}[_]"
+        lines = [
+            f"{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"[{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"[{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,
             sep="\n",
             end=end,
         )
 
+    @staticmethod
+    def __prepare_log_box(
+        values: tuple[object, ...],
+        default_color: Optional[Rgba | Hexa] = None,
+    ) -> 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()]
+        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
+
     @staticmethod
     def confirm(
         prompt: object = "Do you want to continue?",
         start="",
         end="\n",
-        default_color: hexa | rgba = COLOR.cyan,
+        default_color: Rgba | Hexa = COLOR.cyan,
         default_is_yes: bool = True,
     ) -> bool:
         """Ask a yes/no question.\n
@@ -488,9 +581,9 @@ class Console:
         prompt: object = "",
         start="",
         end="\n",
-        default_color: hexa | rgba = COLOR.cyan,
+        default_color: Rgba | Hexa = COLOR.cyan,
         show_keybindings=True,
-        input_prefix=" ⤷ ",
+        input_prefix=" ⮡ ",
         reset_ansi=True,
     ) -> str:
         """An input where users can input (and paste) text over multiple lines.\n
@@ -511,7 +604,7 @@ class Console:
         def _(event):
             event.app.exit(result=event.app.current_buffer.document.text)
 
-        FormatCodes.print(start + prompt, default_color=default_color)
+        FormatCodes.print(start + str(prompt), default_color=default_color)
         if show_keybindings:
             FormatCodes.print("[dim][[b](CTRL+D)[dim] : end of input][_dim]")
         input_string = _prompt_toolkit.prompt(input_prefix, multiline=True, wrap_lines=True, key_bindings=kb)
@@ -523,11 +616,11 @@ class Console:
         prompt: object = "",
         start="",
         end="\n",
-        default_color: hexa | rgba = COLOR.cyan,
-        allowed_chars: str = CHARS.all,
-        min_len: int = None,
-        max_len: int = None,
-        mask_char: str = None,
+        default_color: Rgba | Hexa = COLOR.cyan,
+        allowed_chars: str = CHARS.all,  # type: ignore[assignment]
+        min_len: Optional[int] = None,
+        max_len: Optional[int] = None,
+        mask_char: Optional[str] = None,
         reset_ansi: bool = True,
     ) -> Optional[str]:
         """Acts like a standard Python `input()` with the advantage, that you can specify:
@@ -538,7 +631,7 @@ class Console:
         ---------------------------------------------------------------------------------------
         The input can be formatted with special formatting codes. For more detailed
         information about formatting codes, see the `xx_format_codes` module documentation."""
-        FormatCodes.print(start + prompt, default_color=default_color, end="")
+        FormatCodes.print(start + str(prompt), default_color=default_color, end="")
         result = ""
         select_all = False
         last_line_count = 1
@@ -594,7 +687,8 @@ class Console:
 
         def handle_character_input():
             nonlocal result
-            if (allowed_chars == CHARS.all or event.name in allowed_chars) and (max_len is None or len(result) < max_len):
+            if event.name is not None and ((allowed_chars == CHARS.all or event.name in allowed_chars) and
+                                           (max_len is None or len(result) < max_len)):
                 result += event.name
                 update_display(Console.w)
 
@@ -615,7 +709,7 @@ class Console:
                     return None
                 elif event.name == "space":
                     handle_character_input()
-                elif len(event.name) == 1:
+                elif event.name is not None and len(event.name) == 1:
                     handle_character_input()
                 else:
                     select_all = False
@@ -626,12 +720,22 @@ class Console:
         prompt: object = "Password: ",
         start="",
         end="\n",
-        default_color: hexa | rgba = COLOR.cyan,
+        default_color: Rgba | Hexa = COLOR.cyan,
         allowed_chars: str = CHARS.standard_ascii,
-        min_len: int = None,
-        max_len: int = None,
+        min_len: Optional[int] = None,
+        max_len: Optional[int] = None,
         reset_ansi: bool = True,
-    ) -> str:
+    ) -> Optional[str]:
         """Password input (preset for `Console.restricted_input()`)
         that always masks the entered characters with asterisks."""
-        return Console.restricted_input(prompt, start, end, default_color, allowed_chars, min_len, max_len, "*", reset_ansi)
+        return Console.restricted_input(
+            prompt=prompt,
+            start=start,
+            end=end,
+            default_color=default_color,
+            allowed_chars=allowed_chars,
+            min_len=min_len,
+            max_len=max_len,
+            mask_char="*",
+            reset_ansi=reset_ansi,
+        )

xulbux/xx_data.py

@@ -166,7 +166,7 @@ class Data:
 
         def process_string(s: str) -> Optional[str]:
             if comment_end:
-                match = pattern.match(s)
+                match = pattern.match(s)  # type: ignore[unbound]
                 if match:
                     start, end = match.group(1).strip(), match.group(2).strip()
                     return f"{start}{comment_sep if start and end else ''}{end}" or None
@@ -223,7 +223,7 @@ class Data:
                 return True
             if type(d1) is not type(d2):
                 return False
-            if isinstance(d1, dict):
+            if isinstance(d1, dict) and isinstance(d2, dict):
                 if set(d1.keys()) != set(d2.keys()):
                     return False
                 return all(compare(d1[key], d2[key], ignore_paths, current_path + [key]) for key in d1)
@@ -251,7 +251,7 @@ class Data:
         comment_start: str = ">>",
         comment_end: str = "<<",
         ignore_not_found: bool = False,
-    ) -> str | list[str]:
+    ) -> Optional[str | list[Optional[str]]]:
         """Generates a unique ID based on the path to a specific value within a nested data structure.\n
         -------------------------------------------------------------------------------------------------
         The `data` parameter is the list, tuple, or dictionary, which the id should be generated for.\n
@@ -355,12 +355,12 @@ class Data:
         return get_nested(data, Data.__sep_path_id(path_id), get_key)
 
     @staticmethod
-    def set_value_by_path_id(data: DataStructure, update_values: dict[str, Any]) -> list | tuple | dict:
+    def set_value_by_path_id(data: DataStructure, update_values: dict[str, Any]) -> DataStructure:
         """Updates the value/s from `update_values` in the `data`.\n
         --------------------------------------------------------------------------------
         Input a list, tuple or dict as `data`, along with `update_values`, which is a
         dictionary where keys are path IDs and values are the new values to insert:
-           { "1>": "new value", "path_id2": ["new value 1", "new value 2"], ... }
+           { "1>012": "new value", "1>31": ["new value 1", "new value 2"], ... }
         The path IDs should have been created using `Data.get_path_id()`.\n
         --------------------------------------------------------------------------------
         The value from path ID will be changed to the new value, as long as the
@@ -413,7 +413,8 @@ class Data:
         - `2` keeps everything collapsed (all on one line)\n
         ------------------------------------------------------------------------------
         If `as_json` is set to `True`, the output will be in valid JSON format."""
-        if syntax_hl := _syntax_highlighting not in (None, False):
+        _syntax_hl = {}
+        if do_syntax_hl := _syntax_highlighting not in (None, False):
             if _syntax_highlighting is True:
                 _syntax_highlighting = {}
             elif not isinstance(_syntax_highlighting, dict):
@@ -426,62 +427,62 @@ class Data:
                 "punctuation": (f"[{COLOR.darkgray}]", "[_c]"),
             }
             _syntax_hl.update({
-                k: [f"[{v}]", "[_]"] if k in _syntax_hl and v not in ("", None) else ["", ""]
+                k: (f"[{v}]", "[_]") if k in _syntax_hl and v not in ("", None) else ("", "")
                 for k, v in _syntax_highlighting.items()
             })
             sep = f"{_syntax_hl['punctuation'][0]}{sep}{_syntax_hl['punctuation'][1]}"
         punct_map = {"(": ("/(", "("), **{char: char for char in "'\":)[]{}"}}
         punct = {
-            k: ((f"{_syntax_hl['punctuation'][0]}{v[0]}{_syntax_hl['punctuation'][1]}" if syntax_hl else v[1])
+            k: ((f"{_syntax_hl['punctuation'][0]}{v[0]}{_syntax_hl['punctuation'][1]}" if do_syntax_hl else v[1])
                 if isinstance(v, (list, tuple)) else
-                (f"{_syntax_hl['punctuation'][0]}{v}{_syntax_hl['punctuation'][1]}" if syntax_hl else v))
+                (f"{_syntax_hl['punctuation'][0]}{v}{_syntax_hl['punctuation'][1]}" if do_syntax_hl else v))
             for k, v in punct_map.items()
         }
 
-        def format_value(value: Any, current_indent: int = None) -> str:
+        def format_value(value: Any, current_indent: Optional[int] = None) -> str:
             if current_indent is not None and isinstance(value, dict):
                 return format_dict(value, current_indent + indent)
             elif current_indent is not None and hasattr(value, "__dict__"):
                 return format_dict(value.__dict__, current_indent + indent)
             elif current_indent is not None and isinstance(value, IndexIterable):
                 return format_sequence(value, current_indent + indent)
-            elif isinstance(value, (bytes, bytearray)):
+            elif current_indent is not None and isinstance(value, (bytes, bytearray)):
                 obj_dict = Data.serialize_bytes(value)
                 return (
                     format_dict(obj_dict, current_indent + indent) if as_json else (
                         f"{_syntax_hl['type'][0]}{(k := next(iter(obj_dict)))}{_syntax_hl['type'][1]}"
-                        + format_sequence((obj_dict[k], obj_dict["encoding"]), current_indent + indent) if syntax_hl else
+                        + format_sequence((obj_dict[k], obj_dict["encoding"]), current_indent + indent) if do_syntax_hl else
                         (k := next(iter(obj_dict)))
                         + format_sequence((obj_dict[k], obj_dict["encoding"]), current_indent + indent)
                     )
                 )
             elif isinstance(value, bool):
                 val = str(value).lower() if as_json else str(value)
-                return f"{_syntax_hl['literal'][0]}{val}{_syntax_hl['literal'][1]}" if syntax_hl else val
+                return f"{_syntax_hl['literal'][0]}{val}{_syntax_hl['literal'][1]}" if do_syntax_hl else val
             elif isinstance(value, (int, float)):
                 val = "null" if as_json and (_math.isinf(value) or _math.isnan(value)) else str(value)
-                return f"{_syntax_hl['number'][0]}{val}{_syntax_hl['number'][1]}" if syntax_hl else val
-            elif isinstance(value, complex):
+                return f"{_syntax_hl['number'][0]}{val}{_syntax_hl['number'][1]}" if do_syntax_hl else val
+            elif current_indent is not None and isinstance(value, complex):
                 return (
                     format_value(str(value).strip("()")) if as_json else (
                         f"{_syntax_hl['type'][0]}complex{_syntax_hl['type'][1]}"
                         + format_sequence((value.real, value.imag), current_indent + indent)
-                        if syntax_hl else f"complex{format_sequence((value.real, value.imag), current_indent + indent)}"
+                        if do_syntax_hl else f"complex{format_sequence((value.real, value.imag), current_indent + indent)}"
                     )
                 )
             elif value is None:
                 val = "null" if as_json else "None"
-                return f"{_syntax_hl['literal'][0]}{val}{_syntax_hl['literal'][1]}" if syntax_hl else val
+                return f"{_syntax_hl['literal'][0]}{val}{_syntax_hl['literal'][1]}" if do_syntax_hl else val
             else:
                 return ((
                     punct['"'] + _syntax_hl["str"][0] + String.escape(str(value), '"') + _syntax_hl["str"][1]
-                    + punct['"'] if syntax_hl else punct['"'] + String.escape(str(value), '"') + punct['"']
+                    + punct['"'] if do_syntax_hl else punct['"'] + String.escape(str(value), '"') + punct['"']
                 ) if as_json else (
                     punct["'"] + _syntax_hl["str"][0] + String.escape(str(value), "'") + _syntax_hl["str"][1]
-                    + punct["'"] if syntax_hl else punct["'"] + String.escape(str(value), "'") + punct["'"]
+                    + punct["'"] if do_syntax_hl else punct["'"] + String.escape(str(value), "'") + punct["'"]
                 ))
 
-        def should_expand(seq: list | tuple | dict) -> bool:
+        def should_expand(seq: IndexIterable) -> bool:
             if compactness == 0:
                 return True
             if compactness == 2:
@@ -500,7 +501,7 @@ class Data:
                     + sep.join(f"{format_value(k)}{punct[':']} {format_value(v, current_indent)}"
                                for k, v in d.items()) + punct["}"]
                 )
-            if not should_expand(d.values()):
+            if not should_expand(list(d.values())):
                 return (
                     punct["{"]
                     + sep.join(f"{format_value(k)}{punct[':']} {format_value(v, current_indent)}"

xulbux/xx_env_path.py

@@ -1,5 +1,6 @@
 from .xx_path import Path
 
+from typing import Optional
 import sys as _sys
 import os as _os
 
@@ -13,7 +14,7 @@ class EnvPath:
         return paths.split(_os.pathsep) if as_list else paths
 
     @staticmethod
-    def has_path(path: str = None, cwd: bool = False, base_dir: bool = False) -> bool:
+    def has_path(path: Optional[str] = None, cwd: bool = False, base_dir: bool = False) -> bool:
         """Check if a path is present in the PATH environment variable."""
         if cwd:
             path = _os.getcwd()
@@ -25,21 +26,21 @@ class EnvPath:
         return _os.path.normpath(path) in [_os.path.normpath(p) for p in paths]
 
     @staticmethod
-    def add_path(path: str = None, cwd: bool = False, base_dir: bool = False) -> None:
+    def add_path(path: Optional[str] = None, cwd: bool = False, base_dir: bool = False) -> None:
         """Add a path to the PATH environment variable."""
         path = EnvPath.__get(path, cwd, base_dir)
         if not EnvPath.has_path(path):
             EnvPath.__persistent(path, add=True)
 
     @staticmethod
-    def remove_path(path: str = None, cwd: bool = False, base_dir: bool = False) -> None:
+    def remove_path(path: Optional[str] = None, cwd: bool = False, base_dir: bool = False) -> None:
         """Remove a path from the PATH environment variable."""
         path = EnvPath.__get(path, cwd, base_dir)
         if EnvPath.has_path(path):
             EnvPath.__persistent(path, remove=True)
 
     @staticmethod
-    def __get(path: str = None, cwd: bool = False, base_dir: bool = False) -> list:
+    def __get(path: Optional[str] = None, cwd: bool = False, base_dir: bool = False) -> str:
         """Get and/or normalize the paths.\n
         ------------------------------------------------------------------------------------
         Raise an error if no path is provided and neither `cwd` or `base_dir` is `True`."""
@@ -56,7 +57,7 @@ class EnvPath:
         """Add or remove a path from PATH persistently across sessions as well as the current session."""
         if add == remove:
             raise ValueError("Either add or remove must be True, but not both.")
-        current_paths = EnvPath.paths(as_list=True)
+        current_paths = list(EnvPath.paths(as_list=True))
         path = _os.path.normpath(path)
         if remove:
             current_paths = [p for p in current_paths if _os.path.normpath(p) != _os.path.normpath(path)]

xulbux/xx_file.py

@@ -19,8 +19,8 @@ class File:
         """Rename the extension of a file.\n
         --------------------------------------------------------------------------
         If `full_extension` is true, everything after the first dot in the
-        filename will be treated as the extension to replace. Otherwise, only the
-        part after the last dot is replaced.\n
+        filename will be treated as the extension to replace (e.g. `.tar.gz`).
+        Otherwise, only the part after the last dot is replaced (e.g. `.gz`).\n
         If the `camel_case_filename` parameter is true, the filename will be made
         CamelCase in addition to changing the files extension."""
         normalized_file = _os.path.normpath(file)