Documentation: https://cyclopts.readthedocs.io
Source Code: https://github.com/BrianPugh/cyclopts
Cyclopts is a modern, easy-to-use command-line interface (CLI) framework that aims to provide an intuitive & efficient developer experience.
Why Cyclopts?
-
Intuitive API: Quickly write CLI applications using a terse, intuitive syntax.
-
Advanced Type Hinting: Full support of all builtin types and even user-specified (yes, including Pydantic, Dataclasses, and Attrs).
-
Rich Help Generation: Automatically generates beautiful help pages from docstrings and other contextual data.
-
Extendable: Easily customize converters, validators, token parsing, and application launching.
Installation
Cyclopts requires Python >=3.10; to install Cyclopts, run:
pip install cyclopts
Quick Start
- Import
cyclopts.run()and give it a function to run.
from cyclopts import run
def foo(loops: int):
for i in range(loops):
print(f"Looping! {i}")
run(foo)
Execute the script from the command line:
$ python start.py 3
Looping! 0
Looping! 1
Looping! 2
When you need more control:
- Create an application using
cyclopts.App. - Register commands with the
commanddecorator. - Register a default function with the
defaultdecorator.
from cyclopts import App
app = App()
@app.command
def foo(loops: int):
for i in range(loops):
print(f"Looping! {i}")
@app.default
def default_action():
print("Hello world! This runs when no command is specified.")
app()
Execute the script from the command line:
$ python demo.py
Hello world! This runs when no command is specified.
$ python demo.py foo 3
Looping! 0
Looping! 1
Looping! 2
With just a few additional lines of code, we have a full-featured CLI app. See the docs for more advanced usage.
Compared to Typer
Cyclopts is what you thought Typer was. Cyclopts's includes information from docstrings, support more complex types (even Unions and Literals!), and include proper validation support. See the documentation for a complete Typer comparison.
Consider the following short 29-line Cyclopts application:
import cyclopts
from typing import Literal
app = cyclopts.App()
@app.command
def deploy(
env: Literal["dev", "staging", "prod"],
replicas: int | Literal["default", "performance"] = "default",
):
"""Deploy code to an environment.
Parameters
----------
env
Environment to deploy to.
replicas
Number of workers to spin up.
"""
if replicas == "default":
replicas = 10
elif replicas == "performance":
replicas = 20
print(f"Deploying to {env} with {replicas} replicas.")
if __name__ == "__main__":
app()
$ my-script deploy --help
Usage: my-script.py deploy [ARGS] [OPTIONS]
Deploy code to an environment.
╭─ Parameters ────────────────────────────────────────────────────────────────────────────────────╮
│ * ENV --env Environment to deploy to. [choices: dev, staging, prod] [required] │
│ REPLICAS --replicas Number of workers to spin up. [choices: default, performance] [default: │
│ default] │
╰─────────────────────────────────────────────────────────────────────────────────────────────────╯
$ my-script deploy staging
Deploying to staging with 10 replicas.
$ my-script deploy staging 7
Deploying to staging with 7 replicas.
$ my-script deploy staging performance
Deploying to staging with 20 replicas.
$ my-script deploy nonexistent-env
╭─ Error ────────────────────────────────────────────────────────────────────────────────────────────╮
│ Error converting value "nonexistent-env" to typing.Literal['dev', 'staging', 'prod'] for "--env". │
╰────────────────────────────────────────────────────────────────────────────────────────────────────╯
$ my-script --version
0.0.0
In its current state, this application would be impossible to implement in Typer. However, lets see how close we can get with Typer (47-lines):
import typer
from typing import Annotated, Literal
from enum import Enum
app = typer.Typer()
class Environment(str, Enum):
dev = "dev"
staging = "staging"
prod = "prod"
def replica_parser(value: str):
if value == "default":
return 10
elif value == "performance":
return 20
else:
return int(value)
def _version_callback(value: bool):
if value:
print("0.0.0")
raise typer.Exit()
@app.callback()
def callback(
version: Annotated[
bool | None, typer.Option("--version", callback=_version_callback)
] = None,
):
pass
@app.command(help="Deploy code to an environment.")
def deploy(
env: Annotated[Environment, typer.Argument(help="Environment to deploy to.")],
replicas: Annotated[
int,
typer.Argument(
parser=replica_parser,
help="Number of workers to spin up.",
),
] = replica_parser("default"),
):
print(f"Deploying to {env.name} with {replicas} replicas.")
if __name__ == "__main__":
app()
$ my-script deploy --help
Usage: my-script deploy [OPTIONS] ENV:{dev|staging|prod} [REPLICAS]
Deploy code to an environment.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────╮
│ * env ENV:{dev|staging|prod} Environment to deploy to. [default: None] [required] │
│ replicas [REPLICAS] Number of workers to spin up. [default: 10] │
╰─────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────────────────────────────────╯
$ my-script deploy staging
Deploying to staging with 10 replicas.
$ my-script deploy staging 7
Deploying to staging with 7 replicas.
$ my-script deploy staging performance
Deploying to staging with 20 replicas.
$ my-script deploy nonexistent-env
Usage: my-script.py deploy [OPTIONS] ENV:{dev|staging|prod} [REPLICAS]
Try 'my-script.py deploy --help' for help.
╭─ Error ─────────────────────────────────────────────────────────────────────────────────────────╮
│ Invalid value for '[REPLICAS]': nonexistent-env │
╰─────────────────────────────────────────────────────────────────────────────────────────────────╯
$ my-script --version
0.0.0
The Typer implementation is 47 lines long, while the Cyclopts implementation is just 29 (38% shorter!).
Not only is the Cyclopts implementation significantly shorter, but the code is easier to read.
Since Typer does not support Unions, the choices for replica could not be displayed on the help page.
Cyclopts is much more terse, much more readable, and much more intuitive to use.
Contributing
Contributions are welcome! See CONTRIBUTING.md for development setup, coding standards, and how to submit a pull request.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file cyclopts-4.23.2.tar.gz.
File metadata
- Download URL: cyclopts-4.23.2.tar.gz
- Upload date:
- Size: 196.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1c9de7f245394d3ef9344fc6c976fc373fe1f2ce929b27f08ad4ea8499c13461
|
|
| MD5 |
3283f18fbcb93be0f9237ade60d46bdc
|
|
| BLAKE2b-256 |
fcdbbecc1331b1eefe8e3370281a2fd7b9685ae6a10dbdd54c7e44ea05bf2ed6
|
Provenance
The following attestation bundles were made for cyclopts-4.23.2.tar.gz:
Publisher:
deploy.yaml on BrianPugh/cyclopts
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
cyclopts-4.23.2.tar.gz -
Subject digest:
1c9de7f245394d3ef9344fc6c976fc373fe1f2ce929b27f08ad4ea8499c13461 - Sigstore transparency entry: 2568138073
- Sigstore integration time:
-
Permalink:
BrianPugh/cyclopts@22cfd43249ee740e8815626a29d7da3d095501b0 -
Branch / Tag:
refs/tags/v4.23.2 - Owner: https://github.com/BrianPugh
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
deploy.yaml@22cfd43249ee740e8815626a29d7da3d095501b0 -
Trigger Event:
push
-
Statement type:
File details
Details for the file cyclopts-4.23.2-py3-none-any.whl.
File metadata
- Download URL: cyclopts-4.23.2-py3-none-any.whl
- Upload date:
- Size: 236.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
eb95b6f221ec8e62ba64f879beb27dff779408a320db730fc184427c463a3695
|
|
| MD5 |
05bf0b1ea451ad6e8d320e633fb80e38
|
|
| BLAKE2b-256 |
3540c17d731af4ddbf6dede1f1acb09e6335c2587e8b73b3d4742f3f9c6996d3
|
Provenance
The following attestation bundles were made for cyclopts-4.23.2-py3-none-any.whl:
Publisher:
deploy.yaml on BrianPugh/cyclopts
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
cyclopts-4.23.2-py3-none-any.whl -
Subject digest:
eb95b6f221ec8e62ba64f879beb27dff779408a320db730fc184427c463a3695 - Sigstore transparency entry: 2568138075
- Sigstore integration time:
-
Permalink:
BrianPugh/cyclopts@22cfd43249ee740e8815626a29d7da3d095501b0 -
Branch / Tag:
refs/tags/v4.23.2 - Owner: https://github.com/BrianPugh
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
deploy.yaml@22cfd43249ee740e8815626a29d7da3d095501b0 -
Trigger Event:
push
-
Statement type:
