[](https://pypi.org/project/clipstick/)
[](https://github.com/psf/black)
[](https://github.com/ambv/black)
<!-- begin index -->
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.
<!-- end index -->
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!
Raw data
{
"_id": null,
"home_page": "https://github.com/sander76/clipstick",
"name": "clipstick",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "pydantic cli,pydantic,cli,command line interface,argparse,click,typer",
"author": "Sander Teunissen",
"author_email": "s.teunissen@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/01/4a/75821a6eafb7759ee8fb18767e2d585acaf5eb6d650750cf863a5291a2c0/clipstick-0.6.1.tar.gz",
"platform": null,
"description": "\n[](https://pypi.org/project/clipstick/)\n[](https://github.com/psf/black)\n[](https://github.com/ambv/black)\n\n<!-- begin index -->\n\nCreate your cli using Pydantic models.\n\nDefine 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.\n\n## Installation\n\n`pip install clipstick`\n\n\n\n## Example\n\nCreate a pydantic model as you would normally do.\n\n```python\nfrom pydantic import BaseModel\n\nfrom clipstick import parse\n\n\nclass MyName(BaseModel):\n \"\"\"What is my name.\n\n In case you forgot I will repeat it x times.\n \"\"\"\n\n name: str\n \"\"\"Your name.\"\"\"\n\n age: int = 24\n \"\"\"Your age\"\"\"\n\n repeat_count: int = 10\n \"\"\"How many times to repeat your name.\"\"\"\n\n def main(self):\n for _ in range(self.repeat_count):\n print(f\"Hello: {self.name}, you are {self.age} years old\")\n\n\nif __name__ == \"__main__\":\n model = parse(MyName)\n model.main()\n\n```\n\nThat'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.\n\nSo `python examples/name.py -h` gives you nicely formatted (and colored) output:\n\n\n\nAnd use your cli `python examples/name.py superman --repeat-count 4`:\n\n\n\nThe provided annotations define the type to which your arguments need to be converted.\nIf you provide a value which cannot be converted you will be presented with a nice error:\n\n`python examples/name.py superman --age too-old`\n\n\n\n> 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.\n\n## Why?\n\nThere are many other tools out there that do kind of the same, \nbut they all don't do quite exactly what I want.\n\nThe goal of clipstip is to use pydantic to model your cli by leveraging:\n\n- The automatic casting of input variables.\n- The powerful validation capabilities.\n- Docstrings as cli documentation.\n- No other mental model required than Typing and Pydantic.\n\nClipstick 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.\n\nSome 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.\n\n<!-- end index -->\n\nFor more information visit the [documentation](https://sander76.github.io/clipstick/index.html)\n\n## Development\n\nPull requests are very much appreciated!\nSome guidance:\n\n- Fork this repo and use this to create your branch based on the `dev` branch.\n- This project makes use of **Poetry**. `Poetry install` to install everything\n need for development.\n- This project makes use of **Nox**. `nox -s test` and `nox -s quality` are your friends here.\n- Please update the `CHANGELOG.md` file with your changes under `## [Unreleased]` section.\n- When finished, point your pull-request towards the `dev` dev branch.\n\nThanks!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A pydantic cli creation tool based on Pydantic models.",
"version": "0.6.1",
"project_urls": {
"Documentation": "https://sander76.github.io/clipstick/index.html",
"Homepage": "https://github.com/sander76/clipstick",
"Repository": "https://github.com/sander76/clipstick"
},
"split_keywords": [
"pydantic cli",
"pydantic",
"cli",
"command line interface",
"argparse",
"click",
"typer"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "68ef83cf571a61bd505abb19b18a5f8e621a2e0633ff6f0a25b20ebd75b2de6a",
"md5": "a5ae5ffa7fe3e9163b9e6403f85867ac",
"sha256": "ae014e1e607019cc6e50869a08064b3da16a56021579c94d710aec9b3a5cd4d8"
},
"downloads": -1,
"filename": "clipstick-0.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a5ae5ffa7fe3e9163b9e6403f85867ac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 15205,
"upload_time": "2024-03-16T10:51:26",
"upload_time_iso_8601": "2024-03-16T10:51:26.268089Z",
"url": "https://files.pythonhosted.org/packages/68/ef/83cf571a61bd505abb19b18a5f8e621a2e0633ff6f0a25b20ebd75b2de6a/clipstick-0.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "014a75821a6eafb7759ee8fb18767e2d585acaf5eb6d650750cf863a5291a2c0",
"md5": "84eee4d151787f87170c006f82fd4dc4",
"sha256": "f7cd156b3d82554463d410b49cc063fa7cd19e2389a5a518954c443b8a9807c5"
},
"downloads": -1,
"filename": "clipstick-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "84eee4d151787f87170c006f82fd4dc4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 14254,
"upload_time": "2024-03-16T10:51:28",
"upload_time_iso_8601": "2024-03-16T10:51:28.402052Z",
"url": "https://files.pythonhosted.org/packages/01/4a/75821a6eafb7759ee8fb18767e2d585acaf5eb6d650750cf863a5291a2c0/clipstick-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-16 10:51:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sander76",
"github_project": "clipstick",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "clipstick"
}
JSON
