Cliar

Cliar is a Python package to help you create commandline interfaces. It focuses on simplicity and extensibility:

Creating a CLI is as simple as subclassing from cliar.Cliar.
Extending a CLI is as simple as subclassing from a cliar.Cliar subclass.

Cliar's mission is to let you focus on the business logic instead of building an interface for it. At the same time, Cliar doesn't want to stand in your way, so it provides the means to customize the generated CLI.

Installation

$ pip install cliar

Cliar requires Python 3.6+ and is tested on Windows, Linux, and macOS. There are no dependencies outside Python's standard library.

Basic Usage

Let's create a commandline calculator that adds two floats:

from cliar import Cliar


class Calculator(Cliar):
    '''Calculator app.'''

    def add(self, x: float, y: float):
        '''Add two numbers.'''

        print(f'The sum of {x} and {y} is {x+y}.')


if __name__ == '__main__':
    Calculator().parse()

Save this code to calc.py and run it. Try different inputs:

Valid input:

$ python calc.py add 12 34
The sum of 12.0 and 34.0 is 46.0.

Invalid input:

$ python calc.py add foo bar
usage: calc.py add [-h] x y
calc.py add: error: argument x: invalid float value: 'foo'

Help:

$ python calc.py -h
usage: calc.py [-h] {add} ...

Calculator app.

optional arguments:
-h, --help  show this help message and exit

commands:
{add}       Available commands:
    add       Add two numbers.

Help for add command:

$ python calc.py add -h
usage: calc.py add [-h] x y

Add two numbers.

positional arguments:
x
y

optional arguments:
-h, --help  show this help message and exit

A few things to note:

It's a regular Python class with a regular Python method. You don't need to learn any new syntax to use Cliar.
add method is converted to add command, its positional params are converted to positional commandline args.
There is no explicit conversion to float for x or y or error handling in the add method body. Instead, x and y are just treated as floats. Cliar converts the types using add's type hints. Invalid input doesn't even reach your code.
--help and -h flags are added automatically and the help messages are generated from the docstrings.

Setuptools and Poetry

To invoke your CLI via an entrypoint, wrap parse call in a function and point to it in your setup.py or pyproject.toml.

calc.py:

...
def entry_point():
    Calculator().parse()

setup.py:

setup(
    ...
    entry_points = {
        'console_scripts': ['calc=calc:entry_point'],
    }
    ...
)

pyproject.toml:

...
[tool.poetry.scripts]
calc = 'calc:entry_point'

Metadata

Release files for cliar 1.3.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cliar 1.3.5
File	Size	Uploaded
cliar-1.3.5.tar.gz	6.4 kB	Oct 21, 2021	Details

Built distribution (wheel)

Table of built distributions (wheels) for cliar 1.3.5
File	Interpreter	ABI	Platform	Reset
cliar-1.3.5-py3-none-any.whl 6.5 kB Oct 21, 2021	Python 3	none	any	Details

Total release size: 13.0 kB

Release files / cliar-1.3.5.tar.gz

Download URL	cliar-1.3.5.tar.gz
Size	6.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`5ff471cb78f1a191d62589f9722c2dd93fa50b803063a411e4fa28741e591633`
BLAKE2b-256 checksum How to use checksums	`bcc0e449bd83c9128c22cdd50e0dbc2b49b0c7fd980af765b35f492e37d0d95b`
Upload date	Oct 21, 2021
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.2.0a1 CPython/3.10.0 Windows/10`

Release files / cliar-1.3.5-py3-none-any.whl

Download URL	cliar-1.3.5-py3-none-any.whl
Size	6.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f6983c9a34c7be69f9679e7dce5aa05bd77ef61ec9dc85733d9d59a3c0b832be`
BLAKE2b-256 checksum How to use checksums	`fe0f03d0134bdb9e9c2ff4c43a25ff810ef61c16dba11f9c70110591f34a8340`
Upload date	Oct 21, 2021
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.2.0a1 CPython/3.10.0 Windows/10`