log21 3.0.2__tar.gz → 3.1.0__tar.gz

{log21-3.0.2 → log21-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: log21
-Version: 3.0.2
+Version: 3.1.0
 Summary: A simple logging package
 Keywords: python,log,colorize,color,logging,Python3,CodeWriter21
 Author: CodeWriter21(Mehrad Pooryoussof)
@@ -94,57 +94,140 @@ pip install git+https://github.com/MPCodeWriter21/log21
 Changelog
 ---------
 
-### v3.0.2
+### v3.1.0
 
-Change `argumentify` to use the whole function description as the argument-parser
-description instead of the one-line short description.
+Change the way `argumentify` handles function parameters to argument-parser arguments
+conversion.
 
-+ Example:
++ `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.
 
-```python
-def main(verbose: bool = False) -> None:
-    """This is a very useful tool and I will describe it thoroughly. It is so good that
-    we have a second line in the first part of the description.
+#### Example 1
 
-    And now we can talk more about the tool...
+```python
+def main(path: Path, /, output: Path, *, verbose: bool = False):
+    """Process a file.
 
-    :param verbose: This flag will make the logs more verbose!
+    :param path: The input file path
+    :param output: The output file
+    :param verbose: Write more logs to the standard output.
     """
+    ...
 
-argumentify(main)
+
+if __name__ == "__main__":
+    argumentify(main)
 ```
 
-The way old versions would look:
+The help looks like this:
 
 ```help
-usage: test.py [-h] [--verbose]
+usage: test.py [-h] --output OUTPUT [--verbose] path
+
+Process a file.
 
-This is a very useful tool and I will describe it thoroughly. It is so good that
+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
-                        This flag will make the logs more verbose!
+                        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.")
+    ...
 ```
 
-Now at v3.0.2:
+The help looks like this:
 
 ```help
-usage: test.py [-h] [--verbose]
+usage: test.py [-h] output [inputs ...]
+
+Process multiple files into one.
 
-This is a very useful tool and I will describe it thoroughly. It is so good that we have a
-second line in the first part of the description. And now we can talk more about the tool...
+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
-                        This flag will make the logs more verbose!
+                        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._
+
 [Full CHANGELOG](https://github.com/MPCodeWriter21/log21/blob/master/CHANGELOG.md)
 
 Usage Examples

{log21-3.0.2 → log21-3.1.0}/README.md

@@ -69,57 +69,140 @@ pip install git+https://github.com/MPCodeWriter21/log21
 Changelog
 ---------
 
-### v3.0.2
+### v3.1.0
 
-Change `argumentify` to use the whole function description as the argument-parser
-description instead of the one-line short description.
+Change the way `argumentify` handles function parameters to argument-parser arguments
+conversion.
 
-+ Example:
++ `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.
 
-```python
-def main(verbose: bool = False) -> None:
-    """This is a very useful tool and I will describe it thoroughly. It is so good that
-    we have a second line in the first part of the description.
+#### Example 1
 
-    And now we can talk more about the tool...
+```python
+def main(path: Path, /, output: Path, *, verbose: bool = False):
+    """Process a file.
 
-    :param verbose: This flag will make the logs more verbose!
+    :param path: The input file path
+    :param output: The output file
+    :param verbose: Write more logs to the standard output.
     """
+    ...
 
-argumentify(main)
+
+if __name__ == "__main__":
+    argumentify(main)
 ```
 
-The way old versions would look:
+The help looks like this:
 
 ```help
-usage: test.py [-h] [--verbose]
+usage: test.py [-h] --output OUTPUT [--verbose] path
+
+Process a file.
 
-This is a very useful tool and I will describe it thoroughly. It is so good that
+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
-                        This flag will make the logs more verbose!
+                        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.")
+    ...
 ```
 
-Now at v3.0.2:
+The help looks like this:
 
 ```help
-usage: test.py [-h] [--verbose]
+usage: test.py [-h] output [inputs ...]
+
+Process multiple files into one.
 
-This is a very useful tool and I will describe it thoroughly. It is so good that we have a
-second line in the first part of the description. And now we can talk more about the tool...
+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
-                        This flag will make the logs more verbose!
+                        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._
+
 [Full CHANGELOG](https://github.com/MPCodeWriter21/log21/blob/master/CHANGELOG.md)
 
 Usage Examples

{log21-3.0.2 → log21-3.1.0}/pyproject.toml

@@ -23,7 +23,7 @@ dependencies = [
     "webcolors",
     "docstring-parser"
 ]
-version = "3.0.2"
+version = "3.1.0"
 
 [build-system]
 requires = ["uv_build>=0.8.15,<0.9.0"]

{log21-3.0.2 → log21-3.1.0}/src/log21/__init__.py

@@ -31,7 +31,7 @@ from .stream_handler import StreamHandler, ColorizingStreamHandler
 # yapf: enable
 
 __author__ = 'CodeWriter21 (Mehrad Pooryoussof)'
-__version__ = '3.0.2'
+__version__ = '3.1.0'
 __github__ = 'https://GitHub.com/MPCodeWriter21/log21'
 __all__ = [
     'ColorizingStreamHandler', 'DecolorizingFileHandler', 'ColorizingFormatter',

{log21-3.0.2 → log21-3.1.0}/src/log21/argumentify.py

@@ -344,6 +344,28 @@ def _add_arguments(
     """
     if reserved_flags is None:
         reserved_flags = RESERVED_FLAGS.copy()
+
+    keyword_only_exists = False
+    for argument in info.arguments.values():
+        # Reserve the name of POSITIONAL_ONLY and VAR_POSITIONAL arguments as flags
+        # since their flag name and their dest need to be the same
+        if argument.kind in [_inspect._ParameterKind.POSITIONAL_ONLY,
+                             _inspect._ParameterKind.VAR_POSITIONAL]:
+            reserved_flags.add(argument.name)
+        # If there is at least one KEYWORD_ONLY argument, the parameters of kind
+        # POSITIONAL_OR_KEYWORD will be marked as required
+        if argument.kind == _inspect._ParameterKind.KEYWORD_ONLY:
+            keyword_only_exists = True
+        # Check if the function has a VAR_KEYWORD argument
+        # Raises a ArgumentTypeError if it does
+        # TODO: See if we can find a use-case and a way of supporting these arguments
+        if argument.kind == _inspect._ParameterKind.VAR_KEYWORD:
+            raise ArgumentTypeError(
+                f"The function has a `**{argument.name}` argument, "
+                "which is not supported.",
+                unsupported_arg=argument.name
+            )
+
     # Add the arguments
     for argument in info.arguments.values():
         config: _Dict[str, _Any] = {
@@ -351,19 +373,21 @@ def _add_arguments(
             'dest': argument.name,
             'help': argument.help
         }
+        flags = generate_flag(argument, reserved_flags=reserved_flags)
         if argument.annotation is bool:
             config['action'] = 'store_true'
         elif argument.annotation:
             config['type'] = argument.annotation
         if argument.kind == _inspect._ParameterKind.POSITIONAL_ONLY:
-            config['required'] = True
+            flags = [config.pop('dest')]
         if argument.kind == _inspect._ParameterKind.VAR_POSITIONAL:
             config['nargs'] = '*'
+            flags = [config.pop('dest')]
+        if argument.kind == _inspect._ParameterKind.POSITIONAL_OR_KEYWORD and keyword_only_exists:
+            config['required'] = True
         if argument.default is not None:
             config['default'] = argument.default
-        parser.add_argument(
-            *generate_flag(argument, reserved_flags=reserved_flags), **config
-        )
+        parser.add_argument(*flags, **config)
 
 
 def _argumentify_one(func: Callable) -> None:
@@ -373,16 +397,6 @@ def _argumentify_one(func: Callable) -> None:
     """
     info = FunctionInfo(func)
 
-    # Check if the function has a VAR_KEYWORD argument
-    # Raises a ArgumentTypeError if it does
-    for argument in info.arguments.values():
-        if argument.kind == _inspect._ParameterKind.VAR_KEYWORD:
-            raise ArgumentTypeError(
-                f"The function has a `**{argument.name}` argument, "
-                "which is not supported.",
-                unsupported_arg=argument.name
-            )
-
     # Create the parser
     parser = _argparse.ColorizingArgumentParser(description=info.docstring.description)
     # Add the arguments