https://github.com/sander76/clipstick
create cli applications using pydantic models
https://github.com/sander76/clipstick
cli click commandline pydantic typer
Last synced: 5 months ago
JSON representation
create cli applications using pydantic models
- Host: GitHub
- URL: https://github.com/sander76/clipstick
- Owner: sander76
- License: mit
- Created: 2023-09-26T15:04:50.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-06-25T11:05:16.000Z (almost 2 years ago)
- Last Synced: 2025-01-01T19:46:05.859Z (over 1 year ago)
- Topics: cli, click, commandline, pydantic, typer
- Language: Python
- Homepage: https://sander76.github.io/clipstick/
- Size: 2.96 MB
- Stars: 29
- Watchers: 2
- Forks: 3
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-pydantic - Clipstick - Clipstick creates 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. (Command-Line Interface)
README
[](https://pypi.org/project/clipstick/)
[](https://github.com/psf/black)
[](https://github.com/ambv/black)
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.
```python
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](https://brentyi.github.io/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](https://sander76.github.io/clipstick/index.html)
## 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!