clipstick 0.6.1

A pydantic cli creation tool based on Pydantic models.

Create your cli using Pydantic models.

Define a pydantic model as you would normally do, pass it to clipstick and you get a cli including subcommands, nice docstrings and validations based on typing and pydantic validators.

Installation

pip install clipstick

Example

Create a pydantic model as you would normally do.

from pydantic import BaseModel

from clipstick import parse


class MyName(BaseModel):
    """What is my name.

    In case you forgot I will repeat it x times.
    """

    name: str
    """Your name."""

    age: int = 24
    """Your age"""

    repeat_count: int = 10
    """How many times to repeat your name."""

    def main(self):
        for _ in range(self.repeat_count):
            print(f"Hello: {self.name}, you are {self.age} years old")


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

That's it. The clipstick parser will convert this into a command line interface based on the properties assigned to the model, the provided typing and docstrings.

So python examples/name.py -h gives you nicely formatted (and colored) output:

And use your cli python examples/name.py superman --repeat-count 4:

The provided annotations define the type to which your arguments need to be converted. If you provide a value which cannot be converted you will be presented with a nice error:

python examples/name.py superman --age too-old

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.

Why?

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, which is excellent and 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.

Some other similar tools don't support pydantic v2, so I decided to create my own. Next to that I wanted to try and build my own parser instead of using Argparse because... why not.

For more information visit the documentation

Development

Pull requests are very much appreciated! Some guidance:

• Fork this repo and use this to create your branch based on the dev branch.
• This project makes use of Poetry. Poetry install to install everything need for development.
• This project makes use of Nox. nox -s test and nox -s quality are your friends here.
• Please update the CHANGELOG.md file with your changes under ## [Unreleased] section.
• When finished, point your pull-request towards the dev dev branch.

Thanks!