tessl/pypi-cyclopts
Intuitive, easy CLIs based on type hints.
—
Pending
core-app.mddocs/
Core Application Framework
The foundation of Cyclopts CLI applications, providing the App class for command registration, argument parsing, and execution flow control.
Capabilities
App Class
The main application class that manages command registration, parsing, and execution.
class App:
def __init__(
self,
name: str | tuple[str, ...] | None = None,
help: str | None = None,
*,
usage: str | None = None,
alias: str | tuple[str, ...] | None = None,
default_command: Callable[..., Any] | None = None,
default_parameter: Parameter | None = None,
config: Iterable[ConfigProtocol] | None = None,
version: str | Callable[[], str] | None = None,
version_flags: Iterable[str] = ("--version",),
show: bool = True,
console: Console | None = None,
help_flags: Iterable[str] = ("--help", "-h"),
help_format: Literal["markdown", "md", "plaintext", "restructuredtext", "rst", "rich"] | None = None,
help_on_error: bool | None = None,
version_format: Literal["markdown", "md", "plaintext", "restructuredtext", "rst", "rich"] | None = None,
group: Group | str | tuple[Group | str, ...] | None = None,
group_arguments: Group | str | None = None,
group_parameters: Group | str | None = None,
group_commands: Group | str | None = None,
validator: list[Callable[..., Any]] | None = None,
name_transform: Callable[[str], str] | None = None,
sort_key: Callable[[str], Any] | None = None,
end_of_options_delimiter: str | None = None,
suppress_keyboard_interrupt: bool = True
):
"""
Create a new Cyclopts application.
Parameters
----------
name
Application name. If None, derived from calling module
help
Help text for the application
usage
Custom usage string override
alias
Alternative names for the application
default_command
Function to run when no command is specified
default_parameter
Default parameter configuration for all commands
config
Configuration loaders for file-based config
version
Version string or callable that returns version
version_flags
Flag options that trigger version display
show
Whether to show this app in parent help displays
console
Rich console for output formatting
help_flags
Flag options that trigger help display
help_format
Output format for help text (markdown, plaintext, rich, etc.)
help_on_error
Whether to show help on parsing errors
version_format
Output format for version text
group
Groups to organize this app within parent app
group_arguments
Default group for positional arguments
group_parameters
Default group for keyword parameters
group_commands
Default group for subcommands
validator
List of validator functions for the app
name_transform
Function to transform Python names to CLI names
sort_key
Function for sorting commands in help
end_of_options_delimiter
String that marks end of options (default: "--")
suppress_keyboard_interrupt
Whether to suppress KeyboardInterrupt exceptions
"""Command Registration
Register functions as commands and default handlers.
def command(
self,
func: Callable = None,
*,
name: str | tuple[str, ...] | None = None
) -> Callable:
"""
Register a function as a command.
Parameters
----------
func
Function to register as command
name
Command name. If None, derived from function name
Returns
-------
Callable
The decorated function
"""
def default(self, func: Callable = None) -> Callable:
"""
Register a function as the default command.
Parameters
----------
func
Function to register as default command
Returns
-------
Callable
The decorated function
"""Parsing and Execution
Parse command-line arguments and execute commands.
def parse_args(self, tokens: list[str] | None = None) -> Any:
"""
Parse command-line arguments and return the result.
Parameters
----------
tokens
Command-line tokens to parse. If None, uses sys.argv
Returns
-------
Any
Result of executing the matched command
"""
def parse_known_args(self, tokens: list[str] | None = None) -> tuple[Any, list[str]]:
"""
Parse known arguments, returning result and remaining tokens.
Parameters
----------
tokens
Command-line tokens to parse. If None, uses sys.argv
Returns
-------
tuple[Any, list[str]]
Result of command execution and list of unknown tokens
"""
def __call__(self, tokens: list[str] | None = None) -> Any:
"""
Execute the application with command-line arguments.
Parameters
----------
tokens
Command-line tokens to parse. If None, uses sys.argv
Returns
-------
Any
Result of executing the matched command
"""Application Properties and Methods
Additional App methods for help, version, and configuration.
@property
def name(self) -> tuple[str, ...]:
"""Get the application name as a tuple."""
@property
def help(self) -> str | None:
"""Get the application help text."""
@property
def version(self) -> str | Callable[[], str] | None:
"""Get the application version."""
def help_print(self, tokens: list[str] | None = None) -> None:
"""
Print help information for the application or specific command.
Parameters
----------
tokens
Command tokens to show help for
"""
def version_print(self) -> None:
"""Print the application version."""
def interactive_shell(self) -> None:
"""Start an interactive shell for the application."""
def update(self, other: App) -> None:
"""
Update this app with configuration from another app.
Parameters
----------
other
App to copy configuration from
"""High-Level Run Function
Convenience function for simple CLI applications.
def run(
func: Callable,
*,
name: str | tuple[str, ...] | None = None,
help: str | None = None,
version: str | Callable[[], str] | None = None,
help_flags: Iterable[str] = ("--help", "-h"),
version_flags: Iterable[str] = ("--version", "-V"),
config: Iterable[ConfigProtocol] | None = None,
console: Console | None = None,
**kwargs
) -> Any:
"""
Run a single function as a CLI application.
Parameters
----------
func
Function to run as CLI command
name
Application name
help
Help text for the application
version
Version string or callable
help_flags
Flag options that trigger help display
version_flags
Flag options that trigger version display
config
Configuration loaders
console
Rich console for output
Returns
-------
Any
Result of function execution
"""Usage Examples
Basic App with Multiple Commands
from cyclopts import App
app = App(name="myapp", version="1.0.0")
@app.command
def hello(name: str):
print(f"Hello {name}!")
@app.command
def goodbye(name: str):
print(f"Goodbye {name}!")
@app.default
def main():
print("Available commands: hello, goodbye")
if __name__ == "__main__":
app()App with Custom Configuration
from cyclopts import App, Group
from cyclopts.config import Json
app = App(
name="myapp",
help="My CLI application",
group_commands=Group("Commands", "Available commands:"),
config=[Json("config.json")],
version="2.1.0"
)
@app.command
def process(input_file: str, verbose: bool = False):
"""Process an input file."""
if verbose:
print(f"Processing {input_file}")
# Process file...
if __name__ == "__main__":
app()Install with Tessl CLI
npx tessl i tessl/pypi-cyclopts