| Name | cligen JSON |
| Version |
0.5.3
JSON |
| download |
| home_page | |
| Summary | generate __main__.py with argparse setup generated from YAML |
| upload_time | 2023-11-20 15:28:01 |
| maintainer | |
| docs_url | None |
| author | Anthon van der Neut |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
generate
cli
yaml
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# cligen
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/cligen)
[](https://bitbucket.org/ruamel/oitnb/)
cligen is is a utility to generate command-line parsing code, writing
your `__main__.py` from a specification in YAML. The generated
code requires Python 3.8+.
For a commandline utility `direction` that needs the subcommands `left`
and `right`, and where the subcommand `left` can have the option
`--u-turn` (assuming you drive on the right side of the road), and both
subcommands could have a `--verbose` option would look like:
!Cli 0:
- !Instance driving.Direction
- !Option [verbose, v, !Help increase verbosity level, !Action count]
- left:
- !Help turning to the left
- !Option [u-turn, U, !Type bool, !Help make a U-turn]
- right:
- !H turning to the right
with the result that `direction left -h` will show:
usage: direction left [-h] [--u-turn] [--verbose]
optional arguments:
-h, --help show this help message and exit
--u-turn, -U make a U-turn
--verbose, -v increase verbosity level
When `direction left` is called from the command-line, the code in `__main__.py`
will create an instance of the class `Direction` imported from `driving.py`, providing
the result of the parsing as argument to the intialisation,
and then call the method `left_subcommand` or method `left` (trying in that order) of that class.
`cligen` can alternatively generate code that calls functions
imported from a Python file, or call code inserted from the
YAML specification in `__main__.py` itself (in this case the `..._subcommand`
is not tried, and the results of parsing passed in to the function).
The YAML document can either be in a file `cli.yaml` on its own, or, if you
want to diminish file clutter in your project root, it can be stored in
the variable `_cligen_data` in `__init__.py`, this means between the
following two lines in that file:
```
_cligen_data = """\
"""
```
The YAML document uses
various tags, many of which have a short version (e.g. `!H` is equivalent
to using `!Help`).
Having the commandline options and argument data in a programmatically
modifiable format like YAML, makes it more easy to check or manipulate all
your utilities. E.g. if you want to make sure that all utilities that
have a `--verbose` option also have a `--quiet` option that
decreases the verbosity level.
## Feature list
- multiple long (`--date`) and short options (`-D`) can be associated with
one target.
- additional smart types/actions. E.g. an option with type 'date' defaults to `datetime.date.today()`
and you can specify an argument like `yesterday` or `-w-2` (two weeks ago)
- default values, with optionally some of the defaults defaults updated
from a configuration file (YAML/INI/PON)
- nested parsers for subcommands, and subcommands inheriting options
from their parent. This allows you to
insert parent options before or after the subcommand, without the cligen
code needing to re-arrange the commandline.
- an optional default subcommand/parser, which is used if unknown options/arguments
are found.
- Optional shorthands in the form of alternative executable names
for often used subcommand and/or options strings.
- no dependencies on anything but the Python standard library,
unless your config file is in a format that requires some installed
library ( YAML -\> ruamel.yaml )
- allow YAML aliases for tagged scalars to be used by other tags:
- !Help &xhelp text1 text2 text3 # this is the same as: "&xhelp !Help text1 text2 text3"
- !Prolog [*xhelp] # xhelp is a tagged scalar, "!Prolog *xhelp" would error
# the value for !Prolog is automatically un-sequenced
## Using !Config
In its most explicit form the tag `!Config` can takes a two element
sequence as value. The first element indicates the *type* (`pon`,
`yaml`, `ini`, TBI: `json`), the second the *path* to the file. A path
starting with a tilde (`~`) will be expanded. A path not starting with
tilde, or (forward-)slash (`/`), will be appended to your users config
directory.
If `!Config` is followed by a scalar that looks like a path (i.e. the
value starts with `~` or includes a `/`) the extension of the path is
taken to be the *type*. In other cases `!Config` is assumed to be
followed by a *type* and the basename is derived from the package name
(`_package_data['full_package_name']`) in your users config directory.
A user config directory is based on XDG config locations (on Windows,
the config information is expected under `%APPDATA%`)
When `!Config` is specified the inserted code will check for
`--config some_explicit_path` on the commandline and load the config
data from the path specified.
### config file format
Config files are assumed to contain a dictionary at the root level (for
formats like `.ini` the data is converted to a dictionary during
loading). This dictionary contains keys that correspond to the various
subparsers. A section `global` (or optionally `glbl` in PON to prevent
use of a reserved keyword, renamed to `global` after loading), is used
for defaults for options that come before the subparser as well as for
global options. Each section consists of key-value pairs, where the key
corresponds to a long option (`--verbose`) or if that is not available
the short option (`-v`), either without the leading dashes.
Assuming you have the following configuration:
!Cli 0:
- !Opt [verbose, v, !H increase verbosity, !Action count]
- !Config [pon, /usr/local/etc/myutil.pon]
- subp1: []
your `myutil.pon` can use:
dict(glbl=dict(verbose=2))
to set the verbosity (you might want to format your PON somewhat nicer.
The same with a YAML file:
!Cli 0:
- !Opt [verbose, v, !H increase verbosity, !Action count]
- !Config YAML
- subp1: []
your `~/.config/your_util_name/your_util_name.yaml` would be:
global:
verbose: 2
## argparse
An earlier version of cligen generated `argparse` commmands
in the `__main__.py` file. The current python output doesn't
use `argparse` anymore, resulting in code that is about twice as
big, but also twice as fast.
The old, unmaintained, code generator can be invoked by providing
`--type argparse`
Raw data
{
"_id": null,
"home_page": "",
"name": "cligen",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "generate cli yaml",
"author": "Anthon van der Neut",
"author_email": "a.van.der.neut@ruamel.eu",
"download_url": "https://files.pythonhosted.org/packages/6e/0b/cea24282d3ebadd5f35c3511469abe64a4840258ca29626e7d97b6d9ba08/cligen-0.5.3.tar.gz",
"platform": null,
"description": "\n# cligen\n\n[](https://opensource.org/licenses/MIT)\n[](https://pypi.org/project/cligen)\n[](https://bitbucket.org/ruamel/oitnb/)\n\ncligen is is a utility to generate command-line parsing code, writing\nyour `__main__.py` from a specification in YAML. The generated\ncode requires Python 3.8+.\n\nFor a commandline utility `direction` that needs the subcommands `left`\nand `right`, and where the subcommand `left` can have the option\n`--u-turn` (assuming you drive on the right side of the road), and both\nsubcommands could have a `--verbose` option would look like:\n\n !Cli 0:\n - !Instance driving.Direction\n - !Option [verbose, v, !Help increase verbosity level, !Action count]\n - left:\n - !Help turning to the left\n - !Option [u-turn, U, !Type bool, !Help make a U-turn]\n - right:\n - !H turning to the right\n\nwith the result that `direction left -h` will show:\n\n usage: direction left [-h] [--u-turn] [--verbose]\n\n optional arguments:\n -h, --help show this help message and exit\n --u-turn, -U make a U-turn\n --verbose, -v increase verbosity level\n\nWhen `direction left` is called from the command-line, the code in `__main__.py` \nwill create an instance of the class `Direction` imported from `driving.py`, providing\nthe result of the parsing as argument to the intialisation,\nand then call the method `left_subcommand` or method `left` (trying in that order) of that class. \n`cligen` can alternatively generate code that calls functions\nimported from a Python file, or call code inserted from the\nYAML specification in `__main__.py` itself (in this case the `..._subcommand` \nis not tried, and the results of parsing passed in to the function).\n\nThe YAML document can either be in a file `cli.yaml` on its own, or, if you\nwant to diminish file clutter in your project root, it can be stored in\nthe variable `_cligen_data` in `__init__.py`, this means between the\nfollowing two lines in that file:\n```\n_cligen_data = \"\"\"\\\n\"\"\"\n```\nThe YAML document uses\nvarious tags, many of which have a short version (e.g. `!H` is equivalent\nto using `!Help`).\n\nHaving the commandline options and argument data in a programmatically\nmodifiable format like YAML, makes it more easy to check or manipulate all\nyour utilities. E.g. if you want to make sure that all utilities that\nhave a `--verbose` option also have a `--quiet` option that\ndecreases the verbosity level.\n\n## Feature list\n- multiple long (`--date`) and short options (`-D`) can be associated with\n one target. \n\n- additional smart types/actions. E.g. an option with type 'date' defaults to `datetime.date.today()`\n and you can specify an argument like `yesterday` or `-w-2` (two weeks ago)\n\n- default values, with optionally some of the defaults defaults updated \n from a configuration file (YAML/INI/PON)\n\n- nested parsers for subcommands, and subcommands inheriting options \n from their parent. This allows you to\n insert parent options before or after the subcommand, without the cligen\n code needing to re-arrange the commandline.\n\n- an optional default subcommand/parser, which is used if unknown options/arguments\n are found. \n\n- Optional shorthands in the form of alternative executable names\n for often used subcommand and/or options strings. \n\n- no dependencies on anything but the Python standard library, \n unless your config file is in a format that requires some installed\n library ( YAML -\\> ruamel.yaml )\n\n- allow YAML aliases for tagged scalars to be used by other tags:\n\n - !Help &xhelp text1 text2 text3 # this is the same as: \"&xhelp !Help text1 text2 text3\"\n - !Prolog [*xhelp] # xhelp is a tagged scalar, \"!Prolog *xhelp\" would error\n # the value for !Prolog is automatically un-sequenced\n\n## Using !Config\n\nIn its most explicit form the tag `!Config` can takes a two element\nsequence as value. The first element indicates the *type* (`pon`,\n`yaml`, `ini`, TBI: `json`), the second the *path* to the file. A path\nstarting with a tilde (`~`) will be expanded. A path not starting with\ntilde, or (forward-)slash (`/`), will be appended to your users config\ndirectory.\n\nIf `!Config` is followed by a scalar that looks like a path (i.e. the\nvalue starts with `~` or includes a `/`) the extension of the path is\ntaken to be the *type*. In other cases `!Config` is assumed to be\nfollowed by a *type* and the basename is derived from the package name\n(`_package_data['full_package_name']`) in your users config directory.\n\nA user config directory is based on XDG config locations (on Windows,\nthe config information is expected under `%APPDATA%`)\n\nWhen `!Config` is specified the inserted code will check for\n`--config some_explicit_path` on the commandline and load the config\ndata from the path specified.\n\n### config file format\n\nConfig files are assumed to contain a dictionary at the root level (for\nformats like `.ini` the data is converted to a dictionary during\nloading). This dictionary contains keys that correspond to the various\nsubparsers. A section `global` (or optionally `glbl` in PON to prevent\nuse of a reserved keyword, renamed to `global` after loading), is used\nfor defaults for options that come before the subparser as well as for\nglobal options. Each section consists of key-value pairs, where the key\ncorresponds to a long option (`--verbose`) or if that is not available\nthe short option (`-v`), either without the leading dashes.\n\nAssuming you have the following configuration:\n\n !Cli 0:\n - !Opt [verbose, v, !H increase verbosity, !Action count]\n - !Config [pon, /usr/local/etc/myutil.pon]\n - subp1: []\n\nyour `myutil.pon` can use:\n\n dict(glbl=dict(verbose=2))\n\nto set the verbosity (you might want to format your PON somewhat nicer.\n\nThe same with a YAML file:\n\n !Cli 0:\n - !Opt [verbose, v, !H increase verbosity, !Action count]\n - !Config YAML\n - subp1: []\n\nyour `~/.config/your_util_name/your_util_name.yaml` would be:\n\n global:\n verbose: 2\n\n## argparse\n\nAn earlier version of cligen generated `argparse` commmands\nin the `__main__.py` file. The current python output doesn't \nuse `argparse` anymore, resulting in code that is about twice as \nbig, but also twice as fast.\n\nThe old, unmaintained, code generator can be invoked by providing\n`--type argparse`\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "generate __main__.py with argparse setup generated from YAML",
"version": "0.5.3",
"project_urls": {
"Documentation": "https://cligen.readthedocs.io/",
"Home": "https://sourceforge.net/p/ruamel-cligen/",
"Source": "https://sourceforge.net/p/ruamel-cligen/code/ci/default/tree/",
"Tracker": "https://sourceforge.net/p/ruamel-cligen/tickets/"
},
"split_keywords": [
"generate",
"cli",
"yaml"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "90617f2a00b07c65b7621b211b39e9b8083b0fdb43ab80b851614dfdd0f28836",
"md5": "756f3d9b1d6026ff101a51feae9e8b44",
"sha256": "487482b3129a00daae666e8ab501f8b5467543276851dc506bb511f6c499ee1a"
},
"downloads": -1,
"filename": "cligen-0.5.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "756f3d9b1d6026ff101a51feae9e8b44",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 44659,
"upload_time": "2023-11-20T15:27:59",
"upload_time_iso_8601": "2023-11-20T15:27:59.828074Z",
"url": "https://files.pythonhosted.org/packages/90/61/7f2a00b07c65b7621b211b39e9b8083b0fdb43ab80b851614dfdd0f28836/cligen-0.5.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6e0bcea24282d3ebadd5f35c3511469abe64a4840258ca29626e7d97b6d9ba08",
"md5": "74646cae06b39a8fb1035efe9583d26e",
"sha256": "848094d3e727dc90361b0a943151d85f7d7846eabd7f459a884eb4b3efce755c"
},
"downloads": -1,
"filename": "cligen-0.5.3.tar.gz",
"has_sig": false,
"md5_digest": "74646cae06b39a8fb1035efe9583d26e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 53196,
"upload_time": "2023-11-20T15:28:01",
"upload_time_iso_8601": "2023-11-20T15:28:01.917350Z",
"url": "https://files.pythonhosted.org/packages/6e/0b/cea24282d3ebadd5f35c3511469abe64a4840258ca29626e7d97b6d9ba08/cligen-0.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-20 15:28:01",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "cligen"
}
