Metadata-Version: 2.1
Name: clidesc
Version: 0.1.0
Summary: An automatic CLI interface framework.
Home-page: https://github.com/rafasgj/clidesc
Author: Rafael Guterres Jeffman
Author-email: rafasgj@gmail.com
License: GPLv3
Project-URL: Bug Tracker, https://github.com/rafasgj/clidesc/issues
Project-URL: Changelog, https://github.com/rafasgj/clidesc/releases/latest
Keywords: ['CLI','Development Tool']
Platform: any
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: black ; extra == 'dev'
Requires-Dist: yamllint ; extra == 'dev'
Requires-Dist: flake8 ; extra == 'dev'
Requires-Dist: pylint ; extra == 'dev'
Requires-Dist: pydocstyle ; extra == 'dev'
Requires-Dist: behave ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: coverage ; extra == 'dev'
Provides-Extra: lint
Requires-Dist: black ; extra == 'lint'
Requires-Dist: yamllint ; extra == 'lint'
Requires-Dist: flake8 ; extra == 'lint'
Requires-Dist: pylint ; extra == 'lint'
Requires-Dist: pydocstyle ; extra == 'lint'
Provides-Extra: test
Requires-Dist: behave ; extra == 'test'
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: coverage ; extra == 'test'

clidesc
=======

`clidesc` is a CLI interface framework that can be used to build simple,
yet functional, command line interfaces with minimal client code.

The goal is to create a framework to build the command line interface only
using configuration files (YAML or JSON format), and minimizing the need to
write code for it.


Usage
-----

To create a simple "Greeting" application, the CLI definition file, should
look like:

```yaml
---
program: greeting
description: A greeting application.
version: 1.0
handler: greeting.hello
arguments:
  - name: someone
    description: Someone to greet.
    type: string
    required: true
```

And the application code would be:

```python
# Contents of greeting.py

from clidesc import CLIDesc

def hello(someone):
    print(f"Hello, {someone}!")

if __name__ == "__main__":
    cli = CLIDesc.from_file("greeting.yml")
    cli.run()
```

With this configuration, the application will have options to display its
version (--version), help instructions (-h or --help), and a required
positional argument. If run with `--help`, the output is:

```
usage: greeting [-h] [--version] someone

A greeting application.

positional arguments:
  someone     Someone to greet.

optional arguments:
  -h, --help  show this help message and exit
  --version   display program version
```

If the application does not receive the required argument, an error is
displayed. For example, the output for running `greeting` is:

```
usage: greeting [-h] [--version] someone
greeting: error: the following arguments are required: someone
```

When running an application with one parameter, `greeting World`, the output
would be:

```
Hello, World!
```

You may also use `clidesc` to automatically format the output returned by
the handler methods. Use the `output` attribute along with the handler
method to configure the output format.

The next example configures the output format, with a formatting string,
that follows Python's formatting rules.

```yaml
---
program: output
description: Auto-formatting output.
version: 1.0
handler: output.hello
output:
  format: "Hello, {someone}"
arguments:
  - name: someone
    description: Someone to greet.
    required: true
```

And the code for this application would be:

```python
# contents of output.py.

from clidesc import CLIDesc


def hello(someone):
    """Greet someone."""
    return {"someone": someone}


if __name__ == "__main__":
    cli = CLIDesc.from_file('output.yaml'))
    cli.run()
```

Applications with multiple commands and command groups (like `git`) are
supported through `sub_commands`. Each `command` in `sub_command` can have
its own `sub_command`, creating a command hierarchy (deep hierarchies are
not recommended).

The configuration for such application would be:

```yaml
---
program: multi
description: A multi-command application.
version: 1.0
sub_commands:
  title: Commands
  description: Application sub-commands
  group_name: Sub commands
  commands:
    - name: abc
      description: First command.
      handler: multi.abc
      arguments:
      - name: some_arg
        description: Some argument.
    - name: xyz
      description: Second command.
      handler: multi.xyz
      arguments:
      - name: another_arg
        description: Another argument.
```

And the client code:

```python
# contents of multi.py

from clidesc import CLIDesc

def abc(some_arg):
    """Greet someone."""
    print(f"ABC: {some_arg}")


def xyz(another_arg):
    """Greet someone."""
    print(f"XYZ: {another_arg}")


if __name__ == "__main__":
    cli = CLIDesc.from_file("multi.yml")
    cli.run()
```


