make Console.get_args() intake **find_args kwargs instead of a find_args dictionary

Author: xulbux

.gitignore

@@ -25,6 +25,7 @@ cython_debug/
 __pypackages__/
 
 # TESTING
+.venv/
 .pytest_cache/
 
 # MISCELLANEOUS

src/xulbux/console.py

@@ -101,16 +101,14 @@ def __bool__(self):
 
 class Args:
     """Container for parsed command-line arguments, allowing attribute-style access.\n
-    --------------------------------------------------------------------------------------
-    - `kwargs` -⠀a mapping of argument aliases to their corresponding data dictionaries\n
-    --------------------------------------------------------------------------------------
+    ----------------------------------------------------------------------------------------
+    - `**kwargs` -⠀a mapping of argument aliases to their corresponding data dictionaries\n
+    ----------------------------------------------------------------------------------------
     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: Mapping[str, str | list[str]]):
+    def __init__(self, **kwargs: ArgResultRegular | ArgResultPositional):
         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.")
             if "values" in data_dict:
                 setattr(
                     self, alias_name,
@@ -181,70 +179,70 @@ class Console:
 
     @staticmethod
     def get_args(
-        find_args: Mapping[str, set[str] | ArgConfigWithDefault | Literal["before", "after"]],
         allow_spaces: bool = False,
+        **find_args: set[str] | ArgConfigWithDefault | Literal["before", "after"],
     ) -> Args:
         """Will search for the specified arguments in the command line
         arguments and return the results as a special `Args` object.\n
-        -----------------------------------------------------------------------------------------------------------
-        - `find_args` -⠀a dictionary defining the argument aliases and their flags/configuration (explained below)
-        - `allow_spaces` -⠀if true , flagged argument values can span multiple space-separated tokens until the
+        ---------------------------------------------------------------------------------------------------------
+        - `allow_spaces` -⠀if true, flagged argument values can span multiple space-separated tokens until the
           next flag is encountered, otherwise only the immediate next token is captured as the value:<br>
           This allows passing multi-word values without quotes
           (e.g. `-f hello world` instead of `-f "hello world"`).<br>
           * This setting does not affect `"before"`/`"after"` positional arguments,
             which always treat each token separately.<br>
           * When `allow_spaces=True`, positional `"after"` arguments will always be empty if any flags
-            are present, as all tokens following the last flag are consumed as that flag's value.\n
-        -----------------------------------------------------------------------------------------------------------
-        The `find_args` dictionary can have the following structures for each alias:
+            are present, as all tokens following the last flag are consumed as that flag's value.
+        - `**find_args` -⠀kwargs defining the argument aliases and their flags/configuration (explained below)\n
+        ---------------------------------------------------------------------------------------------------------
+        The `**find_args` keyword arguments can have the following structures for each alias:
         1. Simple set of flags (when no default value is needed):
            ```python
-           "alias_name": {"-f", "--flag"}
+           alias_name={"-f", "--flag"}
            ```
         2. Dictionary with `"flags"` and `"default"` value:
            ```python
-           "alias_name": {
+           alias_name={
                "flags": {"-f", "--flag"},
                "default": "some_value",
            }
            ```
         3. Positional argument collection using the literals `"before"` or `"after"`:
            ```python
-           "alias_name": "before"  # Collects non-flagged args before first flag
-           "alias_name": "after"   # Collects non-flagged args after last flag
+           alias_name="before"  # Collects non-flagged args before first flag
+           alias_name="after"   # Collects non-flagged args after last flag
            ```
-        #### Example `find_args`:
+        #### Example usage:
         ```python
-        find_args={
-            "text": "before",           # Positional args before flagged args
-            "arg1": {"-a1", "--arg1"},  # Just flags
-            "arg2": {"-a2", "--arg2"},  # Just flags
-            "arg3": {                   # With default value
+        ARGS = Console.get_args(
+            text="before",           # Positional args before flagged args
+            arg1={"-a1", "--arg1"},  # Just flags
+            arg2={"-a2", "--arg2"},  # Just flags
+            arg3={                   # With default value
                 "flags": {"-a3", "--arg3"},
                 "default": "default_val",
             },
-        }
+        )
         ```
         If the script is called via the command line:\n
         `python script.py Hello World -a1 "value1" --arg2`\n
-        ...it would return an `Args` object where:
-        - `args.text.exists` is `True`, `args.text.values` is `["Hello", "World"]`
-        - `args.arg1.exists` is `True`, `args.arg1.value` is `"value1"` (flag present with value)
-        - `args.arg2.exists` is `True`, `args.arg2.value` is `None` (flag present without value)
-        - `args.arg3.exists` is `False`, `args.arg3.value` is `"default_val"` (not present, has default value)\n
-        -----------------------------------------------------------------------------------------------------------
+        ... it would return an `Args` object where:
+        - `ARGS.text.exists` is `True`, `ARGS.text.values` is `["Hello", "World"]`
+        - `ARGS.arg1.exists` is `True`, `ARGS.arg1.value` is `"value1"` (flag present with value)
+        - `ARGS.arg2.exists` is `True`, `ARGS.arg2.value` is `None` (flag present without value)
+        - `ARGS.arg3.exists` is `False`, `ARGS.arg3.value` is `"default_val"` (not present, has default value)\n
+        ---------------------------------------------------------------------------------------------------------
         If an arg, defined with flags 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
           * `values` will be `[]` for positional `"before"`/`"after"` arguments\n
-        -----------------------------------------------------------------------------------------------------------
+        ---------------------------------------------------------------------------------------------------------
         For positional arguments:
         - `"before"` collects all non-flagged arguments that appear before the first flag
         - `"after"` collects all non-flagged arguments that appear after the last flag's value
-        -----------------------------------------------------------------------------------------------------------
-        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 part of the value up until the next arg-flag is found.
+        ---------------------------------------------------------------------------------------------------------
+        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 part of the value up until the next arg-flag is found.
         (Multiple spaces will become one space in the value.)"""
         positional_configs, arg_lookup, results = {}, {}, {}
         before_count, after_count = 0, 0
@@ -254,8 +252,6 @@ def get_args(
         for alias, config in find_args.items():
             flags, default_value = None, None
 
-            if not alias.isidentifier():
-                raise TypeError(f"Argument alias '{alias}' is invalid: It must be a valid Python variable name.")
             if isinstance(config, str):
                 # HANDLE POSITIONAL ARGUMENT COLLECTION
                 if config == "before":
@@ -277,7 +273,7 @@ def get_args(
                 flags = config
                 results[alias] = {"exists": False, "value": default_value}
             elif isinstance(config, dict):
-                flags, default_value = config["flags"], config["default"]
+                flags, default_value = config.get("flags"), config.get("default")
                 results[alias] = {"exists": False, "value": default_value}
             else:
                 raise TypeError(

src/xulbux/regex.py

@@ -202,19 +202,19 @@ def _clean(pattern: str) -> str:
 
 class LazyRegex:
     """A class that lazily compiles and caches regex patterns on first access.\n
-    -----------------------------------------------------------------------------------
-    - `patterns` -⠀keyword arguments where the key is the name of the pattern and
+    --------------------------------------------------------------------------------
+    - `**patterns` -⠀keyword arguments where the key is the name of the pattern and
       the value is the regex pattern string to compile\n
-    -----------------------------------------------------------------------------------
+    --------------------------------------------------------------------------------
     #### Example usage:
     ```python
     PATTERNS = LazyRegex(
         email=r"(?i)[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}",
         phone=r"\\+?\\d{1,3}[-.\\s]?\\(?\\d{1,4}\\)?[-.\\s]?\\d{1,4}[-.\\s]?\\d{1,9}",
     )
 
-    email_pattern = PATTERNS.email  # COMPILES AND CACHES THE EMAIL PATTERN
-    phone_pattern = PATTERNS.phone  # COMPILES AND CACHES THE PHONE PATTERN
+    email_pattern = PATTERNS.email  # Compiles and caches the EMAIL pattern
+    phone_pattern = PATTERNS.phone  # Compiles and caches the PHONE pattern
     ```"""
 
     def __init__(self, **patterns: str):

tests/test_console.py

@@ -213,7 +213,7 @@ def test_console_size(mock_terminal_size):
 )
 def test_get_args_no_spaces(monkeypatch, argv, find_args, expected_args_dict):
     monkeypatch.setattr(sys, "argv", argv)
-    args_result = Console.get_args(find_args, allow_spaces=False)
+    args_result = Console.get_args(allow_spaces=False, **find_args)
     assert isinstance(args_result, Args)
     assert args_result.dict() == expected_args_dict
     for key, expected in expected_args_dict.items():
@@ -336,7 +336,7 @@ def test_get_args_no_spaces(monkeypatch, argv, find_args, expected_args_dict):
 )
 def test_get_args_with_spaces(monkeypatch, argv, find_args, expected_args_dict):
     monkeypatch.setattr(sys, "argv", argv)
-    args_result = Console.get_args(find_args, allow_spaces=True)
+    args_result = Console.get_args(allow_spaces=True, **find_args)
     assert isinstance(args_result, Args)
     assert args_result.dict() == expected_args_dict
 
@@ -345,63 +345,37 @@ def test_get_args_flag_without_value(monkeypatch):
     """Test that flags without values have None as their value, not True."""
     # TEST SINGLE FLAG WITHOUT VALUE AT END OF ARGS
     monkeypatch.setattr(sys, "argv", ["script.py", "--verbose"])
-    args_result = Console.get_args({"verbose": {"--verbose"}})
+    args_result = Console.get_args(verbose={"--verbose"})
     assert args_result.verbose.exists is True
     assert args_result.verbose.value is None
 
     # TEST FLAG WITHOUT VALUE FOLLOWED BY ANOTHER FLAG
     monkeypatch.setattr(sys, "argv", ["script.py", "--verbose", "--debug"])
-    args_result = Console.get_args({"verbose": {"--verbose"}, "debug": {"--debug"}})
+    args_result = Console.get_args(verbose={"--verbose"}, debug={"--debug"})
     assert args_result.verbose.exists is True
     assert args_result.verbose.value is None
     assert args_result.debug.exists is True
     assert args_result.debug.value is None
 
     # TEST FLAG WITH DEFAULT VALUE BUT NO PROVIDED VALUE
     monkeypatch.setattr(sys, "argv", ["script.py", "--mode"])
-    args_result = Console.get_args({"mode": {"flags": {"--mode"}, "default": "production"}})
+    args_result = Console.get_args(mode={"flags": {"--mode"}, "default": "production"})
     assert args_result.mode.exists is True
     assert args_result.mode.value is None
 
 
-def test_get_args_invalid_alias():
-    with pytest.raises(TypeError, match="Argument alias 'invalid-alias' is invalid."):
-        Args(**{"invalid-alias": {"exists": False, "value": None}})
-
-    with pytest.raises(TypeError, match="Argument alias '123start' is invalid."):
-        Args(**{"123start": {"exists": False, "value": None}})
-
-
-def test_get_args_invalid_config():
-    with pytest.raises(TypeError, match="Invalid configuration type for alias 'bad_config'.\n"
-                       "Must be a set, dict, literal 'before' or literal 'after'."):
-        Console.get_args({"bad_config": 123})  # type: ignore[assignment]
-
-    with pytest.raises(ValueError,
-                       match="Invalid configuration for alias 'missing_flags'. Dictionary must contain a 'flags' key."):
-        Console.get_args({"missing_flags": {"default": "value"}})  # type: ignore[assignment]
-
-    with pytest.raises(ValueError,
-                       match="Invalid configuration for alias 'bad_flags'. Dictionary must contain a 'default' key.\n"
-                       "Use a simple set of strings if no default value is needed and only flags are to be specified."):
-        Console.get_args({"bad_flags": {"flags": ["--flag"]}})  # type: ignore[assignment]
-
-    with pytest.raises(ValueError, match="Invalid 'flags' for alias 'bad_flags'. Must be a set of strings."):
-        Console.get_args({"bad_flags": {"flags": "not-a-set", "default": "value"}})  # type: ignore[assignment]
-
-
 def test_get_args_duplicate_flag():
     with pytest.raises(ValueError, match="Duplicate flag '-f' found. It's assigned to both 'file1' and 'file2'."):
-        Console.get_args({"file1": {"-f", "--file1"}, "file2": {"flags": {"-f", "--file2"}, "default": "..."}})
+        Console.get_args(file1={"-f", "--file1"}, file2={"flags": {"-f", "--file2"}, "default": "..."})
 
     with pytest.raises(ValueError, match="Duplicate flag '--long' found. It's assigned to both 'arg1' and 'arg2'."):
-        Console.get_args({"arg1": {"flags": {"--long"}, "default": "..."}, "arg2": {"-a", "--long"}})
+        Console.get_args(arg1={"flags": {"--long"}, "default": "..."}, arg2={"-a", "--long"})
 
 
 def test_get_args_dash_values_not_treated_as_flags(monkeypatch):
     """Test that values starting with dashes are not treated as flags unless explicitly defined"""
     monkeypatch.setattr(sys, "argv", ["script.py", "-v", "-42", "--input", "-3.14"])
-    result = Console.get_args({"verbose": {"-v"}, "input": {"--input"}})
+    result = Console.get_args(verbose={"-v"}, input={"--input"})
 
     assert result.verbose.exists is True
     assert result.verbose.value == "-42"
@@ -412,7 +386,7 @@ def test_get_args_dash_values_not_treated_as_flags(monkeypatch):
 def test_get_args_dash_strings_as_values(monkeypatch):
     """Test that dash-prefixed strings are treated as values when not defined as flags"""
     monkeypatch.setattr(sys, "argv", ["script.py", "-f", "--not-a-flag", "-t", "-another-value"])
-    result = Console.get_args({"file": {"-f"}, "text": {"-t"}})
+    result = Console.get_args(file={"-f"}, text={"-t"})
 
     assert result.file.exists is True
     assert result.file.value == "--not-a-flag"
@@ -423,7 +397,7 @@ def test_get_args_dash_strings_as_values(monkeypatch):
 def test_get_args_positional_with_dashes_before(monkeypatch):
     """Test that positional 'before' arguments include dash-prefixed values"""
     monkeypatch.setattr(sys, "argv", ["script.py", "-123", "--some-file", "normal", "-v"])
-    result = Console.get_args({"before_args": "before", "verbose": {"-v"}})
+    result = Console.get_args(before_args="before", verbose={"-v"})
 
     assert result.before_args.exists is True
     assert result.before_args.values == ["-123", "--some-file", "normal"]
@@ -434,7 +408,7 @@ def test_get_args_positional_with_dashes_before(monkeypatch):
 def test_get_args_positional_with_dashes_after(monkeypatch):
     """Test that positional 'after' arguments include dash-prefixed values"""
     monkeypatch.setattr(sys, "argv", ["script.py", "-v", "value", "-123", "--output-file", "-negative"])
-    result = Console.get_args({"verbose": {"-v"}, "after_args": "after"})
+    result = Console.get_args(verbose={"-v"}, after_args="after")
 
     assert result.verbose.exists is True
     assert result.verbose.value == "value"
@@ -445,7 +419,7 @@ def test_get_args_positional_with_dashes_after(monkeypatch):
 def test_get_args_multiword_with_dashes(monkeypatch):
     """Test multiword values with dashes when allow_spaces=True"""
     monkeypatch.setattr(sys, "argv", ["script.py", "-m", "start", "-middle", "--end", "-f", "other"])
-    result = Console.get_args({"message": {"-m"}, "file": {"-f"}}, allow_spaces=True)
+    result = Console.get_args(allow_spaces=True, message={"-m"}, file={"-f"})
 
     assert result.message.exists is True
     assert result.message.value == "start -middle --end"
@@ -461,13 +435,13 @@ def test_get_args_mixed_dash_scenarios(monkeypatch):
             "after1", "-also-not-flag"
         ]
     )
-    result = Console.get_args({
-        "before": "before",
-        "verbose": {"-v"},
-        "debug": {"-d"},
-        "file": {"--file"},
-        "after": "after",
-    })
+    result = Console.get_args(
+        before="before",
+        verbose={"-v"},
+        debug={"-d"},
+        file={"--file"},
+        after="after",
+    )
 
     assert result.before.exists is True
     assert result.before.values == ["before1", "-not-flag", "before2"]

tests/test_data.py

@@ -42,9 +42,6 @@ def test_serialize_bytes():
     import base64
     assert base64.b64decode(serialized_non_utf8["bytes"]).decode("latin-1") == non_utf8_bytes.decode("latin-1")
 
-    with pytest.raises(TypeError):
-        Data.serialize_bytes("not bytes")  # type: ignore[assignment]
-
 
 def test_deserialize_bytes():
     utf8_serialized_bytes = {"bytes": "Hello", "encoding": "utf-8"}

tests/test_path.py

@@ -62,8 +62,6 @@ def test_extend(setup_test_environment):
     assert Path.extend("") is None
     with pytest.raises(PathNotFoundError, match="Path is empty."):
         Path.extend("", raise_error=True)
-    with pytest.raises(TypeError, match="parameter must be a string"):
-        Path.extend(None, raise_error=True)  # type: ignore[assignment]
 
     # FOUND IN STANDARD LOCATIONS
     assert Path.extend("file_in_cwd.txt") == str(env["cwd"] / "file_in_cwd.txt")