| Name | swiftcli JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Build testable CLI apps with `click` and `pydantic` |
| upload_time | 2025-01-03 00:13:50 |
| maintainer | None |
| docs_url | None |
| author | Or Levi |
| requires_python | <4.0,>=3.9 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# SwiftCLI
Build testable CLI apps with `click` and `pydantic`
`swiftcli` makes it easy to define CLI parameters with `pydantic` BaseModels, combining the power of `click` with `pydantic`'s data validation.
## Features
- Define CLI parameters using pydantic models
- Type validation and conversion out of the box
- Support for arguments, options, flags and switches
- Easy to test CLI applications
## Installation
```bash
pip install swiftcli
```
## Simple Example
```python
from pydantic import BaseModel
from swiftcli import BaseCommand, Group
from swiftcli.types import Argument, Option
class GreetParams(BaseModel):
name: Argument[str] # required argument
color: Option[str] = "" # Optional --color option with default value
class GreetCommand(BaseCommand[GreetParams]):
NAME = "greet"
def run(self) -> None:
if self.params.color:
print(f"Hello, {self.params.name}. You like the color {self.params.color}.")
else:
print(f"Hello, {self.params.name}.")
cli = Group()
cli.add_command_cls(GreetCommand)
if __name__ == "__main__":
cli()
```
## Parameter Types
SwiftCLI provides several parameter types through the `swiftcli.types` module:
### Argument
Required positional arguments:
```python
class MyParams(BaseModel):
filename: Argument[str] # Required positional argument
```
### Option
Optional named parameters with default values:
```python
class MyParams(BaseModel):
output: Option[str] = "output.txt" # --output option with default
count: Option[int] = 1 # --count option with default
```
### Flag
Boolean flags that can be enabled:
```python
class MyParams(BaseModel):
verbose: Flag # --verbose flag, defaults to False
```
### Switch
Enum-based switches that create multiple mutually exclusive flags:
```python
from enum import Enum
class LogLevel(str, Enum):
DEBUG = "debug"
INFO = "info"
ERROR = "error"
class MyParams(BaseModel):
log_level: Switch[LogLevel] = LogLevel.INFO # Creates --debug, --info, --error flags
```
## Advanced Usage
### Command Configuration
Commands can be configured using the CONFIG class variable:
```python
class MyCommand(BaseCommand[MyParams]):
NAME = "mycommand"
CONFIG = {
"help": "My command help text",
"short_help": "Short help",
"epilog": "Additional help text at the bottom",
"hidden": False,
"deprecated": False,
}
```
### Option Customization
Options can be customized using OptionSettings:
```python
from typing import Annotated
from swiftcli.types import OptionSettings
class MyParams(BaseModel):
verbose: Annotated[
int,
OptionSettings(
count=True, # Allow multiple flags (-vvv)
aliases=["-v"], # Add short alias
help="Sets the verbosity level"
)
] = 0
```
### Command Groups
Group multiple commands together:
```python
from swiftcli import Group
cli = Group()
cli.add_command_cls(CommandOne)
cli.add_command_cls(CommandTwo)
if __name__ == "__main__":
cli()
```
## Testing
SwiftCLI makes it easy to test your CLI applications:
```python
# Import the command we want to test
from my_cli.commands import MyCommand
# Test the command
def test_my_command():
# You can mock, stub, or read the stdout/err
# Run the command:
MyCommand(param1="a", param2="b").run()
```
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "swiftcli",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Or Levi",
"author_email": "orlevi128@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/20/34/51a495737a2e30d4da9a1b2ee79921e125eefeef1f2fca79de8b94020608/swiftcli-0.1.0.tar.gz",
"platform": null,
"description": "# SwiftCLI\nBuild testable CLI apps with `click` and `pydantic`\n\n`swiftcli` makes it easy to define CLI parameters with `pydantic` BaseModels, combining the power of `click` with `pydantic`'s data validation.\n\n## Features\n- Define CLI parameters using pydantic models\n- Type validation and conversion out of the box\n- Support for arguments, options, flags and switches\n- Easy to test CLI applications\n\n## Installation\n```bash\npip install swiftcli\n```\n\n## Simple Example\n```python\nfrom pydantic import BaseModel\n\nfrom swiftcli import BaseCommand, Group\nfrom swiftcli.types import Argument, Option\n\n\nclass GreetParams(BaseModel):\n name: Argument[str] # required argument\n color: Option[str] = \"\" # Optional --color option with default value\n\n\nclass GreetCommand(BaseCommand[GreetParams]):\n NAME = \"greet\"\n\n def run(self) -> None:\n if self.params.color:\n print(f\"Hello, {self.params.name}. You like the color {self.params.color}.\")\n else:\n print(f\"Hello, {self.params.name}.\")\n\n\ncli = Group()\ncli.add_command_cls(GreetCommand)\n\nif __name__ == \"__main__\":\n cli()\n```\n\n## Parameter Types\nSwiftCLI provides several parameter types through the `swiftcli.types` module:\n\n### Argument\nRequired positional arguments:\n```python\nclass MyParams(BaseModel):\n filename: Argument[str] # Required positional argument\n```\n\n### Option\nOptional named parameters with default values:\n```python\nclass MyParams(BaseModel):\n output: Option[str] = \"output.txt\" # --output option with default\n count: Option[int] = 1 # --count option with default\n```\n\n### Flag\nBoolean flags that can be enabled:\n```python\nclass MyParams(BaseModel):\n verbose: Flag # --verbose flag, defaults to False\n```\n\n### Switch\nEnum-based switches that create multiple mutually exclusive flags:\n```python\nfrom enum import Enum\n\nclass LogLevel(str, Enum):\n DEBUG = \"debug\"\n INFO = \"info\" \n ERROR = \"error\"\n\nclass MyParams(BaseModel):\n log_level: Switch[LogLevel] = LogLevel.INFO # Creates --debug, --info, --error flags\n```\n\n## Advanced Usage\n\n### Command Configuration\nCommands can be configured using the CONFIG class variable:\n\n```python\nclass MyCommand(BaseCommand[MyParams]):\n NAME = \"mycommand\"\n CONFIG = {\n \"help\": \"My command help text\",\n \"short_help\": \"Short help\",\n \"epilog\": \"Additional help text at the bottom\",\n \"hidden\": False,\n \"deprecated\": False,\n }\n```\n\n### Option Customization\nOptions can be customized using OptionSettings:\n\n```python\nfrom typing import Annotated\nfrom swiftcli.types import OptionSettings\n\nclass MyParams(BaseModel):\n verbose: Annotated[\n int,\n OptionSettings(\n count=True, # Allow multiple flags (-vvv)\n aliases=[\"-v\"], # Add short alias\n help=\"Sets the verbosity level\"\n )\n ] = 0\n```\n\n### Command Groups\nGroup multiple commands together:\n\n```python\nfrom swiftcli import Group\n\ncli = Group()\ncli.add_command_cls(CommandOne)\ncli.add_command_cls(CommandTwo)\n\nif __name__ == \"__main__\":\n cli()\n```\n\n## Testing\nSwiftCLI makes it easy to test your CLI applications:\n\n```python\n# Import the command we want to test\nfrom my_cli.commands import MyCommand\n\n# Test the command\ndef test_my_command():\n # You can mock, stub, or read the stdout/err\n # Run the command:\n MyCommand(param1=\"a\", param2=\"b\").run()\n```\n\n## License\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Build testable CLI apps with `click` and `pydantic`",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f76ce3821cbd8f0e9f4c8d7887edf27843c7d2b8c0891adf429d981cfd8239aa",
"md5": "c5fe4dbde0775d5761200f5d1090703f",
"sha256": "7d42a150521d2121597f3064459da4d1d0cedbecfb12ef90797e6f68c5e51ce5"
},
"downloads": -1,
"filename": "swiftcli-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c5fe4dbde0775d5761200f5d1090703f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 8258,
"upload_time": "2025-01-03T00:13:48",
"upload_time_iso_8601": "2025-01-03T00:13:48.361499Z",
"url": "https://files.pythonhosted.org/packages/f7/6c/e3821cbd8f0e9f4c8d7887edf27843c7d2b8c0891adf429d981cfd8239aa/swiftcli-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "203451a495737a2e30d4da9a1b2ee79921e125eefeef1f2fca79de8b94020608",
"md5": "c3fea9633245c3b98fc6de87714bc819",
"sha256": "9b1a1da150553e9c4cd65db57f35db88c7126728105f8bb15e74bc8c2c10e05d"
},
"downloads": -1,
"filename": "swiftcli-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "c3fea9633245c3b98fc6de87714bc819",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 6225,
"upload_time": "2025-01-03T00:13:50",
"upload_time_iso_8601": "2025-01-03T00:13:50.654394Z",
"url": "https://files.pythonhosted.org/packages/20/34/51a495737a2e30d4da9a1b2ee79921e125eefeef1f2fca79de8b94020608/swiftcli-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-03 00:13:50",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "swiftcli"
}
