| Name | xmlhelpy JSON |
| Version |
0.14.0
JSON |
| download |
| home_page | None |
| Summary | CLI wrapper supporting the xmlhelp interface. |
| upload_time | 2024-10-23 12:36:28 |
| maintainer | None |
| docs_url | None |
| author | Karlsruhe Institute of Technology |
| requires_python | <3.14,>=3.9 |
| license | Apache-2.0 |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# xmlhelpy
**xmlhelpy** is a wrapper library based on
[Click](https://github.com/pallets/click). Its main goal is to easily provide
the *xmlhelp* interface to any Python CLI tool. This interface can be used to
obtain a machine readable XML representation of tools and their parameters. The
XML representation can be used, for example, to generate GUIs on top of any
tool that provides it.
## Installation
xmlhelpy can be installed using `pip`, note that Python version **>=3.9** is
required to install the latest version:
```shell
pip install xmlhelpy
```
When installing xmlhelpy from source for development, it is recommended to
install it in editable mode and to install all additional development
dependencies as defined in `pyproject.toml`:
```shell
pip install -e .[dev]
```
Performing the development installation inside a virtual environment is
recommended, see [Virtualenv](https://virtualenv.pypa.io/en/latest
"Virtualenv") for more information.
## Usage
### Quickstart
In essence, xmlhelpy works very similarly to Click, as the following example
taken from the Click documentation shows:
```python
import click
import xmlhelpy
@xmlhelpy.command()
@xmlhelpy.argument(
"count",
description="Number of greetings.",
param_type=xmlhelpy.Integer,
)
@xmlhelpy.option(
"name",
description="Your name.",
default="me",
)
def hello(count, name):
"""Simple program that greets NAME for a total of COUNT times.
A slightly modified example taken from Click.
"""
for x in range(count):
click.echo(f"Hello {name}!")
if __name__ == "__main__":
hello()
```
And when running it, assuming the code above was saved as `hello.py`:
```shell
$ python hello.py 2
Hello me!
Hello me!
```
The main functionality xmlhelpy provides on top of the usual Click
functionality is the `--xmlhelp` option:
```xml
$ python hello.py --xmlhelp
<?xml version='1.0' encoding='UTF-8'?>
<program name="hello" description="Simple program that greets NAME for a total of COUNT times.">
<param description="Number of greetings." type="long" name="arg0" positional="true" required="true"/>
<param description="Your name." type="string" name="name" default="me"/>
</program>
```
With this option, a machine readable representation of the `hello` command and
its parameters can be obtained without writing any additional code.
The rest of this documentation focuses on the specific functionality that
xmlhelpy provides. Please refer to the
[Click](https://click.palletsprojects.com) documentation for more general
usage.
### Builtin options
Besides the usual `--help` option that Click provides, xmlhelpy provides the
following:
* `--xmlhelp`: Prints a machine readable representation of a command or
environment and their parameters.
* `--version`: Prints the version of a group, command or environment, if
specified.
* `--commands`: Prints a list of all subcommands a group contains.
### Commands
xmlhelpy provides three different command types: *groups*, regular *commands*
and *environments*.
Similar to Click, groups can be used to easily group related commands into
multiple subcommands. Environments, on the other hand, are commands that are
meant to wrap other commands, e.g. an *ssh* tool to execute another command on
a remote machine. Environments are almost identical to regular commands, with
the exception that they also contain the required `--env-exec` option, which
specifies one or more command strings to be executed inside the environment.
The following code shows an example of each command type:
```python
@xmlhelpy.group(
name=None,
version=None,
cls=xmlhelpy.Group,
)
def my_group():
"""My group."""
@my_group.command(
name=None,
version=None,
description=None,
example=None,
cls=xmlhelpy.Command,
)
def my_command():
"""My command."""
@my_group.environment(
name=None,
version=None,
description=None,
example=None,
cls=xmlhelpy.Environment,
)
def my_environment(env_exec):
"""My environment."""
```
All command types provide the following parameters:
* `name`: The name of the command, which defaults to the name of the function
with underscores replaced by dashes.
* `version`: The version of the command. Subcommands can override the version
of their parent groups, otherwise it is inherited.
* `cls`: A custom command class to customize the command behaviour.
Commands and environments additionally provide the following parameters:
* `description`: The description of the command to be shown in the xmlhelp.
Defaults to the first line of the docstring of the function.
* `example`: An example parametrization of using the command.
### Parameters
Similar to Click, xmlhelpy provides *argument* and *option* parameters.
Arguments are required, positional parameters, while options are always given
by their name.
The following code shows an example of each parameter type:
```python
@xmlhelpy.command()
@xmlhelpy.argument(
"arg",
description="",
nargs=1,
param_type=xmlhelpy.String,
required=True,
default=None,
exclude_from_xml=False,
)
@xmlhelpy.option(
"opt",
description="",
nargs=1,
param_type=xmlhelpy.String,
required=False,
default=None,
exclude_from_xml=False,
char=None,
var_name=None,
is_flag=False,
requires=None,
excludes=None,
)
def my_command(**kwargs):
pass
```
Both parameter types provide the following parameters:
* `name`: The name of the parameter, which will also be used for the variable
name, with dashes replaced by underscores. The names of options have to be
given as `--<name> <value>`.
* `description`: The description of the parameter.
* `nargs`: The number of arguments (separated by spaces) to expect. If larger
than `1`, the variable in the decorated function will be a tuple. For
arguments, `-1` can be specified for a single argument to allow for an
unlimited number of values.
* `param_type`: The type of the parameter, either as class or instance.
* `required`: Whether the parameter is required or not. Defaults to `True` for
arguments.
* `default`: The default value to take if the parameter is not given.
* `exclude_from_xml`: Flag indicating whether the parameter should be excluded
from the xmlhelp output.
Options additionally provide the following parameters:
* `char`: A shorthand for an option consisting of a single ASCII letter, which
has to be given as `-<char> <value>`.
* `var_name`: A custom variable name to use in the decorated function instead
of the parameter name.
* `is_flag`: Whether the option is a flag. Flags do not require a value. They
always use boolean types and `False` as default value. Additionally, their
type is specified as `flag` in the xmlhelp.
* `requires`: A list of option names which should be required when using this
option.
* `excludes`: A list of option names which should be excluded when using this
option.
### Parameter types
xmlhelpy wraps most of the parameter types that also exist in Click. All types
can be specified for both arguments and options. Types can either be given as
classes or as instances.
The following code shows an example of the different parameter types:
```python
@xmlhelpy.command()
@xmlhelpy.argument("string", param_type=xmlhelpy.String)
@xmlhelpy.argument("tokenlist", param_type=xmlhelpy.TokenList(separator=","))
@xmlhelpy.argument("bool", param_type=xmlhelpy.Bool)
@xmlhelpy.argument("long", param_type=xmlhelpy.Integer)
@xmlhelpy.argument("long_range", param_type=xmlhelpy.IntRange(min=None, max=None))
@xmlhelpy.argument("real", param_type=xmlhelpy.Float)
@xmlhelpy.argument("real_range", param_type=xmlhelpy.FloatRange(min=None, max=None))
@xmlhelpy.argument("choice", param_type=xmlhelpy.Choice(["a", "b"], case_sensitive=False))
@xmlhelpy.argument("path", param_type=xmlhelpy.Path(path_type=None, exists=False))
def my_command(**kwargs):
pass
```
The provided types can be used for the following cases:
* `String`: For simple string values.
* `TokenList`: For string values that should be converted to a list according
to a given separator.
* `Bool`: For simple boolean values.
* `Integer`: For simple integer values.
* `IntRange`: For integer values in a certain range.
* `Float`: For simple float values.
* `FloatRange`: For float values in a certain range.
* `Choice`: For string values that can be selected from a specific list, either
case sensitive or insensitive.
* `Path`: For path values that can optionally be checked for whether they
actually exist. The given path type can optionally be set to either `file` or
`directory`, which sets the type in the xmlhelp accordingly and is also
relevant for the check mentioned above.
Raw data
{
"_id": null,
"home_page": null,
"name": "xmlhelpy",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Karlsruhe Institute of Technology",
"author_email": null,
"download_url": null,
"platform": null,
"description": "# xmlhelpy\n\n**xmlhelpy** is a wrapper library based on\n[Click](https://github.com/pallets/click). Its main goal is to easily provide\nthe *xmlhelp* interface to any Python CLI tool. This interface can be used to\nobtain a machine readable XML representation of tools and their parameters. The\nXML representation can be used, for example, to generate GUIs on top of any\ntool that provides it.\n\n## Installation\n\nxmlhelpy can be installed using `pip`, note that Python version **>=3.9** is\nrequired to install the latest version:\n\n```shell\npip install xmlhelpy\n```\n\nWhen installing xmlhelpy from source for development, it is recommended to\ninstall it in editable mode and to install all additional development\ndependencies as defined in `pyproject.toml`:\n\n```shell\npip install -e .[dev]\n```\n\nPerforming the development installation inside a virtual environment is\nrecommended, see [Virtualenv](https://virtualenv.pypa.io/en/latest\n\"Virtualenv\") for more information.\n\n## Usage\n\n### Quickstart\n\nIn essence, xmlhelpy works very similarly to Click, as the following example\ntaken from the Click documentation shows:\n\n```python\nimport click\nimport xmlhelpy\n\n\n@xmlhelpy.command()\n@xmlhelpy.argument(\n \"count\",\n description=\"Number of greetings.\",\n param_type=xmlhelpy.Integer,\n)\n@xmlhelpy.option(\n \"name\",\n description=\"Your name.\",\n default=\"me\",\n)\ndef hello(count, name):\n \"\"\"Simple program that greets NAME for a total of COUNT times.\n\n A slightly modified example taken from Click.\n \"\"\"\n for x in range(count):\n click.echo(f\"Hello {name}!\")\n\n\nif __name__ == \"__main__\":\n hello()\n```\n\nAnd when running it, assuming the code above was saved as `hello.py`:\n\n```shell\n$ python hello.py 2\nHello me!\nHello me!\n```\n\nThe main functionality xmlhelpy provides on top of the usual Click\nfunctionality is the `--xmlhelp` option:\n\n```xml\n$ python hello.py --xmlhelp\n<?xml version='1.0' encoding='UTF-8'?>\n<program name=\"hello\" description=\"Simple program that greets NAME for a total of COUNT times.\">\n <param description=\"Number of greetings.\" type=\"long\" name=\"arg0\" positional=\"true\" required=\"true\"/>\n <param description=\"Your name.\" type=\"string\" name=\"name\" default=\"me\"/>\n</program>\n\n```\n\nWith this option, a machine readable representation of the `hello` command and\nits parameters can be obtained without writing any additional code.\n\nThe rest of this documentation focuses on the specific functionality that\nxmlhelpy provides. Please refer to the\n[Click](https://click.palletsprojects.com) documentation for more general\nusage.\n\n### Builtin options\n\nBesides the usual `--help` option that Click provides, xmlhelpy provides the\nfollowing:\n\n* `--xmlhelp`: Prints a machine readable representation of a command or\n environment and their parameters.\n* `--version`: Prints the version of a group, command or environment, if\n specified.\n* `--commands`: Prints a list of all subcommands a group contains.\n\n### Commands\n\nxmlhelpy provides three different command types: *groups*, regular *commands*\nand *environments*.\n\nSimilar to Click, groups can be used to easily group related commands into\nmultiple subcommands. Environments, on the other hand, are commands that are\nmeant to wrap other commands, e.g. an *ssh* tool to execute another command on\na remote machine. Environments are almost identical to regular commands, with\nthe exception that they also contain the required `--env-exec` option, which\nspecifies one or more command strings to be executed inside the environment.\n\nThe following code shows an example of each command type:\n\n```python\n@xmlhelpy.group(\n name=None,\n version=None,\n cls=xmlhelpy.Group,\n)\ndef my_group():\n \"\"\"My group.\"\"\"\n\n\n@my_group.command(\n name=None,\n version=None,\n description=None,\n example=None,\n cls=xmlhelpy.Command,\n)\ndef my_command():\n \"\"\"My command.\"\"\"\n\n\n@my_group.environment(\n name=None,\n version=None,\n description=None,\n example=None,\n cls=xmlhelpy.Environment,\n)\ndef my_environment(env_exec):\n \"\"\"My environment.\"\"\"\n```\n\nAll command types provide the following parameters:\n\n* `name`: The name of the command, which defaults to the name of the function\n with underscores replaced by dashes.\n* `version`: The version of the command. Subcommands can override the version\n of their parent groups, otherwise it is inherited.\n* `cls`: A custom command class to customize the command behaviour.\n\nCommands and environments additionally provide the following parameters:\n\n* `description`: The description of the command to be shown in the xmlhelp.\n Defaults to the first line of the docstring of the function.\n* `example`: An example parametrization of using the command.\n\n### Parameters\n\nSimilar to Click, xmlhelpy provides *argument* and *option* parameters.\nArguments are required, positional parameters, while options are always given\nby their name.\n\nThe following code shows an example of each parameter type:\n\n```python\n@xmlhelpy.command()\n@xmlhelpy.argument(\n \"arg\",\n description=\"\",\n nargs=1,\n param_type=xmlhelpy.String,\n required=True,\n default=None,\n exclude_from_xml=False,\n)\n@xmlhelpy.option(\n \"opt\",\n description=\"\",\n nargs=1,\n param_type=xmlhelpy.String,\n required=False,\n default=None,\n exclude_from_xml=False,\n char=None,\n var_name=None,\n is_flag=False,\n requires=None,\n excludes=None,\n)\ndef my_command(**kwargs):\n pass\n```\n\nBoth parameter types provide the following parameters:\n\n* `name`: The name of the parameter, which will also be used for the variable\n name, with dashes replaced by underscores. The names of options have to be\n given as `--<name> <value>`.\n* `description`: The description of the parameter.\n* `nargs`: The number of arguments (separated by spaces) to expect. If larger\n than `1`, the variable in the decorated function will be a tuple. For\n arguments, `-1` can be specified for a single argument to allow for an\n unlimited number of values.\n* `param_type`: The type of the parameter, either as class or instance.\n* `required`: Whether the parameter is required or not. Defaults to `True` for\n arguments.\n* `default`: The default value to take if the parameter is not given.\n* `exclude_from_xml`: Flag indicating whether the parameter should be excluded\n from the xmlhelp output.\n\nOptions additionally provide the following parameters:\n\n* `char`: A shorthand for an option consisting of a single ASCII letter, which\n has to be given as `-<char> <value>`.\n* `var_name`: A custom variable name to use in the decorated function instead\n of the parameter name.\n* `is_flag`: Whether the option is a flag. Flags do not require a value. They\n always use boolean types and `False` as default value. Additionally, their\n type is specified as `flag` in the xmlhelp.\n* `requires`: A list of option names which should be required when using this\n option.\n* `excludes`: A list of option names which should be excluded when using this\n option.\n\n### Parameter types\n\nxmlhelpy wraps most of the parameter types that also exist in Click. All types\ncan be specified for both arguments and options. Types can either be given as\nclasses or as instances.\n\nThe following code shows an example of the different parameter types:\n\n```python\n@xmlhelpy.command()\n@xmlhelpy.argument(\"string\", param_type=xmlhelpy.String)\n@xmlhelpy.argument(\"tokenlist\", param_type=xmlhelpy.TokenList(separator=\",\"))\n@xmlhelpy.argument(\"bool\", param_type=xmlhelpy.Bool)\n@xmlhelpy.argument(\"long\", param_type=xmlhelpy.Integer)\n@xmlhelpy.argument(\"long_range\", param_type=xmlhelpy.IntRange(min=None, max=None))\n@xmlhelpy.argument(\"real\", param_type=xmlhelpy.Float)\n@xmlhelpy.argument(\"real_range\", param_type=xmlhelpy.FloatRange(min=None, max=None))\n@xmlhelpy.argument(\"choice\", param_type=xmlhelpy.Choice([\"a\", \"b\"], case_sensitive=False))\n@xmlhelpy.argument(\"path\", param_type=xmlhelpy.Path(path_type=None, exists=False))\ndef my_command(**kwargs):\n pass\n```\n\nThe provided types can be used for the following cases:\n\n* `String`: For simple string values.\n* `TokenList`: For string values that should be converted to a list according\n to a given separator.\n* `Bool`: For simple boolean values.\n* `Integer`: For simple integer values.\n* `IntRange`: For integer values in a certain range.\n* `Float`: For simple float values.\n* `FloatRange`: For float values in a certain range.\n* `Choice`: For string values that can be selected from a specific list, either\n case sensitive or insensitive.\n* `Path`: For path values that can optionally be checked for whether they\n actually exist. The given path type can optionally be set to either `file` or\n `directory`, which sets the type in the xmlhelp accordingly and is also\n relevant for the check mentioned above.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "CLI wrapper supporting the xmlhelp interface.",
"version": "0.14.0",
"project_urls": {
"Source": "https://gitlab.com/iam-cms/workflows/xmlhelpy"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b52ab4c1f909ced82563c2a20c3dfa4783b30eca78d4bf82a2735c456b328187",
"md5": "c35c65e1f2070efb19d119c22d75ca7d",
"sha256": "d99460782bf64713f7ca58fd520f76030c25db0b619557a8e87b3c3de37350f1"
},
"downloads": -1,
"filename": "xmlhelpy-0.14.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c35c65e1f2070efb19d119c22d75ca7d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.9",
"size": 18431,
"upload_time": "2024-10-23T12:36:28",
"upload_time_iso_8601": "2024-10-23T12:36:28.476947Z",
"url": "https://files.pythonhosted.org/packages/b5/2a/b4c1f909ced82563c2a20c3dfa4783b30eca78d4bf82a2735c456b328187/xmlhelpy-0.14.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-23 12:36:28",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "iam-cms",
"gitlab_project": "workflows",
"lcname": "xmlhelpy"
}
