brewing.cli

brewing.cli

A class-based command-line generator based on typer.

Note

The main goal of this functionality is to make it easier to build embedded command lines, so that for example you can provide a command line as part of a library, and make it easy for consumers to embed the command line into their own wider CLI application.

If you just want a simple CLI in the global scope of a python module, this package offers nothing compared to typer.

brewing's CLI class is an object-oriented wrapper around Tiangolo's Typer, which itself builds on PalletsProjects' click.

To write a CLI, simply inherit from brewing.cli.CLI, write a python class with type hints on the methods, and instantiate an instance of that class. brewing CLI will automatically build a CLI based on the public methods of the class.

from brewing import CLI, CLIOptions


class MyCLI(CLI[CLIOptions]):
    def greet(self, message: str):
        print("message")


cli = MyCLI(CLIOptions(name="mycli")).typer

typer is transparently used to parse the methods, so all of its documentation about how to declare arguments and options is applicable. To explicitely declare a parameter to be an option, use typing.Annotated with typer's Option class.

from typing import Annotated
from typer import Option
from brewing import CLI, CLIOptions


class MyCLI(CLI[CLIOptions]):
    def greet(self, message: [Annotated[str, Option()]]):
        print("message")

CLI(options, /, *children, help=None, extends=None, wraps=_self)

A class-based command-line generator based on typer.

Parameters:

Name	Type	Description	Default
options	OptionsT	Options for this CLI.	required
*children	CLI[Any]	CLI: Additional CLIs that should be nested inside this one.	()
help	str | None	(str | None): Help message to be displayed for the CLI; if not provided, class docstring will be used.	None
extends	Typer | CLI | None	If provided, a typer instance or another CLI to add commands to.	None
wraps	Any	Object to obtain CLI commands from. If not provided, self will be used.	_self

command_names property

Return list of all CLI command names.

name property

Read only name attribute.

Returns:

Name	Type	Description
str	str	The name of the CLI as provided at instantiation.

typer property

Read only name attribute.

Returns:

Name	Type	Description
Typer	Typer	the typer instance that the class wraps around, as generated or provided at instantiation.

__call__(*args, **kwargs)

Run the CLI.

__getattr__(name)

Proxy unknown methods onto typer.

This allows a CLI instance to be used precisely as a typer instance would be.

CLIOptions

Bases: NamedTuple

Minimal configuration options for a CLI.

ConflictingCommandError

Bases: ValueError

A conflict was found setting up the CLI.