sh40-carmine 0.3.5

The no-boilerplate CLI library powered by Python's introspection.

carmine

The no-boilerplate CLI library powered by Python's introspection.

pip install sh40-carmine

the context

CLIs (command line interfaces) are one of Python's longest standing issues. The builtin solution, argparse, is hard to understand & reason about, and doesn't even follow Python's own conventions in multiple places.

Alternative solutions often feel redundant and force you to define arguments twice - once in the function's definition, and another time as an CLI option.

Turns out, there's a better solution

the solution

carmine reads your functions signatures directly, removing the need to manually define option types. It also (optionally) uses type hints to automatically convert arguments given to the CLI to the types you expect them to be. All this is done with no modification to the syntax!

"""My Carmine app."""

import sys
from carmine import carmine_cli, Choice

def hello(name: str, *, age: int) -> None:
    """Says hello!

    Args:
        name: Your name.
        age: Your age.
    """

    print(f"Hello {name}, are you {age} years old?")

def goodbye(name: str, duration: Choice("for now", "forever")) -> None:
    """Says goodbye!

    Args:
        name: Your name.
        age: How long you're gonna leave for.
    """

    print(f"It's been nice knowing you, {name}!", end="")

    if duration == "for now":
        print("See you soon!")
    else:
        print("Eh, you'll be back soon enough.")

def main(argv: list[str] | sys.argv) -> None:
    """Runs the application."""

    with carmine_cli(__doc__, argv) as register:
        register(hello, goodbye)

single-command mode

Not every app needs to have multiple commands. If your app only registers one thing, carmine will no longer require a command selection, which keeps things cleaner.

"""My (simple) Carmine app.

This docstring won't be used in the help, as the sole command's overrules it.
"""

import sys
from carmine import carmine_cli, Choice


def multiply(a: int, b: int, *, power: bool = False) -> None:
    """Multiplies two numbers.

    Args:
        a: The first number.
        b: The second number.
        power: Interpret `b` as a power, rather than a factor.
    """

    result = a ** b if power else a * b
    print(result)

def main(argv: list[str] | sys.argv) -> None:
    """Runs the application."""

    with carmine_cli(__doc__, argv) as register:
        register(multiply)

examples