functional-oriented cli decorator.
Project description
dcli
dcli is a nested functional-oriented cli (command line interface) python module. dcli does not require any other third-party module, it just wraps and encapsolutes argparse in a decorator, i.e. @dcli.command()
.
Getting Started
Before installing, see Requirements to check the dependencies.
See Installation to install dcli to your local environment and Tutorial for more information about how to use.
Requirements
While dcli does not require any third-party, it requires run in Python with specific versions.
- above Python 3.9
Installation
Only one step to install dcli:
$ python3 -m pip install decorator-cli
# pip list to check installation
$ python3 -m pip list
Package Version
------------- ---------
decorator-cli <version>
Tutorial
To create our own command MyCommand
via dcli
# my-command.py
import dcli
@dcli.command(
"MyCommand",
dcli.arg("-f", "--foo", dest="bar", default=False, action="store_true",
help="I am 'foo' identifier!"),
description="This is my command!"
)
def MyCommand(ns):
print("Hello World")
print("--foo", getattr(ns, "bar"))
The only paremeter ns
in MyCommand
is type of argparse.Namespace
, and will be passed from parse_args()
. See Namespace for more information.
@dcli.command
encapsolutes the class argparse.ArgumentParser
, and all parameters from argparse.ArgumentParser
are available for @dcli.command
, just note that the parameters should be passed as kwargs
.
dcli.arg()
just wraps the parameters from argparse.ArgumentParser.add_argument()
, please see add_argument() for more information about how to add argument. In addition, it is possible to add multiple dcli.arg
in a single command @dcli.command
.
@dcli.command(
"SomeCommand"
dcli.arg("--foo", ...),
dcli.arg("--bar", ...),
dcli.arg("--baz", ...),
...
)
def SomeCommand(ns):
...
Once we defined our command MyCommand
, we can easily trigger our command by
# my-command.py
MyCommand()
# in shell
# auto-generated help message.
$ python3 path/to/my-command.py -h
usage: MyCommand [-h] [-f]
This is my command!
options:
-h, --help show this help message and exit
-f, --foo I am 'foo' identifier!
# pass some argument.
$ python3 path/to/my-command.py -f
Hello World
--foo True
MyCommand()
is a decorated function which combine parse_args()
and pass the result into the user-defined function. For advanced usage, if we need to do some test for MyCommand
, it is possible to pass an argument to it instead of a default value as sys.argv
.
MyCommand("--foo")
MyCommand([])
MyCommand(["-x", "X"])
MyCommand(["-foo", "bar"])
dcli also provides subcommand creation. There are two ways to define subcommand.
-
By decorated function
# my-command.py @dcli.command("sub1", parent=MyCommand, help="I am sub command #1.") def SubCommand1(ns): print("I am sub command #1.")
-
By add manually
# my-command.py @dcli.command("sub2", help="I am sub command #2.") def SubCommand2(ns): print("I am sub command #2.") ... MyCommand.addSubCommand(SubCommand2)
And trigger MyCommand
as usual.
# my-command.py
MyCommand()
# in shell
# auto-generated help message.
$ python3 path/to/my-command.py -h
usage: MyCommand [-h] {sub1,sub2} ...
positional arguments:
{sub1,sub2}
sub1 I am sub command #1.
sub2 I am sub command #2.
options:
-h, --help show this help message and exit
# trigger subcommand
$ python3 path/to/my-command.py sub1
I am sub command #1.
$ python3 path/to/my-command.py sub2
I am sub command #2.
It is possible to invoke SubCommand1()
or SubCommand2()
directly if you want to test them.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.