tessl/pypi-cyclopts
Intuitive, easy CLIs based on type hints.
—
Pending
arguments-parameters.mddocs/
Arguments and Parameters
Fine-grained control over command-line argument behavior, validation, and presentation through Argument, Parameter, and related configuration classes.
Capabilities
Argument Class
Represents a command-line argument with type information and metadata.
class Argument:
def __init__(
self,
*,
converter: Callable | None = None,
validator: Callable | list[Callable] | None = None,
default: Any = UNSET,
default_factory: Callable[[], Any] | None = None,
help: str | None = None,
show: bool = True,
group: Group | None = None,
**kwargs
):
"""
Create an argument specification.
Parameters
----------
converter
Function to convert string tokens to target type
validator
Function or list of functions to validate converted value
default
Default value if argument not provided
default_factory
Factory function to generate default value
help
Help text for this argument
show
Whether to show this argument in help
group
Group for organizing this argument in help display
"""ArgumentCollection Class
List-like collection of Argument objects with validation.
class ArgumentCollection(list):
def __init__(self, *args: Argument):
"""
Create a collection of arguments.
Parameters
----------
args
Argument objects to include in collection
"""
def append(self, argument: Argument) -> None:
"""
Add an argument to the collection.
Parameters
----------
argument
Argument to add
"""
def __getitem__(self, index: int) -> Argument:
"""Get argument by index."""
def __len__(self) -> int:
"""Get number of arguments in collection."""Parameter Class
Configuration class for command parameters with advanced options.
class Parameter:
def __init__(
self,
*names: str,
converter: Callable | None = None,
validator: Callable | list[Callable] | None = None,
default: Any = UNSET,
default_factory: Callable[[], Any] | None = None,
help: str | None = None,
show: bool = True,
group: Group | None = None,
env_var: str | Iterable[str] | None = None,
negative: str | Iterable[str] | None = None,
**kwargs
):
"""
Create a parameter specification.
Parameters
----------
names
Parameter names (e.g., "--verbose", "-v")
converter
Function to convert string tokens to target type
validator
Function or list of functions to validate converted value
default
Default value if parameter not provided
default_factory
Factory function to generate default value
help
Help text for this parameter
show
Whether to show this parameter in help
group
Group for organizing this parameter in help display
env_var
Environment variable names to check for value
negative
Negative flag names for boolean parameters
"""Group Class
Organizational structure for commands and parameters in help display.
@dataclass(frozen=True)
class Group:
name: str
title: str = ""
description: str = ""
panel: Panel | None = None
sort_key: Callable[[str], Any] | None = None
default_parameter: Parameter | None = None
def __init__(
self,
name: str,
title: str = "",
description: str = "",
panel: Panel | None = None,
sort_key: Callable[[str], Any] | None = None,
default_parameter: Parameter | None = None
):
"""
Create a group for organizing CLI elements.
Parameters
----------
name
Internal name for the group
title
Display title for the group
description
Description text for the group
panel
Rich panel configuration for display
sort_key
Function for sorting elements within group
default_parameter
Default parameter configuration for group members
"""Token Class
Immutable representation of user input with parsing context.
class Token:
keyword: str
value: str
source: str
index: int
keys: tuple[str, ...]
implicit_value: str | None
def __init__(
self,
keyword: str,
value: str,
source: str = "unknown",
index: int = 0,
keys: tuple[str, ...] = (),
implicit_value: str | None = None
):
"""
Create a token representing user input.
Parameters
----------
keyword
The option keyword (e.g., "--verbose")
value
The string value provided
source
Source of the token (e.g., "cli", "env", "config")
index
Position index in the input sequence
keys
Nested keys for structured configuration
implicit_value
Implicit value for flag-style options
"""
def __str__(self) -> str:
"""String representation of the token."""
def __repr__(self) -> str:
"""Detailed representation of the token."""Utility Constants and Functions
Core utilities for argument handling.
UNSET: object
"""Sentinel value indicating no data provided."""
def default_name_transform(name: str) -> str:
"""
Convert Python identifier to CLI token format.
Parameters
----------
name
Python identifier (e.g., "my_parameter")
Returns
-------
str
CLI token format (e.g., "--my-parameter")
"""Usage Examples
Basic Parameter Configuration
from cyclopts import App, Parameter
app = App()
@app.command
def process(
input_file: str,
output_file: str = Parameter(help="Output file path"),
verbose: bool = Parameter("--verbose", "-v", help="Enable verbose output"),
count: int = Parameter(default=10, help="Number of iterations")
):
"""Process files with configurable options."""
if verbose:
print(f"Processing {input_file} -> {output_file}, {count} iterations")Advanced Parameter with Validation
from cyclopts import App, Parameter
from cyclopts.validators import Number
from pathlib import Path
app = App()
@app.command
def analyze(
data_file: Path = Parameter(help="Input data file"),
threshold: float = Parameter(
default=0.5,
validator=Number(min=0.0, max=1.0),
help="Analysis threshold (0.0-1.0)"
),
output_dir: Path = Parameter(
default_factory=lambda: Path.cwd() / "output",
help="Output directory"
)
):
"""Analyze data with validated parameters."""
print(f"Analyzing {data_file} with threshold {threshold}")
print(f"Output will be saved to {output_dir}")Grouped Parameters
from cyclopts import App, Parameter, Group
# Define groups
input_group = Group("input", "Input Options", "Configure input sources")
output_group = Group("output", "Output Options", "Configure output formatting")
app = App()
@app.command
def convert(
input_file: str = Parameter(group=input_group, help="Input file"),
input_format: str = Parameter(group=input_group, help="Input format"),
output_file: str = Parameter(group=output_group, help="Output file"),
output_format: str = Parameter(group=output_group, help="Output format")
):
"""Convert files between formats."""
print(f"Converting {input_file} ({input_format}) -> {output_file} ({output_format})")Environment Variable Integration
from cyclopts import App, Parameter
app = App()
@app.command
def deploy(
service: str,
region: str = Parameter(
env_var="AWS_REGION",
default="us-east-1",
help="AWS region for deployment"
),
api_key: str = Parameter(
env_var=["API_KEY", "SERVICE_API_KEY"],
help="API key for authentication"
)
):
"""Deploy service with environment variable support."""
print(f"Deploying {service} to {region}")Install with Tessl CLI
npx tessl i tessl/pypi-cyclopts