# dcli
[](https://github.com/vNaonLu/dcli/actions)
**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](https://docs.python.org/3/library/argparse.html) in a decorator, i.e. `@dcli.command()`.
## Getting Started
Before installing, see [Requirements](#requirements) to check the dependencies.
See [Installation](#installation) to install **dcli** to your local environment and [Tutorial](#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**:
```sh
$ 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**
``` python
# 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](https://docs.python.org/3/library/argparse.html#argparse.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()](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.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`.
``` python
@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
``` python
# my-command.py
MyCommand()
```
``` sh
# 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`.
``` python
MyCommand("--foo")
MyCommand([])
MyCommand(["-x", "X"])
MyCommand(["-foo", "bar"])
```
**dcli** also provides subcommand creation. There are two ways to define subcommand.
- By decorated function
``` python
# 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
``` python
# 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.
``` python
# my-command.py
MyCommand()
```
``` sh
# 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/vNaonLu/dcli",
"name": "decorator-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "decorator cli",
"author": "Naon Lu",
"author_email": "vnaonlu0101453@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/7e/3e/995257c63e6d298231fe03204fb24a29f0435756934af786ce601df41b5b/decorator-cli-0.1.8.tar.gz",
"platform": null,
"description": "# dcli\n\n[](https://github.com/vNaonLu/dcli/actions)\n\n**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](https://docs.python.org/3/library/argparse.html) in a decorator, i.e. `@dcli.command()`.\n\n## Getting Started\n\nBefore installing, see [Requirements](#requirements) to check the dependencies.\n\nSee [Installation](#installation) to install **dcli** to your local environment and [Tutorial](#tutorial) for more information about how to use.\n\n\n## Requirements\n\nWhile **dcli** does not require any third-party, it requires run in Python with specific versions.\n\n- above Python 3.9\n\n## Installation\n\nOnly one step to install **dcli**:\n\n```sh\n$ python3 -m pip install decorator-cli\n\n# pip list to check installation\n$ python3 -m pip list\n\nPackage Version\n------------- ---------\ndecorator-cli <version>\n```\n\n## Tutorial\n\nTo create our own command `MyCommand` via **dcli**\n\n``` python\n# my-command.py\nimport dcli\n\n@dcli.command(\n \"MyCommand\",\n dcli.arg(\"-f\", \"--foo\", dest=\"bar\", default=False, action=\"store_true\",\n help=\"I am 'foo' identifier!\"),\n description=\"This is my command!\"\n)\ndef MyCommand(ns):\n print(\"Hello World\")\n print(\"--foo\", getattr(ns, \"bar\"))\n```\n\nThe only paremeter `ns` in `MyCommand` is type of `argparse.Namespace`, and will be passed from `parse_args()`. See [Namespace](https://docs.python.org/3/library/argparse.html#argparse.Namespace) for more information.\n\n`@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`.\n `dcli.arg()` just wraps the parameters from `argparse.ArgumentParser.add_argument()`, please see [add_argument()](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.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`. \n\n``` python\n@dcli.command(\n \"SomeCommand\"\n dcli.arg(\"--foo\", ...),\n dcli.arg(\"--bar\", ...),\n dcli.arg(\"--baz\", ...),\n ...\n)\ndef SomeCommand(ns):\n ...\n```\n\nOnce we defined our command `MyCommand`, we can easily trigger our command by\n\n``` python\n# my-command.py\nMyCommand()\n```\n\n``` sh\n# in shell\n# auto-generated help message.\n$ python3 path/to/my-command.py -h\nusage: MyCommand [-h] [-f]\n\nThis is my command!\n\noptions:\n -h, --help show this help message and exit\n -f, --foo I am 'foo' identifier!\n\n# pass some argument.\n$ python3 path/to/my-command.py -f\nHello World\n--foo True\n```\n\n`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`.\n\n``` python\nMyCommand(\"--foo\")\nMyCommand([])\nMyCommand([\"-x\", \"X\"])\nMyCommand([\"-foo\", \"bar\"])\n```\n\n**dcli** also provides subcommand creation. There are two ways to define subcommand.\n\n- By decorated function\n\n ``` python\n # my-command.py\n @dcli.command(\"sub1\", parent=MyCommand,\n help=\"I am sub command #1.\")\n def SubCommand1(ns):\n print(\"I am sub command #1.\")\n ```\n\n- By add manually\n\n ``` python\n # my-command.py\n @dcli.command(\"sub2\",\n help=\"I am sub command #2.\")\n def SubCommand2(ns):\n print(\"I am sub command #2.\")\n ...\n MyCommand.addSubCommand(SubCommand2)\n ```\n\nAnd trigger `MyCommand` as usual.\n\n``` python\n# my-command.py\nMyCommand()\n```\n\n``` sh\n# in shell\n# auto-generated help message.\n$ python3 path/to/my-command.py -h\nusage: MyCommand [-h] {sub1,sub2} ...\n\npositional arguments:\n {sub1,sub2}\n sub1 I am sub command #1.\n sub2 I am sub command #2.\n\noptions:\n -h, --help show this help message and exit\n\n# trigger subcommand\n$ python3 path/to/my-command.py sub1\nI am sub command #1.\n$ python3 path/to/my-command.py sub2\nI am sub command #2.\n```\n\nIt is possible to invoke `SubCommand1()` or `SubCommand2()` directly if you want to test them.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "functional-oriented cli decorator.",
"version": "0.1.8",
"project_urls": {
"Homepage": "https://github.com/vNaonLu/dcli"
},
"split_keywords": [
"decorator",
"cli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7e3e995257c63e6d298231fe03204fb24a29f0435756934af786ce601df41b5b",
"md5": "1e855057f84698e6c2078452dcf28477",
"sha256": "061f849c25ad64ea7a5a40d56986a8e5552a68de6433d730f29d8b619e0ae9b3"
},
"downloads": -1,
"filename": "decorator-cli-0.1.8.tar.gz",
"has_sig": false,
"md5_digest": "1e855057f84698e6c2078452dcf28477",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 6812,
"upload_time": "2024-03-23T13:17:36",
"upload_time_iso_8601": "2024-03-23T13:17:36.868926Z",
"url": "https://files.pythonhosted.org/packages/7e/3e/995257c63e6d298231fe03204fb24a29f0435756934af786ce601df41b5b/decorator-cli-0.1.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-23 13:17:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vNaonLu",
"github_project": "dcli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "decorator-cli"
}
JSON
