Skip to main content

A pydantic cli creation tool based on Pydantic models.

Project description

coverage PyPI - Version code style - black types - Mypy

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:

help_output

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

usage output

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

wrong age

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!

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

clipstick-0.6.1.tar.gz (14.3 kB view details)

Uploaded Source

Built Distribution

clipstick-0.6.1-py3-none-any.whl (15.2 kB view details)

Uploaded Python 3

File details

Details for the file clipstick-0.6.1.tar.gz.

File metadata

  • Download URL: clipstick-0.6.1.tar.gz
  • Upload date:
  • Size: 14.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.2 CPython/3.11.8 Linux/6.5.0-1016-azure

File hashes

Hashes for clipstick-0.6.1.tar.gz
Algorithm Hash digest
SHA256 f7cd156b3d82554463d410b49cc063fa7cd19e2389a5a518954c443b8a9807c5
MD5 84eee4d151787f87170c006f82fd4dc4
BLAKE2b-256 014a75821a6eafb7759ee8fb18767e2d585acaf5eb6d650750cf863a5291a2c0

See more details on using hashes here.

File details

Details for the file clipstick-0.6.1-py3-none-any.whl.

File metadata

  • Download URL: clipstick-0.6.1-py3-none-any.whl
  • Upload date:
  • Size: 15.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.2 CPython/3.11.8 Linux/6.5.0-1016-azure

File hashes

Hashes for clipstick-0.6.1-py3-none-any.whl
Algorithm Hash digest
SHA256 ae014e1e607019cc6e50869a08064b3da16a56021579c94d710aec9b3a5cd4d8
MD5 a5ae5ffa7fe3e9163b9e6403f85867ac
BLAKE2b-256 68ef83cf571a61bd505abb19b18a5f8e621a2e0633ff6f0a25b20ebd75b2de6a

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page