clipstick 0.2.0

A cli tool based on Pydantic models.

Clipstick

A cli-tool based on Pydantic models.

There are many other tools out there that do kind of the same, but they all don't do quite exactly what I want.

The goal of clipstip is to use pydantic to model your cli by leveraging:

• The automatic casting of input variables.
• The powerful validation capabilities.
• Docstrings as cli documentation.
• No other mental model required than Typing and Pydantic.

Clipstick is inspired by tyro. It is excellent and is more versatile than this tool. But in my opionion its primary focus is not building a cli tool along the lines of Argparse or Click, but more on composing complex objects from the command line. Making tyro behave like a "traditional" cli requires additional Annotation flags, which I don't want.

Installation

pip install clipstick

Example

# examples/simple.py

from pydantic import BaseModel
from clipstick import parse


class SimpleModel(BaseModel):
    """A simple model demonstrating clipstick.

    This is used in help as describing the main command.
    """

    name: str
    """Your name. This is used in help describing name."""

    repeat_count: int = 10
    """How many times to repeat your name. Used in help describing repeat_count."""

    def main(self):
        for _ in range(self.repeat_count):
            print(f"hello: {self.name}")


if __name__ == "__main__":
    model = parse(SimpleModel)
    model.main()

python examples/simple.py -h gives you:

usage: examples/simple.py [-h] name [--repeat-count]

A simple model demonstrating clipstick.

    This is used in help as describing the main command.
    

positional arguments:
    name                     Your name. This is used in help describing name. [str]

optional keyword arguments:
    --repeat-count           How many times to repeat your name. Used in help describing repeat_count. [int][default=10]

python examples/simple.py alex --repeat-count 3 gives you:

hello: alex
hello: alex
hello: alex

[!NOTE] The inclusion of the def main(self) method is not a requirement. clipstick generates a pydantic model based on provided cli arguments and gives it back to you for your further usage. Using def main() is one of the options to further process it.

Positional arguments

All properties in your pydantic model without a default value are converted to cli positional arguments.

# docs/source/positional_arg.py

from pydantic import BaseModel
from clipstick import parse


class MyModel(BaseModel):
    my_value: int


if __name__ == "__main__":
    """your cli entrypoint"""
    model = parse(MyModel)

# >>> python docs/source/positional_arg.py 10
MyModel(my_value=10)

Keyword arguments

All fields with a default value are converted to cli optional arguments.

# docs/source/keyword_arg.py

from pydantic import BaseModel
from clipstick import parse


class MyModel(BaseModel):
    my_value: int = 22


if __name__ == "__main__":
    model = parse(MyModel)

# >>> python docs/source/keyword_arg.py --my-value 10
MyModel(my_value=10)

Choices

Choices are supported by using the Literal type annotation.

# docs/source/choice_arg.py

from typing import Literal
from pydantic import BaseModel
from clipstick import parse


class MyModel(BaseModel):
    my_value: Literal["option1", "option2"] = "option1"


if __name__ == "__main__":
    model = parse(MyModel)

# >>> python docs/source/choice_arg.py --my-value option2
MyModel(my_value='option2')

Lists

Booleans/Flags

# docs/source/boolean_required_arg.py

from pydantic import BaseModel
from clipstick import parse


class MyModel(BaseModel):
    verbose: bool


if __name__ == "__main__":
    model = parse(MyModel)

# >>> python docs/source/boolean_required_arg.py --verbose
MyModel(verbose=True)

# >>> python docs/source/boolean_required_arg.py --no-verbose
MyModel(verbose=False)

Subcommands

Subcommands are possible by adding a property with a union of BaseModel, each defined as new path in the sub-command tree.

# docs/source/subcommand_arg.py

from pydantic import BaseModel
from clipstick import parse


class Routes(BaseModel):
    route_name: str


class Climbers(BaseModel):
    climber_name: str


class MyModel(BaseModel):
    """The base model with a subcommand."""

    sub_command: Routes | Climbers


if __name__ == "__main__":
    model = parse(MyModel)

# >>> python docs/source/subcommand_arg.py climbers Ondra
MyModel(sub_command=Climbers(climber_name='Ondra'))

• Only one subcommand per model is allowed. (If you need more (and want to follow the more object-composition path), have a look at tyro)
• sub_command as a name is not required. Any name will do.
• Nesting of subcommands is possible.