cyclopts API reference

128 public APIs from cyclopts (BrianPugh/cyclopts) — 46 classes, 42 functions, 40 methods. Signatures extracted by static analysis of the actual source.

Repository: BrianPugh/cyclopts

Kind	Count
Classes	46
Functions	42
Methods	40

API list

func

cyclopts._convert.convert_enum_flag(enum_type:type[F], tokens:Iterable[str] | Iterable['Token'], name_transform:Callable[[str], str]) -> F

Convert tokens to a Flag enum value.

funccyclopts._convert.create_empty_instance(hint:Any) -> Any

Create an empty instance of ``hint``'s container type.

funccyclopts._convert.get_enum_member(type_:type[E], token:Union['Token', str], name_transform:Callable[[str], str]) -> E

Match a token's value to an enum's member.

funccyclopts._convert.instantiate_from_dict(type_:type[T], data:dict[str, Any]) -> T

Instantiate a type with proper handling of parameter kinds.

classcyclopts._edit.EditorDidNotChangeError

User did not edit file contents in :func:`.edit`.

classcyclopts._edit.EditorDidNotSaveError

User did not save upon exiting :func:`.edit`.

classcyclopts._edit.EditorError

Root editor-related error.

classcyclopts._edit.EditorNotFoundError

Could not find a valid text editor for :func`.edit`.

funccyclopts._env_var.env_var_split(type_:Any, val:str, *delimiter:str | None=None) -> list[str]

Type-dependent environment variable value splitting.

funccyclopts._markup.escape_html(text:str | None) -> str

Escape special HTML characters in text.

funccyclopts._markup.escape_markdown(text:str | None) -> str | None

Escape special markdown characters in text.

funccyclopts._markup.escape_rst(text:str | None) -> str

Escape special reStructuredText characters in text.

funccyclopts._markup.extract_text(obj:Any, console:Optional['Console']=None, preserve_markup:bool=False) -> str

Extract text from Rich renderables or any object.

funccyclopts._result_action.handle_result_action(result:Any, action:ResultAction, print_fn:Callable[[Any], None]) -> Any

Handle command result based on result_action.

funccyclopts._result_action.resolve_returncode(result:Any, default:int=0) -> int

Resolve the return code for ``result``.

funccyclopts.annotations.is_enum(hint) -> bool

Check if a type hint is an enum.Enum subclass.

funccyclopts.annotations.is_enum_flag(hint) -> bool

Check if a type hint is an enum.Flag subclass.

funccyclopts.annotations.is_typeddict(hint) -> bool

Determine if a type annotation is a TypedDict.

funccyclopts.annotations.is_union(type_:type | None) -> bool

Checks if a type is a union.

funccyclopts.annotations.is_unpack(type_:Any) -> bool

Check if a type is ``typing.Unpack[...]`` (PEP-646 / PEP-692).

funccyclopts.annotations.resolve(type_:Any) -> type

Perform all simplifying resolutions.

funccyclopts.annotations.resolve_optional(type_:Any) -> Any

Only resolves Union's of None + one other type (i.e.

funccyclopts.annotations.resolve_type_alias(type_:Any) -> Any

Resolve TypeAliasType (Python 3.12+ 'type' statement) to its underlying type.

funccyclopts.annotations.resolve_unpack(type_:Any) -> Any

Unwrap ``Unpack[X]`` to ``X``.

methodcyclopts.argument._argument.Argument.append(token:Token)

Safely add a :class:`Token`.

methodcyclopts.argument._argument.Argument.get_choices(force:bool=False) -> tuple[str, ...] | None

Extract completion choices from type hint.

methodcyclopts.argument._argument.Argument.name() -> str

The **first** provided name this argument goes by.

methodcyclopts.argument._argument.Argument.parse() -> bool

Whether this argument should be parsed from CLI tokens.

methodcyclopts.argument._argument.Argument.show() -> bool

Show this argument on the help page.

methodcyclopts.argument._argument.Argument.show_default() -> bool | str | Callable[[Any], str]

Show the default value on the help page.

methodcyclopts.argument._argument.Argument.token_count(keys:tuple[str, ...]=())

The number of string tokens this argument consumes.

methodcyclopts.argument._argument.Argument.validate(value)

Validates provided value.

classcyclopts.argument._collection.ArgumentCollection

A list-like container for :class:`Argument`.

funccyclopts.argument.utils.get_choices_from_hint(type_:type, name_transform:Callable[[str], str]) -> list[str]

Extract completion choices from a type hint.

methodcyclopts.command_spec.CommandSpec.resolve(parent_app:'App') -> 'App'

Import and resolve the command on first access.

classcyclopts.completion._base.CompletionAction

Shell-agnostic completion action types.

classcyclopts.completion._base.CompletionData

Completion data for a command path.

funccyclopts.completion._base.clean_choice_text(text:str) -> str

Clean choice text without shell-specific escaping.

funccyclopts.completion._base.escape_for_shell_pattern(name:str, chars:str='*?[]') -> str

Escape glob/pattern characters for shell case patterns.

funccyclopts.completion._base.get_completion_action(type_hint:Any) -> CompletionAction

Get completion action from type hint.

funccyclopts.completion._base.strip_markup(text:str, format:str='markdown', max_length:int=80) -> str

Strip markup and render to plain text for shell completions.

funccyclopts.completion.bash.generate_completion_script(app:'App', prog_name:str) -> str

Generate bash completion script.

classcyclopts.completion.detect.ShellDetectionError

Raised when the shell type cannot be detected.

funccyclopts.completion.fish.generate_completion_script(app:'App', prog_name:str) -> str

Generate fish completion script.

funccyclopts.completion.install.add_to_rc_file(script_path:Path, prog_name:str, shell:Literal['bash', 'zsh']) -> bool

Add completion configuration to shell RC file.

funccyclopts.completion.zsh.generate_completion_script(app:'App', prog_name:str) -> str

Generate zsh completion script.

classcyclopts.config._common.ConfigBase

Base class for configuration sources.

methodcyclopts.config._common.ConfigBase.config() -> dict[str, Any]

Return the configuration dictionary.

classcyclopts.config._common.ConfigFromFile

Configuration source that loads from a file.

classcyclopts.config._common.Dict

Configuration source from an in-memory dictionary.

method

cyclopts.core.App.assemble_argument_collection(*default_parameter:Parameter | None=None, *parse_docstring:bool=False) -> ArgumentCollection

Assemble the argument collection for this app.

method

cyclopts.core.App.help_print(tokens:Annotated[None | str | Iterable[str], Parameter(show=False)]=None, *console:Annotated[Optional['Console'], Parameter(parse=False)]=None) -> None

Print the help page.

methodcyclopts.core.App.name() -> tuple[str, ...]

Application name(s).

methodcyclopts.core.App.resolved_commands() -> dict[str, 'App']

Get all commands as resolved App instances.

methodcyclopts.core.App.update(app:'App')

Copy over all commands from another :class:`App`.

methodcyclopts.core.App.version_print(console:Annotated[Optional['Console'], Parameter(parse=False)]=None) -> None

Print the application version.

classcyclopts.exceptions.CoercionError

There was an error performing automatic type coercion.

classcyclopts.exceptions.CycloptsError

Root exception for runtime errors.

classcyclopts.exceptions.MissingArgumentError

A required argument was not provided.

classcyclopts.exceptions.MixedArgumentError

Cannot supply keywords and non-keywords to the same argument.

classcyclopts.exceptions.RepeatArgumentError

The same parameter has erroneously been specified multiple times.

classcyclopts.exceptions.UnknownCommandError

CLI token combination did not yield a valid command.

classcyclopts.exceptions.UnknownOptionError

Unknown/unregistered option provided by the cli.

classcyclopts.exceptions.UnusedCliTokensError

Not all CLI tokens were used as expected.

classcyclopts.exceptions.ValidationError

Validator function raised an exception.

classcyclopts.ext.mkdocs.CycloptsPlugin

MkDocs plugin to generate Cyclopts CLI documentation.

classcyclopts.ext.mkdocs.CycloptsPluginConfig

Configuration schema for the Cyclopts MkDocs plugin.

classcyclopts.ext.mkdocs.DirectiveOptions

Configuration for the ::: cyclopts directive.

funccyclopts.ext.mkdocs.is_in_code_block(pos:int) -> bool

Check if a position is inside a code block.

funccyclopts.ext.mkdocs.process_cyclopts_directives(markdown:str, plugin_config:Any) -> str

Process all ::: cyclopts directives in markdown content.

classcyclopts.ext.sphinx.CycloptsDirective

Sphinx directive for documenting Cyclopts CLI applications.

methodcyclopts.ext.sphinx.CycloptsDirective.run() -> list['nodes.Node']

Generate documentation nodes for the Cyclopts app.

classcyclopts.ext.sphinx.DirectiveOptions

Configuration for the Cyclopts directive.

methodcyclopts.ext.sphinx.DirectiveOptions.from_dict(options:dict) -> 'DirectiveOptions'

Create options from directive options dictionary.

classcyclopts.field_info.FieldInfo

Extension of :class:`inspect.Parameter`.

methodcyclopts.field_info.FieldInfo.name()

The **first** provided name.

funccyclopts.group.sort_groups(groups:list[Group], attributes:list[Any]) -> tuple[list[Group], list[Any]]

Sort groups for the help-page.

classcyclopts.group_extractors.RegisteredCommand

A command with the names it was registered under.

classcyclopts.help.formatters.html.HtmlFormatter

HTML documentation formatter.

methodcyclopts.help.formatters.html.HtmlFormatter.get_output() -> str

Get the accumulated HTML output.

method

cyclopts.help.formatters.html.HtmlFormatter.render_description(console:Optional['Console'], options:Optional['ConsoleOptions'], description:Any) -> None

Render the description as HTML.

method

cyclopts.help.formatters.html.HtmlFormatter.render_usage(console:Optional['Console'], options:Optional['ConsoleOptions'], usage:Any) -> None

Render the usage line as HTML.

methodcyclopts.help.formatters.html.HtmlFormatter.reset() -> None

Reset the internal output buffer.

classcyclopts.help.formatters.markdown.MarkdownFormatter

Markdown documentation formatter.

methodcyclopts.help.formatters.markdown.MarkdownFormatter.get_output() -> str

Get the accumulated markdown output.

method

cyclopts.help.formatters.markdown.MarkdownFormatter.render_description(console:Optional['Console'], options:Optional['ConsoleOptions'], description:Any) -> None

Render the description as markdown.

method

cyclopts.help.formatters.markdown.MarkdownFormatter.render_usage(console:Optional['Console'], options:Optional['ConsoleOptions'], usage:Any) -> None

Render the usage line as markdown.

methodcyclopts.help.formatters.markdown.MarkdownFormatter.reset() -> None

Reset the internal output buffer.

classcyclopts.help.formatters.plain.PlainFormatter

Plain text formatter for improved accessibility.

method

cyclopts.help.formatters.plain.PlainFormatter.render_description(console:'Console', options:'ConsoleOptions', description:Any) -> None

Render the description.

method

cyclopts.help.formatters.plain.PlainFormatter.render_usage(console:'Console', options:'ConsoleOptions', usage:Any) -> None

Render the usage line.

classcyclopts.help.formatters.rst.RstFormatter

reStructuredText documentation formatter.

methodcyclopts.help.formatters.rst.RstFormatter.get_output() -> str

Get the accumulated RST output.

method

cyclopts.help.formatters.rst.RstFormatter.render_description(console:Optional['Console'], options:Optional['ConsoleOptions'], description:Any) -> None

Render the description as RST.

method

cyclopts.help.formatters.rst.RstFormatter.render_usage(console:Optional['Console'], options:Optional['ConsoleOptions'], usage:Any) -> None

Render the usage line as RST.

methodcyclopts.help.formatters.rst.RstFormatter.reset() -> None

Reset the internal output buffer.

classcyclopts.help.help.HelpEntry

Container for help table entry data.

methodcyclopts.help.help.HelpEntry.names() -> tuple[str, ...]

All long option names (positive + negative).

methodcyclopts.help.help.HelpEntry.shorts() -> tuple[str, ...]

All short option names (positive + negative).

classcyclopts.help.help.HelpPanel

Data container for help panel information.

funccyclopts.help.help.format_command_entries(apps_with_names:Iterable, format:str) -> list[HelpEntry]

Format command entries for help display.

classcyclopts.help.protocols.ColumnSpecBuilder

Protocol for ColumnSpecBuilders.

classcyclopts.help.protocols.HelpFormatter

Protocol for help **formatter** functions.

classcyclopts.help.silent.SilentRich

Dummy object that causes nothing to be printed.

classcyclopts.help.specs.AsteriskRenderer

Renderer for required parameter asterisk indicator.

classcyclopts.help.specs.ColumnSpec

Specification for a single column in a help table.

classcyclopts.help.specs.CommandNameRenderer

Renderer for command names with aliases in parentheses.

classcyclopts.help.specs.PanelSpec

Specification for panel (outer box) styling.

methodcyclopts.help.specs.PanelSpec.build(renderable:'RenderableType', **overrides) -> 'Panel'

Create a Panel around `renderable`.

classcyclopts.help.specs.TableSpec

Specification for table layout and styling.

method

cyclopts.help.specs.TableSpec.build(columns:tuple[ColumnSpec, ...], entries:Iterable['HelpEntry'], **overrides) -> 'Table'

Construct and populate a rich.Table.

funccyclopts.loader.load_app_from_script(script:str | Path) -> tuple['App', str]

Load a Cyclopts App object from a Python script.

funccyclopts.panel.CycloptsPanel(message:Any, title:str='Error', style:str='red') -> 'Panel'

Create a :class:`~rich.panel.Panel` with a consistent style.

methodcyclopts.parameter.Parameter.default() -> Self

Create a Parameter with all Cyclopts-default values.

method

cyclopts.parameter.Parameter.from_annotation(type_:Any, *default_parameters:'Parameter | None') -> tuple[Any, 'Parameter']

Resolve the immediate Parameter from a type hint.

funccyclopts.parameter.get_parameters(hint:T, skip_converter_params:bool=False) -> tuple[T, list[Parameter]]

At root level, checks for cyclopts.Parameter annotations.

funccyclopts.parameter.validate_command(f:Callable)

Validate if a function abides by Cyclopts's rules.

classcyclopts.token.Token

Tracks how a user supplied a value to the application.

methodcyclopts.token.Token.address() -> tuple[tuple[str, ...], int]

Hashable subkey destination address for this token.

classcyclopts.utils.UNSET

Special sentinel value indicating that no data was provided.

funccyclopts.utils.default_name_transform(s:str) -> str

Converts a python identifier into a CLI token.

funccyclopts.utils.import_app(module_path:str)

Import a Cyclopts App from a module path.

funccyclopts.utils.is_option_like(token:str, *allow_numbers=False) -> bool

Checks if a token looks like an option.

funccyclopts.utils.slice_to_str(value:slice) -> str

Format a slice in slice notation (e.g.

funccyclopts.utils.sort_key_converter(value:Any) -> Any

Convert sort_key value, consuming generators with :func:`next`.

classcyclopts.validators._number.Number

Limit input number to a value range.

classcyclopts.validators._path.Path

Assertions on properties of :class:`pathlib.Path`.

classcyclopts.validators._slice.Slice

Assertions on properties of a :class:`slice`.

About this data

These signatures were extracted from the public source of BrianPugh/cyclopts using Python's ast module. Argument names, default values, type annotations and return types are taken verbatim from the code. Implementation bodies are never stored. See how it works for details.

Back to all 805 libraries