yadopt 2024.10.5__tar.gz

yadopt-2024.10.5/.gitignore

@@ -0,0 +1,13 @@
+# Ignore python cache
+__pycache__
+
+# Ignore python virtual environment
+venv
+.venv
+
+# Ignore build results
+dist/*
+
+# Ignore coverage cache
+.coverage
+htmlcov

yadopt-2024.10.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Tetsuya Ishikawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yadopt-2024.10.5/Makefile

@@ -0,0 +1,54 @@
+# Makefile
+
+SOFTWARE = yadopt
+
+help:
+	@echo "Usage:"
+	@echo "    make <command>"
+	@echo ""
+	@echo "Build commands:"
+	@echo "    build         Build package"
+	@echo "    testpypi      Upload package to TestPyPi"
+	@echo "    pypi          Upload package to PyPi"
+	@echo "    install-test  Install from TestPyPi"
+	@echo ""
+	@echo "Test and code check commands:"
+	@echo "    check         Check the code quality"
+	@echo "    count         Count the lines of code"
+	@echo "    coverage      Measure code coverage"
+	@echo ""
+	@echo "Other commands:"
+	@echo "    clean         Cleanup cache files"
+	@echo "    help          Show this message"
+
+check:
+	pyflakes yadopt/*.py
+	pylint yadopt/*.py
+
+count:
+	cloc --by-file yadopt/*.py
+
+coverage:
+	rm -rf .coverage
+	coverage run --source yadopt tests/run_tests.py
+	coverage html
+
+test:
+	python3 tests/run_tests.py
+
+build:
+	python3 -m build
+
+testpypi:
+	twine upload --repository pypitest dist/*
+
+pypi:
+	twine upload --repository pypi dist/*
+
+install-test:
+	python3 -m pip install --index-url https://test.pypi.org/simple/ $(SOFTWARE)
+
+clean:
+	rm -rf dist .coverage htmlcov `find -type d | grep __pycache__`
+
+# vim: noexpandtab tabstop=4 shiftwidth=4

yadopt-2024.10.5/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.3
+Name: yadopt
+Version: 2024.10.5
+Summary: Yet another docopt, a human-friendly command line arguments parser.
+Project-URL: Repository, https://github.com/tiskw/yadopt
+Project-URL: Issues, https://github.com/tiskw/yadopt/issues
+Author-email: Tetsuya Ishikawa <tiskw111@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 Tetsuya Ishikawa
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="figures/yadopt_logo.svg" width="90%">
+</div>
+
+<div align="center">
+  <img src="https://img.shields.io/badge/PYTHON-%3E%3D3.9-blue.svg?style=for-the-badge&logo=python&logoColor=white">
+  &nbsp;
+  <img src="https://img.shields.io/badge/LICENSE-MIT-orange.svg?style=for-the-badge">
+  &nbsp;
+  <img src="https://img.shields.io/badge/COVERAGE-96%25-green.svg?style=for-the-badge">
+  &nbsp;
+  <img src="https://img.shields.io/badge/QUALITY-9.94/10.0-yellow.svg?style=for-the-badge">
+</div>
+
+YadOpt - Yet another docopt
+================================================================================
+
+YadOpt is a Python re-implementation of [docopt](https://github.com/docopt/docopt)
+and [docopt-ng](https://github.com/jazzband/docopt-ng), a human-friendly
+command-line argument parser with type hinting and utility functions.
+YadOpt helps you to create beautiful command-line interfaces, just like docopt
+and docopt-ng, however, **YadOpt also supports date type hinting**.
+
+The following is the typical usage of YadOpt:
+
+```python
+"""
+Usage:
+    train.py <config_path> [--epochs INT] [--model STR] [--lr FLT]
+    train.py --help
+
+Train a neural network model.
+
+Arguments:
+    config_path     Path to config file.
+
+Training options:
+    --epochs INT    The number of training epochs.   [default: 100]
+    --model STR     Neural network model name.       [default: mlp]
+    --lr FLT        Learning rate.                   [default: 1.0E-3]
+
+Other options:
+    -h, --help      Show this help message and exit.
+"""
+
+import yadopt
+
+if __name__ == "__main__":
+    args = yadopt.parse(__doc__)
+    print(args)
+```
+
+Please save the above code as `sample.py`, and run it as follows:
+
+```console
+$ python3 sample.py config.toml --epochs 10 --model=cnn
+YadOptArgs(config_path=config.toml, epochs=10, model=cnn, lr=0.001, help=False)
+```
+
+In the above code, the parsed command-line arguments are stored in the `arg`
+and you can access each argument using dot notation, like `arg.config_path`.
+Also, the parsed command-line arguments are typed, in other words,
+the `arg` variable satisfies the following assertions:
+
+```python
+assert isinstance(args.config_path, pathlib.Path)
+assert isinstance(args.epochs, int)
+assert isinstance(args.model, str)
+assert isinstance(args.lr, float)
+assert isinstance(args.help, bool)
+```
+
+More realistic examples can be found in the [examples](./examples/README.md)
+directory.
+
+
+Installation
+--------------------------------------------------------------------------------
+
+Please install from [pip](https://pip.pypa.io/en/stable/).
+
+```console
+$ pip install yadopt
+```
+
+
+Usage
+--------------------------------------------------------------------------------
+
+### Use `parse` function
+
+The `yadopt.parse` function allows you to parse command-line arguments based on
+your docstring. The function is designed to parse `sys.argv` by default, but
+you can explicitly specify the argument vector by using the second argument
+of the function, just like as follows:
+
+```python
+# Parse sys.argv
+args = yadopt.parse(__doc__)
+
+# Parse the given argv.
+args = yadopt.parse(__doc__, argv)
+```
+
+### Use `wrap` function
+
+YadOpt supports the decorator approach for command-line parsing by the decorator
+`@yadopt.wrap` which takes the same arguments as the function `yadopt.parse`.
+
+```python
+@yadopt.wrap(__doc__)
+def main(args: yadopt.YadOptArgs, real_arg: str):
+    ...
+
+if __name__ == "__main__":
+    main("real argument")
+```
+
+### Dictionary and namedtuple support
+
+The returned value of `yadopt.parse` is an instance of `YadOptArgs` that is
+a normal mutable Python class. However, sometimes a dictionary that has
+the `get` accessor, or an immutable namedtuple, may be preferable.
+In that case, please try `.to_dict` and `.to_namedtuple` functions.
+
+```python
+# Convert the returned value to dictionary.
+args = yadopt.parse(__doc__).to_dict()
+
+# Convert the returned value to namedtuple.
+args = yadopt.parse(__doc__).to_namedtuple()
+```
+
+
+API
+--------------------------------------------------------------------------------
+
+### `yadopt.parse`
+
+```python
+yadopt.parse(
+    docstr: str,
+    argv: list[str] = None,
+    default_type: str = "auto",
+    force_continue: bool = False,
+) -> YadOptArgs
+```
+
+### Args
+
+| Name             | Type        | Default value | Description |
+|:-----------------|:-----------:|:-------------:|:------------|
+| `docstr`         | `str`       | -             | A help message string that will be parsed to create an object of command line arguments. We recommend to write a help message in the docstring of your Python script and use `__doc__` here. |
+| `argv`           | `list[str]` | `None`        | An argument vector to be parsed. YadOpt uses the command line arguments passed to your Python script, `sys.argv[1:]`, by default. |
+| `default_type`   | `str\|type` | `"auto"`      | Default data type of arguments and options. The default value `"auto"` means automatic determination. |
+| `force_continue` | `bool`      | `False`       | If `True`, do not exit the software regardless of whether YadOpt succeeds command line parsing or not. |
+
+### Returns
+
+The returned value is an instance of the `YadOptArgs` class that represents parsed
+command line arguments. The `YadOptArgs` class is a normal mutable Python
+class and users can access to parsed command line arguments by the dot notation.
+If you wish to convert `YadOptArgs` to dictionary type, please use `.to_dict()`
+function. Likewise, if you prefer an immutable data type, please try
+`.to_namedtuple()` function.
+
+### `yadopt.wrap`
+
+```python
+yadopt.wrap(*pargs, **kwargs) -> Callable
+```
+
+### Args
+
+The same as the arguments of `yadopt.parse` function.
+
+### Returns
+
+The `yadopt.wrap` is a Python decorator function that allows users to modify
+the behavior of functions or methods, therefore the returned value of this
+function is a callable object. The first argument of the target function of
+this decorator is curried by the result of `yadopt.parse` and the curried
+object will be returned.

yadopt-2024.10.5/README.md

@@ -0,0 +1,183 @@
+<div align="center">
+  <img src="figures/yadopt_logo.svg" width="90%">
+</div>
+
+<div align="center">
+  <img src="https://img.shields.io/badge/PYTHON-%3E%3D3.9-blue.svg?style=for-the-badge&logo=python&logoColor=white">
+  &nbsp;
+  <img src="https://img.shields.io/badge/LICENSE-MIT-orange.svg?style=for-the-badge">
+  &nbsp;
+  <img src="https://img.shields.io/badge/COVERAGE-96%25-green.svg?style=for-the-badge">
+  &nbsp;
+  <img src="https://img.shields.io/badge/QUALITY-9.94/10.0-yellow.svg?style=for-the-badge">
+</div>
+
+YadOpt - Yet another docopt
+================================================================================
+
+YadOpt is a Python re-implementation of [docopt](https://github.com/docopt/docopt)
+and [docopt-ng](https://github.com/jazzband/docopt-ng), a human-friendly
+command-line argument parser with type hinting and utility functions.
+YadOpt helps you to create beautiful command-line interfaces, just like docopt
+and docopt-ng, however, **YadOpt also supports date type hinting**.
+
+The following is the typical usage of YadOpt:
+
+```python
+"""
+Usage:
+    train.py <config_path> [--epochs INT] [--model STR] [--lr FLT]
+    train.py --help
+
+Train a neural network model.
+
+Arguments:
+    config_path     Path to config file.
+
+Training options:
+    --epochs INT    The number of training epochs.   [default: 100]
+    --model STR     Neural network model name.       [default: mlp]
+    --lr FLT        Learning rate.                   [default: 1.0E-3]
+
+Other options:
+    -h, --help      Show this help message and exit.
+"""
+
+import yadopt
+
+if __name__ == "__main__":
+    args = yadopt.parse(__doc__)
+    print(args)
+```
+
+Please save the above code as `sample.py`, and run it as follows:
+
+```console
+$ python3 sample.py config.toml --epochs 10 --model=cnn
+YadOptArgs(config_path=config.toml, epochs=10, model=cnn, lr=0.001, help=False)
+```
+
+In the above code, the parsed command-line arguments are stored in the `arg`
+and you can access each argument using dot notation, like `arg.config_path`.
+Also, the parsed command-line arguments are typed, in other words,
+the `arg` variable satisfies the following assertions:
+
+```python
+assert isinstance(args.config_path, pathlib.Path)
+assert isinstance(args.epochs, int)
+assert isinstance(args.model, str)
+assert isinstance(args.lr, float)
+assert isinstance(args.help, bool)
+```
+
+More realistic examples can be found in the [examples](./examples/README.md)
+directory.
+
+
+Installation
+--------------------------------------------------------------------------------
+
+Please install from [pip](https://pip.pypa.io/en/stable/).
+
+```console
+$ pip install yadopt
+```
+
+
+Usage
+--------------------------------------------------------------------------------
+
+### Use `parse` function
+
+The `yadopt.parse` function allows you to parse command-line arguments based on
+your docstring. The function is designed to parse `sys.argv` by default, but
+you can explicitly specify the argument vector by using the second argument
+of the function, just like as follows:
+
+```python
+# Parse sys.argv
+args = yadopt.parse(__doc__)
+
+# Parse the given argv.
+args = yadopt.parse(__doc__, argv)
+```
+
+### Use `wrap` function
+
+YadOpt supports the decorator approach for command-line parsing by the decorator
+`@yadopt.wrap` which takes the same arguments as the function `yadopt.parse`.
+
+```python
+@yadopt.wrap(__doc__)
+def main(args: yadopt.YadOptArgs, real_arg: str):
+    ...
+
+if __name__ == "__main__":
+    main("real argument")
+```
+
+### Dictionary and namedtuple support
+
+The returned value of `yadopt.parse` is an instance of `YadOptArgs` that is
+a normal mutable Python class. However, sometimes a dictionary that has
+the `get` accessor, or an immutable namedtuple, may be preferable.
+In that case, please try `.to_dict` and `.to_namedtuple` functions.
+
+```python
+# Convert the returned value to dictionary.
+args = yadopt.parse(__doc__).to_dict()
+
+# Convert the returned value to namedtuple.
+args = yadopt.parse(__doc__).to_namedtuple()
+```
+
+
+API
+--------------------------------------------------------------------------------
+
+### `yadopt.parse`
+
+```python
+yadopt.parse(
+    docstr: str,
+    argv: list[str] = None,
+    default_type: str = "auto",
+    force_continue: bool = False,
+) -> YadOptArgs
+```
+
+### Args
+
+| Name             | Type        | Default value | Description |
+|:-----------------|:-----------:|:-------------:|:------------|
+| `docstr`         | `str`       | -             | A help message string that will be parsed to create an object of command line arguments. We recommend to write a help message in the docstring of your Python script and use `__doc__` here. |
+| `argv`           | `list[str]` | `None`        | An argument vector to be parsed. YadOpt uses the command line arguments passed to your Python script, `sys.argv[1:]`, by default. |
+| `default_type`   | `str\|type` | `"auto"`      | Default data type of arguments and options. The default value `"auto"` means automatic determination. |
+| `force_continue` | `bool`      | `False`       | If `True`, do not exit the software regardless of whether YadOpt succeeds command line parsing or not. |
+
+### Returns
+
+The returned value is an instance of the `YadOptArgs` class that represents parsed
+command line arguments. The `YadOptArgs` class is a normal mutable Python
+class and users can access to parsed command line arguments by the dot notation.
+If you wish to convert `YadOptArgs` to dictionary type, please use `.to_dict()`
+function. Likewise, if you prefer an immutable data type, please try
+`.to_namedtuple()` function.
+
+### `yadopt.wrap`
+
+```python
+yadopt.wrap(*pargs, **kwargs) -> Callable
+```
+
+### Args
+
+The same as the arguments of `yadopt.parse` function.
+
+### Returns
+
+The `yadopt.wrap` is a Python decorator function that allows users to modify
+the behavior of functions or methods, therefore the returned value of this
+function is a callable object. The first argument of the target function of
+this decorator is curried by the result of `yadopt.parse` and the curried
+object will be returned.

yadopt-2024.10.5/examples/00_usage_in_readme.py

@@ -0,0 +1,27 @@
+"""
+Usage:
+    train.py <config_path> [--epochs INT] [--model STR] [--lr FLT]
+    train.py --help
+
+Train a neural network model.
+
+Arguments:
+    config_path     Path to config file.
+
+Training options:
+    --epochs INT    The number of training epochs.   [default: 100]
+    --model STR     Neural network model name.       [default: mlp]
+    --lr FLT        Learning rate.                   [default: 1.0E-3]
+
+Other options:
+    -h, --help      Show this help message and exit.
+"""
+
+import yadopt
+
+if __name__ == "__main__":
+    argv = ["train.py", "config.toml", "--epochs", "10", "--model=cnn"]
+    args = yadopt.parse(__doc__, argv)
+    print(args)
+
+# vim: expandtab tabstop=4 shiftwidth=4 fdm=marker

yadopt-2024.10.5/examples/01_type_hint.py

@@ -0,0 +1,47 @@
+"""
+Usage:
+    01_type_hint.py <config_path> [--epochs INT] [--model STR] [--lr FLT]
+    01_type_hint.py --help
+
+Train a neural network model.
+
+Arguments:
+    config_path     Path to config file.
+
+Training options:
+    --epochs INT    The number of training epochs.   [default: 100]
+    --model STR     Neural network model name.       [default: mlp]
+    --lr FLT        Learning rate.                   [default: 1.0E-3]
+
+Other options:
+    -h, --help      Show this help message and exit.
+"""
+
+# Import standard libraries.
+import pathlib
+
+# Import YadOpt.
+import yadopt
+
+
+def main():
+    """
+    Entry point of this script.
+    """
+    # Parse command line arguments using YadOpt.
+    args = yadopt.parse(__doc__)
+    print(args)
+
+    # Data type assertions.
+    assert isinstance(args.config_path, pathlib.Path)
+    assert isinstance(args.epochs, int)
+    assert isinstance(args.model, str)
+    assert isinstance(args.lr, float)
+    assert isinstance(args.help, bool)
+
+
+if __name__ == "__main__":
+    main()
+
+
+# vim: expandtab tabstop=4 shiftwidth=4 fdm=marker

yadopt-2024.10.5/examples/02_decorator.py

@@ -0,0 +1,39 @@
+"""
+Usage:
+    02_decorator.py <config_path> [--epochs INT] [--model STR] [--lr FLT]
+    02_decorator.py --help
+
+Train a neural network model.
+
+Arguments:
+    config_path     Path to config file.
+
+Training options:
+    --epochs INT    The number of training epochs.   [default: 100]
+    --model STR     Neural network model name.       [default: mlp]
+    --lr FLT        Learning rate.                   [default: 1.0E-3]
+
+Other options:
+    -h, --help      Show this help message and exit.
+"""
+
+# Import standard libraries.
+import pathlib
+
+# Import YadOpt.
+import yadopt
+
+
+@yadopt.wrap(__doc__)
+def main(args: yadopt.YadOptArgs):
+    """
+    Entry point of this script.
+    """
+    print(args)
+
+
+if __name__ == "__main__":
+    main()
+
+
+# vim: expandtab tabstop=4 shiftwidth=4 fdm=marker

yadopt-2024.10.5/examples/03_subcommand.py

@@ -0,0 +1,36 @@
+"""
+Usage:
+    03_subcommand.py foo [--foo_opt INT]
+    03_subcommand.py bar [--bar_opt INT]
+    03_subcommand.py --help
+
+Test of subcommand in YadOpt.
+
+Options:
+    --foo_opt INT   Options of subcommand foo.   [default: 0]
+    --bar_opt STR   Options of subcommand bar.   [default: 0]
+
+Other options:
+    -h, --help      Show this help message and exit.
+"""
+
+# Import standard libraries.
+import pathlib
+
+# Import YadOpt.
+import yadopt
+
+
+def main():
+    """
+    Entry point of this script.
+    """
+    args = yadopt.parse(__doc__)
+    print(args)
+
+
+if __name__ == "__main__":
+    main()
+
+
+# vim: expandtab tabstop=4 shiftwidth=4 fdm=marker

yadopt-2024.10.5/examples/README.md

@@ -0,0 +1,24 @@
+Examples
+================================================================================
+
+### 01_type_hint.py
+
+```console
+$ python3 01_type_hint.py config.toml --epochs 10 --model cnn --lr 0.01
+YadOptArgs(config_path=config.toml, epochs=10, model=cnn, lr=0.01, help=False)
+```
+
+### 02_decorator.py
+
+```console
+$ python3 02_decorator.py config.toml --epochs 10 --model cnn --lr 0.01
+YadOptArgs(config_path=config.toml, epochs=10, model=cnn, lr=0.01, help=False)
+```
+
+### 03_sub_command.py
+
+```console
+$ python3 03_subcommand.py foo --foo_opt 10
+YadOptArgs(foo_opt=0, bar_opt=0, help=False, foo=True)
+```
+