The best Python CLI library, arguably.
Project description
The best Python CLI library, arguably.
arguably
turns functions into command line interfaces (CLIs). arguably
has a tiny API and is extremely easy to
integrate. You can also use it directly through python3 -m arguably your_script.py
, more on that
here.
To use arguably
in a script, decorate any functions that should appear on the command line with @arguably.command
,
then call arguably.run()
. If multiple functions are decorated, they'll all appear as subcommands. You can even have
multiple levels of subcommands: def s3__ls()
becomes s3 ls
.
#!/usr/bin/env python3
import arguably
@arguably.command
def some_function(required, not_required=2, *others: int, option: float = 3.14):
"""
this function is on the command line!
Args:
required: a required parameter
not_required: this one isn't required, since it has a default
*others: all the other positional arguments go here
option: [-x] an option, short name is in brackets
"""
if __name__ == "__main__":
arguably.run()
becomes
user@machine:~$ ./intro.py -h
usage: intro.py [-h] [-x OPTION] required [not-required] [others ...]
this function is on the command line!
positional arguments:
required a required parameter (type: str)
not-required this one isn't required, since it has a default (type: int, default: 2)
others all the other positional arguments go here (type: int)
options:
-h, --help show this help message and exit
-x, --option OPTION an option, short name is in brackets (type: float, default: 3.14)
arguably
looks at any decorated functions and maps their arguments from Python to the CLI:
This Python ... | ... becomes this on the CLI. |
---|---|
positional args, no default required |
positional CLI args, required required |
positional args, with default not_required=2 |
positional CLI args, optional [not-required] |
positional args, variadic *others |
any extra positional CLI args [others ...] |
keyword-only arguments option |
command-line options [-x OPTION] |
arguably
uses your docstrings to automatically generate help messages. It supports all major formats for docstrings:
reStructuredText, Google, Numpydoc, and Epydoc.
Type annotations are optional, but arguably
can use them to automatically convert arguments. It has smart handling for
mapping built-in types to the command line, including tuple
, list
, enum.Enum
, and enum.Flag
.
There are also a few special behaviors you can attach to a parameter via Annotated[]
and the arguably.arg.*
functions. Using arguably.arg.builder()
, you can even build an object to pass in from the command line (using syntax
inspired by QEMU):
user@machine:~$ ./build.py --nic tap,model=e1000 --nic user,hostfwd=tcp::10022-:22
nic=[TapNic(model='e1000'), UserNic(hostfwd='tcp::10022-:22')]
No integration required
Don't want to write any code? Simply pass any Python script to arguably
to give it a command line interface.
user@machine:~$ python3 -m arguably party-trick.py -h
usage: party-trick [-h] [--version] command ...
this is the docstring for the whole script
positional arguments:
command
hello this is hello's docstring
goodbye any function from a script can be called
some-class so can any __init__ for objects defined in the script
some-class.func-static a @staticmethod on a class can be called
some-class.func-cls so can a @classmethod
options:
-h, --help show this help message and exit
--version show program's version number and exit
Installation
Install using pip install arguably
. If you want to install using conda
, please comment on
this issue.
Documentation
- Why arguably?: https://treykeown.github.io/arguably/why/
- Examples: https://treykeown.github.io/arguably/examples/
- Tutorial: https://treykeown.github.io/arguably/tutorial/intro/
- API Reference: https://treykeown.github.io/arguably/api-reference/
Dependencies
All of arguably
is built on top of argparse
. It has two dependencies:
docstring-parser
for parsing function docstringstyping-extensions
forAnnotated[]
support in Python 3.8 (only needed for that version)
Contributing
Ideas and help are very much appreciated! There's a guide for getting started with contributing to arguably
that shows
you how to run tests and pre-commit hooks.
- Contributing: https://treykeown.github.io/arguably/contributing/
Future roadmap
If you have any interest in these (either as a user or implementer), please leave a comment!
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.