Change the way argumentify handles function parameters to argument-parser arguments conversion.

+ `POSITIONAL_ONLY` and `VAR_POSITIONAL` parameters will be positional
arguments.
+ `POSITIONAL_OR_KEYWORD` and `KEYWORD_ONLY` parameters have flags
assigned to them.
+ `POSITIONAL_OR_KEYWORD` parameters will be required if at least one
`KEYWORD_ONLY` parameter is there, otherwise they are optional.
+ `VAR_KEYWORD` parameters are still not supported.

Author: MPCodeWriter21

CHANGELOG.md

@@ -6,6 +6,140 @@ Help this project by [Donation](DONATE.md)
 Changes
 -------
 
+### v3.1.0
+
+Change the way `argumentify` handles function parameters to argument-parser arguments
+conversion.
+
+- `POSITIONAL_ONLY` and `VAR_POSITIONAL` parameters will be positional arguments.
+- `POSITIONAL_OR_KEYWORD` and `KEYWORD_ONLY` parameters have flags assigned to them.
+- `POSITIONAL_OR_KEYWORD` parameters will be required if at least one `KEYWORD_ONLY`
+  parameter is there, otherwise they are optional.
+- `VAR_KEYWORD` parameters are still not supported.
+
+#### Example 1
+
+```python
+def main(path: Path, /, output: Path, *, verbose: bool = False):
+    """Process a file.
+
+    :param path: The input file path
+    :param output: The output file
+    :param verbose: Write more logs to the standard output.
+    """
+    ...
+
+
+if __name__ == "__main__":
+    argumentify(main)
+```
+
+The help looks like this:
+
+```help
+usage: test.py [-h] --output OUTPUT [--verbose] path
+
+Process a file.
+
+positional arguments:
+  path              The input file path
+
+options:
+  -h, --help
+                        show this help message and exit
+  --output OUTPUT, -o OUTPUT
+                        The output file
+  --verbose, -v
+                        Write more logs to the standard output.
+
+```
+
+_Note that `path` and `output` are required._
+
+#### Example 2
+
+```python
+def main(output: Path, /, *inputs: Path):
+    """Process multiple files into one.
+
+    :param output: The output file
+    :param inputs: The path to the input files
+    """
+    # Since `inputs` is a VAR_POSITIONAL, while being a positional argument, it can have
+    # zero length which is in many cases not intended.
+    # You might want to add a check for its length and raise an ArgumentError if it does
+    # not match your needs
+
+    # Check if at least one input has been passed and mark the argument as required
+    # if len(inputs) < 1:
+    #     raise RequiredArgumentError("inputs")
+
+    # Raise an error unless at least two inputs are present
+    if len(inputs) < 2:
+        raise ArgumentError(message="You need to pass at least two files as input.")
+    ...
+```
+
+The help looks like this:
+
+```help
+usage: test.py [-h] output [inputs ...]
+
+Process multiple files into one.
+
+positional arguments:
+  output            The output file
+  inputs            The path to the input files
+
+options:
+  -h, --help
+                        show this help message and exit
+
+```
+
+#### Example 3
+
+```python
+def main(first_name: str, last_name: str, output: Path, verbose: bool = False):
+    """Write a greeting message.
+
+    :param first_name: The first name of the user to greet (optional)
+    :param last_name: The last name of the user to greet (optional)
+    :param output: The output file (stdout if none is provided)
+    :param verbose: If provided, will write the debug logs to stdout
+    """
+    ...
+
+
+if __name__ == "__main__":
+    argumentify(main)
+```
+
+The help looks like this:
+
+```help
+usage: test.py [-h] [--first-name FIRST_NAME] [--last-name LAST_NAME] [--output OUTPUT]
+               [--verbose]
+
+Write a greeting message.
+
+options:
+  -h, --help
+                        show this help message and exit
+  --first-name FIRST_NAME, -f FIRST_NAME
+                        The first name of the user to greet (optional)
+  --last-name LAST_NAME, -l LAST_NAME
+                        The last name of the user to greet (optional)
+  --output OUTPUT, -o OUTPUT
+                        The output file (stdout if none is provided)
+  --verbose, -v
+                        If provided, will write the debug logs to stdout
+
+```
+
+_Note that all the options are optional and default to None. `verbose` is False by
+default since a default value is provided for it in function definition._
+
 ### v3.0.2
 
 Change `argumentify` to use the whole function description as the argument-parser
@@ -46,7 +180,7 @@ Now at v3.0.2:
 ```help
 usage: test.py [-h] [--verbose]
 
-This is a very useful tool and I will describe it thoroughly. It is so good that we have a
+This is a very useful tool and I will describe it thoroughly. It is so good that we have
 second line in the first part of the description. And now we can talk more about the tool...
 
 options:
@@ -155,7 +289,7 @@ for detailed upgrade instructions.
 ### 2.10.0
 
 - Added some exception classes to raise in the "argumentified" functions to show
-  *parser error* to the user: `ArgumentError`, `IncompatibleArguments`,
+  **parser error** to the user: `ArgumentError`, `IncompatibleArguments`,
   `RequiredArgument`, `TooFewArguments`
 
 ### 2.9.2
@@ -373,7 +507,7 @@ clears the current line in the console and moves the cursor to the beginning of
 ### 2.3.3
 
 Fixed a bug that would cause an error creating a progress bar with no value set for
-width in systems without support for os.get_terminal_size().
+width in systems without support for `os.get_terminal_size()`.
 
 ### 2.3.2
 
@@ -560,7 +694,7 @@ TypeError: A logger name must be a string
 You can use `Logger.print` to print a message using the current level of the logger
 class.
 
-*It gets printed with any level.*
+_It gets printed with any level._
 
 ### 1.4.6
 

EXAMPLES.md

@@ -211,22 +211,25 @@ import log21
 
 
 class ReversedText:
-    def __init__(self, text: str):
+
+    def __init__(self, text: str) -> None:
         self._text = text[::-1]
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self._text
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{self.__class__.__name__}(text='{self._text}') at {hex(id(self))}>"
 
 
 # Old way
 def main():
-    """Here is my main function"""
+    """Here is my main function."""
     parser = log21.ColorizingArgumentParser()
-    parser.add_argument('--positional-arg', '-p', action='store', type=int,
-                        required=True, help="This argument is positional!")
+    parser.add_argument('positional_arg', action='store', type=int,
+                        help="This argument is positional!")
+    parser.add_argument('--required-arg', '-r', action='store', type=float,
+                        help="You have to pass this argument!")
     parser.add_argument('--optional-arg', '-o', action='store', type=ReversedText,
                         help="Whatever you pass here will be REVERSED!")
     parser.add_argument('--arg-with-default', '-a', action='store', default=21,
@@ -241,6 +244,7 @@ def main():
         log21.basic_config(level='DEBUG')
 
     log21.info(f"positional_arg = {args.positional_arg}")
+    log21.info(f"required_arg = {args.required_arg}")
     log21.info(f"optional_arg = {args.optional_arg}")
     log21.debug(f"arg_with_default = {args.arg_with_default}")
     log21.debug(f"additional_arg = {args.additional_arg}")
@@ -251,11 +255,20 @@ if __name__ == '__main__':
 
 
 # New way
-def main(positional_arg: int, /, optional_arg: ReversedText, arg_with_default: int = 21,
-         additional_arg=None, verbose: bool = False):
-    """Some description
+def main(
+    positional_arg: int,
+    /,
+    required_arg: float,
+    *,
+    optional_arg: ReversedText,
+    arg_with_default: int = 21,
+    additional_arg=None,
+    verbose: bool = False
+):
+    """Some description.
 
     :param positional_arg: This argument is positional!
+    :param required_arg: You have to pass this argument!
     :param optional_arg: Whatever you pass here will be REVERSED!
     :param arg_with_default: The default value is 21
     :param additional_arg: This one is extra.
@@ -265,6 +278,7 @@ def main(positional_arg: int, /, optional_arg: ReversedText, arg_with_default: i
         log21.basic_config(level='DEBUG')
 
     log21.info(f"{positional_arg = }")
+    log21.info(f"{required_arg = }")
     log21.info(f"{optional_arg = !s}")
     log21.debug(f"{arg_with_default = }")
     log21.debug(f"{additional_arg = !s}")
@@ -282,6 +296,7 @@ Example with multiple functions as entry-point:
 ```python
 import ast
 import operator
+import contextlib
 from functools import reduce
 
 import log21
@@ -349,8 +364,9 @@ def addition(*numbers: float):
         numbers (float): numbers to add
     """
     if len(numbers) < 2:
-        log21.error('At least two numbers are required! Use `-n`.')
-        return
+        raise log21.ArgumentError(
+            message='At least two numbers are required!'
+        )
     log21.info(f'Result: {sum(numbers)}')
 
 
@@ -361,8 +377,9 @@ def multiplication(*numbers: float):
         numbers (float): numbers to multiply
     """
     if len(numbers) < 2:
-        log21.error('At least two numbers are required! Use `-n`.')
-        return
+        raise log21.ArgumentError(
+            message='At least two numbers are required!'
+        )
     log21.info(f'Result: {reduce(lambda x, y: x * y, numbers)}')
 
 
@@ -374,17 +391,16 @@ def calc(*inputs: str, verbose: bool = False):
     expression = ' '.join(inputs)
 
     if len(expression) < 3:
-        log21.error('At least two numbers and one operator are required! Use `-i`.')
-        return
+        raise log21.ArgumentError(
+            message='At least two numbers and one operator are required!'
+        )
 
     if verbose:
         log21.basic_config(level='DEBUG')
 
     log21.debug(f'Expression: {expression}')
-    try:
+    with contextlib.suppress(TypeError, KeyError, SyntaxError):
         log21.info(f'Result: {safe_eval(expression)}')
-    except (TypeError, KeyError, SyntaxError):
-        pass
 
 
 if __name__ == "__main__":
@@ -396,7 +412,6 @@ if __name__ == "__main__":
 Example with parser errors:
 
 ```python
-# Common Section
 import log21
 
 
@@ -411,7 +426,6 @@ class ReversedText:
         return f"<{self.__class__.__name__}(text='{self._text}') at {hex(id(self))}>"
 
 
-# New way
 def main(positional_arg: int, /, optional_arg: ReversedText, arg_with_default: int = 21,
          additional_arg=None, verbose: bool = False, quiet: bool = False):
     """Some description