xulbux 1.6.8__py3-none-any.whl → 1.7.0__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
+from typing import Optional, Any
 import prompt_toolkit as _prompt_toolkit
 import pyperclip as _pyperclip
 import keyboard as _keyboard
@@ -22,106 +22,142 @@ import sys as _sys
 import os as _os
 
 
-# YAPF: disable
 class _ConsoleWidth:
+
     def __get__(self, obj, owner=None):
         return _os.get_terminal_size().columns
 
+
 class _ConsoleHeight:
+
     def __get__(self, obj, owner=None):
         return _os.get_terminal_size().lines
 
+
 class _ConsoleSize:
+
     def __get__(self, obj, owner=None):
         size = _os.get_terminal_size()
         return (size.columns, size.lines)
 
+
 class _ConsoleUser:
+
     def __get__(self, obj, owner=None):
         return _os.getenv("USER") or _os.getenv("USERNAME") or _getpass.getuser()
 
+
 class ArgResult:
     """Exists: if the argument was found or not\n
     Value: the value from behind the found argument"""
-    def __init__(self, exists: bool, value: any):
+
+    def __init__(self, exists: bool, value: Any):
         self.exists = exists
         self.value = value
+
     def __bool__(self):
         return self.exists
 
+
 class Args:
     """Stores found command arguments under their aliases with their results."""
+
     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 __len__(self):
         return len(vars(self))
+
     def __contains__(self, key):
         return hasattr(self, key)
+
     def __getitem__(self, key):
         if isinstance(key, int):
             return list(self.__iter__())[key]
         return getattr(self, key)
+
     def __iter__(self):
         for key, value in vars(self).items():
             yield (key, {"exists": value.exists, "value": value.value})
-    def dict(self) -> dict[str, dict[str, any]]:
+
+    def dict(self) -> dict[str, dict[str, Any]]:
         """Returns the arguments as a dictionary."""
         return {k: {"exists": v.exists, "value": v.value} for k, v in vars(self).items()}
+
     def keys(self):
         """Returns the argument aliases as `dict_keys([...])`."""
         return vars(self).keys()
+
     def values(self):
         """Returns the argument results as `dict_values([...])`."""
         return vars(self).values()
+
     def items(self):
-        """Returns the argument aliases and results as `dict_items([...])`."""
-        return vars(self).items()
-# YAPF: enable
+        """Yields tuples of `(alias, {'exists': bool, 'value': Any})`."""
+        for key, value in self.__iter__():
+            yield (key, value)
 
 
 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()
+    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()
+    usr: str = _ConsoleUser()  # type: ignore[assignment]
     """The name of the current user."""
 
     @staticmethod
-    def get_args(find_args: dict[str, list[str] | tuple[str, ...]], allow_spaces: bool = False) -> Args:
+    def get_args(
+        find_args: dict[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
         arguments and return the results as a special `Args` object.\n
         ----------------------------------------------------------------
-        The `find_args` dictionary should have the following structure:
+        The `find_args` dictionary can have the following structures for each alias:
+        1. Simple list/tuple of flags (when no default value is needed):
+           ```python
+           "alias_name": ["-f", "--flag"]
+           ```
+        2. Dictionary with 'flags' and optional 'default':
+           ```python
+           "alias_name": {
+               "flags": ["-f", "--flag"],
+               "default": "some_value"  # Optional
+           }
+           ```
+        Example `find_args`:
         ```python
         find_args={
-            "arg1_alias": ["-a1", "--arg1", "--argument-1"],
-            "arg2_alias": ("-a2", "--arg2", "--argument-2"),
-            ...
+            "arg1": { # With default
+                "flags": ["-a1", "--arg1"],
+                "default": "default_val"
+            },
+            "arg2": ("-a2", "--arg2"), # Without default (original format)
+            "arg3": ["-a3"],          # Without default (list format)
+            "arg4": { # Flag with default True
+                "flags": ["-f"],
+                "default": True
+            }
         }
         ```
-        And if the script is called via the command line:\n
-        `python script.py -a1 "argument value" --arg2`\n
-        ...it would return the following `Args` object:
-        ```python
-        Args(
-            arg1_alias=ArgResult(exists=True, value="argument value"),
-            arg2_alias=ArgResult(exists=True, value=None),
-            ...
-        )
-        ```
-        ...which can be accessed like this:\n
-        - `Args.<arg_alias>.exists` is `True` if any of the specified
-            args were found and `False` if not
-        - `Args.<arg_alias>.value` the value from behind the found arg,
-            `None` if no value was found\n
+        If the script is called via the command line:\n
+        `python script.py -a1 "value1" --arg2 -f`\n
+        ...it would return an `Args` object where:
+        - `args.arg1.exists` is `True`, `args.arg1.value` is `"value1"`
+        - `args.arg2.exists` is `True`, `args.arg2.value` is `True` (flag present without value)
+        - `args.arg3.exists` is `False`, `args.arg3.value` is `None` (not present, no default)
+        - `args.arg4.exists` is `True`, `args.arg4.value` is `True` (flag present, overrides default)
+        - If an arg defined in `find_args` is *not* present in the command line:
+            - `exists` will be `False`
+            - `value` will be the specified `default` value, or `None` if no default was specified.\n
         ----------------------------------------------------------------
         Normally if `allow_spaces` is false, it will take a space as
         the end of an args value. If it is true, it will take spaces as
@@ -130,20 +166,40 @@ class Console:
         args = _sys.argv[1:]
         args_len = len(args)
         arg_lookup = {}
-        for arg_key, arg_group in find_args.items():
-            for arg in arg_group:
-                arg_lookup[arg] = arg_key
-        results = {key: {"exists": False, "value": None} for key in find_args}
+        results = {}
+        for alias, config in find_args.items():
+            flags = None
+            default_value = None
+            if isinstance(config, (list, tuple)):
+                flags = config
+            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 not isinstance(flags, (list, tuple)):
+                    raise ValueError(f"Invalid 'flags' for alias '{alias}'. Must be a list or tuple.")
+            else:
+                raise TypeError(f"Invalid configuration type for alias '{alias}'. Must be a list, tuple, or dict.")
+            results[alias] = {"exists": False, "value": default_value}
+            for flag in flags:
+                if flag in arg_lookup:
+                    raise ValueError(
+                        f"Duplicate flag '{flag}' found. It's assigned to both '{arg_lookup[flag]}' and '{alias}'."
+                    )
+                arg_lookup[flag] = alias
         i = 0
         while i < args_len:
             arg = args[i]
-            arg_key = arg_lookup.get(arg)
-            if arg_key:
-                results[arg_key]["exists"] = True
+            alias = arg_lookup.get(arg)
+            if alias:
+                results[alias]["exists"] = True
+                value_found_after_flag = False
                 if i + 1 < args_len and not args[i + 1].startswith("-"):
                     if not allow_spaces:
-                        results[arg_key]["value"] = String.to_type(args[i + 1])
+                        results[alias]["value"] = String.to_type(args[i + 1])
                         i += 1
+                        value_found_after_flag = True
                     else:
                         value_parts = []
                         j = i + 1
@@ -151,8 +207,11 @@ class Console:
                             value_parts.append(args[j])
                             j += 1
                         if value_parts:
-                            results[arg_key]["value"] = String.to_type(" ".join(value_parts))
+                            results[alias]["value"] = String.to_type(" ".join(value_parts))
                             i = j - 1
+                            value_found_after_flag = True
+                if not value_found_after_flag:
+                    results[alias]["value"] = True
             i += 1
         return Args(**results)
 
@@ -190,8 +249,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:
@@ -210,10 +269,14 @@ class Console:
         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 format_linebreaks:
-            clean_prompt, removals = FormatCodes.remove_formatting(str(prompt), get_removals=True)
+            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), removals)  # type: ignore[assignment]
+            )
         else:
             prompt = str(prompt)
         if title == "":
@@ -269,8 +332,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:
@@ -287,8 +350,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:
@@ -303,8 +366,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:
@@ -319,8 +382,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:
@@ -335,8 +398,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,
@@ -352,8 +415,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,
@@ -368,8 +431,8 @@ class Console:
         *values: object,
         start: str = "",
         end: str = "\n",
-        box_bg_color: str | hexa | rgba = "green",
-        default_color: hexa | rgba = "#000",
+        box_bg_color: str | Rgba | Hexa = "green",
+        default_color: Rgba | Hexa = "#000",
         w_padding: int = 2,
         w_full: bool = False,
     ) -> None:
@@ -384,7 +447,7 @@ 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.strip() for val in values for line in val.splitlines()]
+        lines = [line.rstrip() for val in values for line in str(val).splitlines()]
         unfmt_lines = [FormatCodes.remove_formatting(line) for line in lines]
         max_line_len = max(len(line) for line in unfmt_lines)
         pad_w_full = (Console.w - (max_line_len + (2 * w_padding))) if w_full else 0
@@ -407,7 +470,7 @@ class Console:
         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
@@ -429,7 +492,7 @@ class Console:
         prompt: object = "",
         start="",
         end="\n",
-        default_color: hexa | rgba = COLOR.cyan,
+        default_color: Rgba | Hexa = COLOR.cyan,
         show_keybindings=True,
         input_prefix=" ⤷ ",
         reset_ansi=True,
@@ -452,7 +515,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)
@@ -464,11 +527,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:
@@ -479,14 +542,14 @@ 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
         last_console_width = 0
 
         def update_display(console_width: int) -> None:
-            nonlocal select_all, last_line_count, last_console_width
+            nonlocal last_line_count, last_console_width
             lines = String.split_count(str(prompt) + (mask_char * len(result) if mask_char else result), console_width)
             line_count = len(lines)
             if (line_count > 1 or line_count < last_line_count) and not last_line_count == 1:
@@ -535,7 +598,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)
 
@@ -556,7 +620,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
@@ -567,12 +631,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,
+        )