log21 3.0.1__tar.gz → 3.1.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: log21
-Version: 3.0.1
+Version: 3.1.0
 Summary: A simple logging package
 Keywords: python,log,colorize,color,logging,Python3,CodeWriter21
 Author: CodeWriter21(Mehrad Pooryoussof)
@@ -94,85 +94,139 @@ pip install git+https://github.com/MPCodeWriter21/log21
 Changelog
 ---------
 
-### v3.0.1
+### v3.1.0
 
-Fix the issue with `argumentify` which would result in falsy default values to be
-replaced with None.
+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.
+
+#### 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(offset: int = 0) -> None:
+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
+    """
     ...
 
-argumentify(main)
+
+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
+
 ```
 
-if no value is provided for `--offset`, the default will be `None` instead of `0` which
-is unexpected and can lead to issues.
-
-#### Breaking Changes
-
-+ **Internal module renaming and normalization**
-  + All internal modules were renamed to lowercase and, in some cases, split or
-    reorganized.
-  + Imports such as `log21.Colors`, `log21.Logger`, `log21.ProgressBar`, etc. are no
-    longer valid.
-  + Users importing from internal modules must update their imports to the new module
-    names.
-  + Public imports from `log21` remain supported.
-
-+ **Argumentify exception renames**
-  + Several exceptions were renamed to follow a consistent `*Error` naming convention:
-    + `TooFewArguments` → `TooFewArgumentsError`
-    + `RequiredArgument` → `RequiredArgumentError`
-    + `IncompatibleArguments` → `IncompatibleArgumentsError`
-  + Code that explicitly raises or catches these exceptions must be updated.
-
-#### Changes
-
-+ **Crash reporter behavior improvement**
-  + Prevented the default file crash reporter from creating `.crash_report` files when it
-    is not actually used.
-  + Implemented using an internal `FakeModule` helper.
-
-+ **Argparse compatibility update**
-  + Bundled and used the Python 3.13 `argparse` implementation to ensure consistent
-    behavior across supported Python versions.
-
-+ **Progress bar module rename**
-  + Renamed the internal progress bar module to `progress_bar` for consistency with the
-    new naming scheme.
-  + This will not break the usages of `log21.progress_bar(...)` since the call
-    functionality was added to the module using the `FakeModule` helper.
-
-+ **Examples added and updated**
-  + Added new example code files.
-  + Updated existing examples to match the v3 API and conventions.
-
-#### Fixes
-
-+ Resolved various linting and static-analysis issues across the codebase.
-+ Addressed minor compatibility issues uncovered by running linters and pre-commit hooks.
-+ Resolved errors occurring in environments with newer versions of argparse.
-
-#### Internal and Maintenance Changes
-
-+ Migrated the build system configuration to `uv`.
-+ Updated Python version classifiers and set the supported Python version to 3.9+.
-+ Added `vermin` to the pre-commit configuration.
-+ Updated `.gitignore`, license metadata, and tool configurations.
-+ Silenced and resolved a large number of linter warnings.
-+ General internal refactoring with no intended user-visible behavioral changes.
-
-#### Notes
-
-+ There are **no intentional behavioral changes** in logging output, argument parsing
-  logic, or UI components.
-+ Most projects will require **minimal or no changes** unless they depend on internal
-  modules or renamed exceptions.
-+ See [MIGRATION-V2-V3.md](https://github.com/MPCodeWriter21/log21/blob/master/MIGRATION-V2-V3.md)
-for detailed upgrade instructions.
+_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)
 

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

@@ -69,85 +69,139 @@ pip install git+https://github.com/MPCodeWriter21/log21
 Changelog
 ---------
 
-### v3.0.1
+### v3.1.0
 
-Fix the issue with `argumentify` which would result in falsy default values to be
-replaced with None.
+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.
+
+#### 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(offset: int = 0) -> None:
+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
+    """
     ...
 
-argumentify(main)
+
+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
+
 ```
 
-if no value is provided for `--offset`, the default will be `None` instead of `0` which
-is unexpected and can lead to issues.
-
-#### Breaking Changes
-
-+ **Internal module renaming and normalization**
-  + All internal modules were renamed to lowercase and, in some cases, split or
-    reorganized.
-  + Imports such as `log21.Colors`, `log21.Logger`, `log21.ProgressBar`, etc. are no
-    longer valid.
-  + Users importing from internal modules must update their imports to the new module
-    names.
-  + Public imports from `log21` remain supported.
-
-+ **Argumentify exception renames**
-  + Several exceptions were renamed to follow a consistent `*Error` naming convention:
-    + `TooFewArguments` → `TooFewArgumentsError`
-    + `RequiredArgument` → `RequiredArgumentError`
-    + `IncompatibleArguments` → `IncompatibleArgumentsError`
-  + Code that explicitly raises or catches these exceptions must be updated.
-
-#### Changes
-
-+ **Crash reporter behavior improvement**
-  + Prevented the default file crash reporter from creating `.crash_report` files when it
-    is not actually used.
-  + Implemented using an internal `FakeModule` helper.
-
-+ **Argparse compatibility update**
-  + Bundled and used the Python 3.13 `argparse` implementation to ensure consistent
-    behavior across supported Python versions.
-
-+ **Progress bar module rename**
-  + Renamed the internal progress bar module to `progress_bar` for consistency with the
-    new naming scheme.
-  + This will not break the usages of `log21.progress_bar(...)` since the call
-    functionality was added to the module using the `FakeModule` helper.
-
-+ **Examples added and updated**
-  + Added new example code files.
-  + Updated existing examples to match the v3 API and conventions.
-
-#### Fixes
-
-+ Resolved various linting and static-analysis issues across the codebase.
-+ Addressed minor compatibility issues uncovered by running linters and pre-commit hooks.
-+ Resolved errors occurring in environments with newer versions of argparse.
-
-#### Internal and Maintenance Changes
-
-+ Migrated the build system configuration to `uv`.
-+ Updated Python version classifiers and set the supported Python version to 3.9+.
-+ Added `vermin` to the pre-commit configuration.
-+ Updated `.gitignore`, license metadata, and tool configurations.
-+ Silenced and resolved a large number of linter warnings.
-+ General internal refactoring with no intended user-visible behavioral changes.
-
-#### Notes
-
-+ There are **no intentional behavioral changes** in logging output, argument parsing
-  logic, or UI components.
-+ Most projects will require **minimal or no changes** unless they depend on internal
-  modules or renamed exceptions.
-+ See [MIGRATION-V2-V3.md](https://github.com/MPCodeWriter21/log21/blob/master/MIGRATION-V2-V3.md)
-for detailed upgrade instructions.
+_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)
 

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

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

{log21-3.0.1 → 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.1'
+__version__ = '3.1.0'
 __github__ = 'https://GitHub.com/MPCodeWriter21/log21'
 __all__ = [
     'ColorizingStreamHandler', 'DecolorizingFileHandler', 'ColorizingFormatter',

{log21-3.0.1 → 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,20 +397,8 @@ 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.short_description
-    )
+    parser = _argparse.ColorizingArgumentParser(description=info.docstring.description)
     # Add the arguments
     _add_arguments(parser, info)
     cli_args = parser.parse_args()
@@ -432,7 +444,7 @@ def _argumentify(functions: _Dict[str, Callable]) -> None:
     parser = _argparse.ColorizingArgumentParser()
     subparsers = parser.add_subparsers(required=True)
     for name, (_, info) in functions_info.items():
-        subparser = subparsers.add_parser(name, help=info.docstring.short_description)
+        subparser = subparsers.add_parser(name, help=info.docstring.description)
         _add_arguments(subparser, info)
         subparser.set_defaults(func=info.function)
     cli_args = parser.parse_args()