Yet another docopt, a human-friendly command line arguments parser.
Project description
YadOpt - Yet another docopt
YadOpt is a Python re-implementation of docopt and 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:
"""
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:
$ 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:
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 directory.
Installation
Please install from pip.
$ 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:
# 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
.
@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.
# 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
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
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for yadopt-2024.10.5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f82749fd2a5223cc50e926d0b57b5ecd4a3046c59e4080593c5906293db5b6e1 |
|
MD5 | 3d7ad24ced317e1a07aacae1da322303 |
|
BLAKE2b-256 | 4dbf60b92f19758dced382f089b230202daf96469fa84816bc4cfd43a603e57b |