turns functions into command line interfaces
Project description
turns functions into command line interfaces
arguably
solves this problem:
- You've written a Python script
- Now you want to pass in parameters from the command line
- You don't want to read the docs for your favorite argument parsing library again
By leveraging as many Python idioms as possible, arguably
keeps its API small and memorable without sacrificing
funcitonality. arguably
uses functions and their docstrings to automatically set up argparse. Notably, arguably
maps your function signature to a command-line interface like this:
@arguably.command
def some_function(required, not_required="foo", *others, option="bar"):
...
becomes
usage: script [--option OPTION] required [not-required] [others ...]
In short, arguably
turns your function's positional parameters into positional command-line arguments, and
your function's keyword-only arguments into command-line options. From the example above:
Name | Type | Becomes | Usage |
---|---|---|---|
required |
positional, no default value | required positional arg | required |
not_required |
positional, with default value | optional positional arg | [not-required] |
others |
positional, variadic (like *args ) |
the rest of the positional args | [others ...] |
option |
keyword-only argument | an option | [--option OPTION] |
arguably
also enables you to easily add subcommands - just annotate more than one function with @arguably.command
.
You can even have nested subcommands (more on that later).
arguably
reads type annotations and automatically converts arguments to the declared types. It has smart handling for
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.
arguably
parses docstrings to generate descriptions for your commands and parameters. If you want to give a parameter
the alias -X
, prefix its docstring description with [-X]
. Wrapping a word in {}
changes the metavar that gets
printed (this is what's shown in the usage string after an option name, don't worry if you aren't familiar with this).
For example:
#!/usr/bin/env python3
"""docstrings for the file become the description for the script."""
__version__ = "1.0.0" # You can also set `version_flag=True` to add a version flag, it will read `__version__`
import arguably
@arguably.command(alias="h")
def hello(name: str, *, lastname: str | None = None):
"""
says hello to you
:param name: your name
:param lastname: [-l] your {surname}
"""
full_name = name if lastname is None else f"{name} {lastname}"
print(f"Hello, {full_name}!")
@arguably.command(alias="g")
def goodbye(name: str, *, is_sad: bool = False):
"""
says goodbye to you
:param name: your name
:param is_sad: [-s] whether or not it's sad to see you go
"""
print(f"Goodbye, {name}!")
if is_sad:
print(f"It's sad to see you go!")
if __name__ == "__main__":
arguably.run(version_flag=True)
becomes
user@machine:~$ python3 script.py
usage: test_scripts.docs2 [-h] [--version] command ...
docstrings for the file become the description for the script.
positional arguments:
command
hello (h) says hello to you
goodbye (g) says goodbye to you
options:
-h, --help show this help message and exit
--version show program's version number and exit
user@machine:~$ python3 script.py hello --help
usage: test_scripts.docs2 hello [-h] [-l SURNAME] name
says hello to you
positional arguments:
name your name
options:
-h, --help show this help message and exit
-l, --lastname SURNAME your surname (default: None)
More docs coming soon...
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.