NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #366 most downloaded on PyPI
Intuitive, easy CLIs based on type hints.
Last release 5 days ago
23 Sep 2026
Ships on a steady schedule
a new release about every 2 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
3 years old
165 releases · first in 2023
mkdocs plugin (experimental! subject to change!).
Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v4.2.3...v4.4.0a1
Introduce Paramter.n_tokens to control number of tokens consumed/provided to custom converters. by @BrianPugh in https://github.com/BrianPugh/cyclopts
Paramter.n_tokens to control number of tokens consumed/provided to custom converters. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/695
@Parameter(...).Parameter.converter can now be a string indicating a forward-reference to a classmethod in the class.collections.abc.Set by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/703Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v4.2.5...v4.3.0
One column per month.
Fix user-classes not working correctly with aliases by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/699
Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v4.2.4...v4.2.5
More ergonomic ArgumentCollection.__contains__ that allows for string-lookup of arguments. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull
ArgumentCollection.__contains__ that allows for string-lookup of arguments. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/689Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v4.2.3...v4.2.4
Improve datetime converter to use datetime.fromisoformat by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/687
datetime converter to use datetime.fromisoformat by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/687
2025-11-11T13Z (no minute, second or fractional second).Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v4.2.2...v4.2.3
Fix some handling of nested meta-apps (meta-apps of meta-apps like @app.meta.meta)
@app.meta.meta)
App.result_action type hint. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/681Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v4.2.1...v4.2.2
Resolve TypeAliasType (python >=3.12). by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/670
TypeAliasType (python >=3.12). by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/670
type Foo = Annotated[int, cyclopts.Parameter(alias=“-f”)]
Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v4.2.0...v4.2.1
Allow for multiple App.result_action (composable) by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/663
App.result_action (composable) by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/663"call_if_callable" App.result_action by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/667
dataclasses.field's new "doc" field by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/664list[Path] (and similar) shell completions by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/661App.default_parameter) during completion generation. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/662Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v4.1.0...v4.2.0
Support pydantic Secret-types (SecretStr, SecretBytes, etc) by @BrianPugh in
Support pydantic Secret-types (SecretStr, SecretBytes, etc) by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/620
Parameter.count for int counting-flags (e.g., verbosity -vvv). by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/622
from cyclopts import Parameter
def main(verbose: Annotated[int, Parameter(alias="-v", count=True)] = 0):
print(f"Verbosity level: {verbose}") # -vvv → 3
Add App.help_epilogue, which prints a message at the bottom of the app's help-page. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/628
app = App(help_epilogue="For more info, visit: https://cyclopts.readthedocs.io")
@app.default
def main(name: str):
"""Greet someone."""
print(f"Hello {name}")
# ╭─ Parameters ───────────────────────────────╮
# │ * NAME [required] │
# ╰────────────────────────────────────────────╯
#
# For more info, visit: https://cyclopts.readthedocs.io
Add help from dataclass/attrs metadata to the resolution hierarchy. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/642
from dataclasses import dataclass, field
@dataclass
class Config:
port: int = field(default=8080, metadata={"help": "Server port"})
Add GNU-style combined short options support by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/639
from typing import Annotated
from cyclopts import Parameter
def main(
verbose: Annotated[bool, Parameter(alias="-v")],
user: Annotated[str, Parameter(alias="-u")],
):
pass
# -v -uroot → verbose=True, user="root"
# -vuroot → verbose=True, user="root" (GNU-style combined)
# -vu root → verbose=True, user="root"
More powerful ArgumentCollection.__getitem__ to support looking up by parameter name by @isoschiz in https://github.com/BrianPugh/cyclopts/pull/635
arg = argument_collection["param_name"] # Lookup by parameter name
App.version value instead of root-app version value. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/632MutuallyExclusive group validator accurately report the user-specified option name instead of the first positive name. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/634MissingArgumentError accurately report the user-specified option name instead of the first positive name. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/638Optional[bool] in the help-page. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/633--help and --version are passed to a subcommand. --help takes precedence. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/650cyclopts.__version__ not being updated (due to uv migration). by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/657parse=False to App.version_print handlers. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/656Special thanks to @isoschiz for thorough testing and bug reporting!
Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v4.0.0...v4.1.0
While Cyclopts v4 has a few breaking changes that generally make applications cleaner/terser/more intuitive, most shouldn't severely impact applicatio…
Cyclopts v4 represents a big feature update that makes it a no-compromise CLI python framework.
While Cyclopts v4 has a few breaking changes that generally make applications cleaner/terser/more intuitive, most shouldn't severely impact applications in the wild. This section lists the changes from most impactful to least.
The default help/version formatting has been changed from RestructuredText to Markdown.
App(help_format="restructuredtext").Default behavior of App.__call__ and App.run_async return value has changed. By default, these methods do not return and now perform a sys.exit. This ensures that scripts and installed applications have consistent exit code behavior. Previously, a script might have had a different exit code compared to an equivalent installed package. This behavior can be controlled via the new attribute App.result_action.
To replicate the old behavior, set result_action="return_value" in your root app.
app = App(result_action="return_value")
New App-inheritance mechanism/priorities. For most users this will have no impact, but pay attention if you use Meta Apps.
app.meta inherits from app.Dropped Python 3.9 support. Python 3.9 EOL is October 31, 2025.
On the help page, the root application name falls back to the script name (instead of the registered @app.default command name).
If a dataclass-like parameter is annotated with Parameter(name="*"), and all of its attributes are optional, but the parameter itself is not optional, a ValueError will now be raised. The value in the function signature must have a default value like None. See discussion in #519.
InvalidCommandError has been renamed UnknownCommandError for consistency.
Errors are now printed to stderr instead of stdout. Uses the new App.error_console.
If you want the old behavior (printing errors to stdout), set error_console to a console writing to stdout:
from rich.console import Console
app = App(error_console=Console())
All Parameter arguments except name (the only positional parameter) are now keyword-only.
If only nameless Groups are assigned to a Parameter, the default Argument/Parameter group is still also applied. This is most convenient when applying a validator without impacting the help page.
Pure "value added" features.
Lazy loading - Commands can now be registered using import paths (e.g., "myapp.commands.users:create"), which defers module imports until the command is executed. This dramatically improves CLI startup time for applications with many commands or heavy dependencies.
from cyclopts import App
app = App(name="myapp")
user_app = App(name="user")
# Module only imported when command is executed
user_app.command("myapp.commands.users:create")
app.command(user_app)
Shell Completion (supports bash, zsh, fish). Enable with app.register_install_completion_command(), then users can install via myapp --install-completion.
cyclopts run CLI command.Help page customization via help_formatter parameter on App and Group.
HelpFormatter protocol.DefaultFormatter (Rich-based with colors/borders) and PlainFormatter (accessibility-focused plain text).New cyclopts CLI tool.
cyclopts run - Execute a python script with dynamic shell-completion.cyclopts generate-docs - Generates documentation in a variety of formats (markdown, restructuredtext, html).
cyclopts generate-docs myscript.py -o docs.mdSphinx Extension for automatically generating CLI documentation from your Cyclopts App.
.. cyclopts:: mypackage.cli:app directive in your RST files.New App attributes; many of these were available as App.__call__ parameters, but now they can also be directly set on App and are inherited as expected:
print_error - Whether Cyclopts should print the rich-formatted error when a CycloptsError is encountered. True by default.exit_on_error - If there is an error parsing/coercing the CLI tokens, invoke sys.exit(1). True by default.help_on_error - If there is an error parsing/coercing the CLI tokens, print out the help-page for the parsed application. False by default.verbose - Populate CycloptsError exception strings with more information intended for developers. False by default.flatten subapp's subcommands if named "*". by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/611
Add support for enum.Flag and enum.IntFlag.
Add support for datetime.date type by @PerchunPak in https://github.com/BrianPugh/cyclopts/pull/601
Add cyclopts.config.Dict config class for in-memory configuration sources. Add new keyword argument source to config objects. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/599
App.console now always resolves to a console and respects the app-hierarchy. If a console is explicitly assigned, that console will always be used. This makes it easier to access a console object within commands.
Improved parsing of JSON strings from the CLI. Can now handle list[CustomClass] if each element is supplied as a JSON string.
Optimized "happy execution path" performance.
If App.sort_key or Group.sort_key are generators, Cyclopts automatically invokes next on them immediately.
This allows for streamlined lexical ordering of commands using itertools.count:
from itertools import count
from cyclopts import App, Group
counter = count()
@app.command(group=Group("Commands", sort_key=counter))
def first():
pass
@app.command(group=Group("Commands", sort_key=counter))
def second():
pass
list[int]) when consume_multiple=True.help_flags after end_of_options_delimiter by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/609Add cyclopts.config.Dict config class for in-memory configuration sources. Add new keyword argument source to config objects. by @BrianPugh in https:/
Changes since v4.0.0b1
cyclopts.config.Dict config class for in-memory configuration sources. Add new keyword argument source to config objects. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/599datetime.date type by @PerchunPak in https://github.com/BrianPugh/cyclopts/pull/601App._name when registering a subapp by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/610__init__.pyi type stubs by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/604None (use inheritance). by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/594RestructuredText(..., show_errors=False) so that the help-page still reasonable renders, even with unknown roles/directives. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/600Parameter.show_choices impacting shell completion. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/607help_flags after end_of_options_delimiter by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/609Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v4.0.0b1...v4.0.0b2
While Cyclopts v4 has a few breaking changes that generally make applications cleaner/terser/more intuitive, most shouldn't severely impact applicatio…
Assuming that feedback to this release is mostly positive, we are targeting a release of Oct 20, 2025
Cyclopts v4 represents a big feature update that makes it a no-compromise CLI python framework.
While Cyclopts v4 has a few breaking changes that generally make applications cleaner/terser/more intuitive, most shouldn't severely impact applications in the wild. This section lists the changes from most impactful to least.
The default help/version formatting has been changed from RestructuredText to Markdown.
App(help_format="restructuredtext").Default behavior of App.__call__ and App.run_async return value has changed. By default, these methods do not return and now perform a sys.exit. This ensures that scripts and installed applications have consistent exit code behavior. Previously, a script might have had a different exit code compared to an equivalent installed package. This behavior can be controlled via the new attribute App.result_action.
To replicate the old behavior, set result_action="return_value" in your root app.
app = App(result_action="return_value")
New App-inheritance mechanism/priorities. For most users this will have no impact, but pay attention if you use Meta Apps.
app.meta inherits from app.Dropped Python 3.9 support. Python 3.9 EOL is October 31, 2025.
On the help page, the root application name falls back to the script name (instead of the registered @app.default command name).
If a dataclass-like parameter is annotated with Parameter(name="*"), and all of its attributes are optional, but the parameter itself is not optional, a ValueError will now be raised. The value in the function signature must have a default value like None. See discussion in #519.
InvalidCommandError has been renamed UnknownCommandError for consistency.
Errors are now printed to stderr instead of stdout. Uses the new App.error_console.
If you want the old behavior (printing errors to stdout), set error_console to a console writing to stdout:
from rich.console import Console
app = App(error_console=Console())
All Parameter arguments except name (the only positional parameter) are now keyword-only.
If only nameless Groups are assigned to a Parameter, the default Argument/Parameter group is still also applied. This is most convenient when applying a validator without impacting the help page.
Pure "value added" features.
Lazy loading - Commands can now be registered using import paths (e.g., "myapp.commands.users:create"), which defers module imports until the command is executed. This dramatically improves CLI startup time for applications with many commands or heavy dependencies.
from cyclopts import App
app = App(name="myapp")
user_app = App(name="user")
# Module only imported when command is executed
user_app.command("myapp.commands.users:create")
app.command(user_app)
Shell Completion (supports bash, zsh, fish). Enable with app.register_install_completion_command(), then users can install via myapp --install-completion.
cyclopts run CLI command.Help page customization via help_formatter parameter on App and Group.
HelpFormatter protocol.DefaultFormatter (Rich-based with colors/borders) and PlainFormatter (accessibility-focused plain text).New cyclopts CLI tool.
cyclopts run - Execute a python script with dynamic shell-completion.cyclopts generate-docs - Generates documentation in a variety of formats (markdown, restructuredtext, html).
cyclopts generate-docs myscript.py -o docs.mdSphinx Extension for automatically generating CLI documentation from your Cyclopts App.
.. cyclopts:: mypackage.cli:app directive in your RST files.New App attributes; many of these were available as App.__call__ parameters, but now they can also be directly set on App and are inherited as expected:
print_error - Whether Cyclopts should print the rich-formatted error when a CycloptsError is encountered. True by default.exit_on_error - If there is an error parsing/coercing the CLI tokens, invoke sys.exit(1). True by default.help_on_error - If there is an error parsing/coercing the CLI tokens, print out the help-page for the parsed application. False by default.verbose - Populate CycloptsError exception strings with more information intended for developers. False by default.Native enum.Flag and enum.IntFlag support.
App.console now always resolves to a console and respects the app-hierarchy. If a console is explicitly assigned, that console will always be used. This makes it easier to access a console object within commands.
Improved parsing of JSON strings from the CLI. Can now handle list[CustomClass] if each element is supplied as a JSON string.
Optimized "happy execution path" performance.
If App.sort_key or Group.sort_key are generators, Cyclopts automatically invokes next on them immediately.
This allows for streamlined lexical ordering of commands using itertools.count:
from itertools import count
from cyclopts import App, Group
counter = count()
@app.command(group=Group("Commands", sort_key=counter))
def first():
pass
@app.command(group=Group("Commands", sort_key=counter))
def second():
pass
list[int]) when consume_multiple=True.introduce App.run_async, an asyncronous equivalent to App.__call__. This allows users to await Cyclopts within an async context (e.g. inside an async
App.run_async, an asyncronous equivalent to App.__call__. This allows users to await Cyclopts within an async context (e.g. inside an async meta app). by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/539App.version handler by @gerlero @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/540Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.23.1...v3.24.0
negative_iterable with an empty string shouldn't appear in the help screen by @nachocab in https://github.com/BrianPugh/cyclopts/pull/530
negative_iterable with an empty string shouldn't appear in the help screen by @nachocab in https://github.com/BrianPugh/cyclopts/pull/530Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.23.0...v3.23.1
NonExistent* convenience types by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/522
NonExistent* convenience types by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/522show=False. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/521consume_multiple documentation by @nachocab in https://github.com/BrianPugh/cyclopts/pull/517Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.22.5...v3.23.0
Fix broken command alias when name is also specified. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/509
alias when name is also specified. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/509Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.22.4...v3.22.5
Fix parameter alias resolution in dataclass attributes. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/506
alias resolution in dataclass attributes. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/506Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.22.3...v3.22.4
Fix DivideByZero error when counting tuple[bool, ...] by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/498
DivideByZero error when counting tuple[bool, ...] by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/498collections.abc.Sequence[bool] as multiple boolean flags. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/499Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.22.2...v3.22.3
Fix erroneous MissingArgumentError if an empty iterable value is provided in a config file. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pul
MissingArgumentError if an empty iterable value is provided in a config file. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/492Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.22.1...v3.22.2
Fix generating help for annotated enums with typealias by @Rubikoid in https://github.com/BrianPugh/cyclopts/pull/487
Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.22.0...v3.22.1
Add App.alias to conveniently assign additional names to commands. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/486
App.alias to conveniently assign additional names to commands. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/486Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.21.0...v3.22.0
cyclopts.validators.LimitedChoice improvements (by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/483):
cyclopts.validators.LimitedChoice improvements (by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/483):
LimitedChoice min value is negative, then all parameters in the group must be specified.LimitedChoice argument allow_none=False. If True, then also allow 0 CLI parameters (even if min is greater than 0).all_or_none, which is just the instantiated object LimitedChoice(-1, allow_none=True).cyclopts.validators.mutually_exclusive for convenience by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/482Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.20.0...v3.21.0
This release contains changes that may change some behavior for some users, but is mostly benign. If using custom Group Validators, please give this r
This release contains changes that may change some behavior for some users, but is mostly benign. If using custom Group Validators, please give this release more attention.
╭─ Commands ────────────────────────────────────────────────────────────╮
│ --help -h Display this message and exit. │
│ --version Display application version. │
╰───────────────────────────────────────────────────────────────────────╯
╭─ Arguments ───────────────────────────────────────────────────────────╮
│ * FOO [required] │
╰───────────────────────────────────────────────────────────────────────╯
╭─ Parameters ──────────────────────────────────────────────────────────╮
│ * BAR --bar [required] │
╰───────────────────────────────────────────────────────────────────────╯
Group.sort_key for more details.
By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/476Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.19.0...v3.20.0
Add Parameter.alias by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/460
Parameter.alias by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/460
Parameter.name, but it adds additional option names/flags to cyclopts-generated names instead of completely overriding.Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.18.0...v3.19.0
Stop KeyboardInterrupt from printing tracebacks by @gremlation in https://github.com/BrianPugh/cyclopts/pull/448
KeyboardInterrupt from printing tracebacks by @gremlation in https://github.com/BrianPugh/cyclopts/pull/448
KeyboardInterrupt from end-user ctrl-c action by default. This is done because generally the resulting stack trace is not useful to the end-user of the CLI. To disable this feature, set App(suppress_keyboard_interrupt=False).-2). These flags can only exist if the developer explicitly sets them with Parameter, and at that point they must be aware of the ambiguity between a digit-flag and a negative integer. By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/455Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.17.0...v3.18.0
Add Parameter.negative_none feature. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/446
Parameter.negative_none feature. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/446ls -alh) by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/453Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.16.2...v3.17.0
Only display COMMANDS in the help-page if there are registered commands (ignoring help/version flags). By @BrianPugh in https://github.com/BrianPugh/c
Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.16.1...v3.16.2
Do not invoke Parameter.show_default callable with an inspect._empty. Fixes Hex* types exception when attempting to display defaults and a default is
Parameter.show_default callable with an inspect._empty. Fixes Hex* types exception when attempting to display defaults and a default is not present. By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/438Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.16.0...v3.16.1
Rename format_cyclopts_error -> CycloptsPanel and make it public. Useful if you want to format rich Panels similar to Cyclopts. By @BrianPugh in https
format_cyclopts_error -> CycloptsPanel and make it public. Useful if you want to format rich Panels similar to Cyclopts. By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/436Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.15.0...v3.16.0
Add (optional) trio support by @aneeshusa in https://github.com/BrianPugh/cyclopts/pull/431
trio support by @aneeshusa in https://github.com/BrianPugh/cyclopts/pull/431Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.14.2...v3.15.0
Fix Parameter.negative inheritance for classes. By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/426
Parameter.negative inheritance for classes. By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/426Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.14.1...v3.14.2
Fix support of Enum member aliases. Thanks @beskep for the fix! By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/424
Enum member aliases. Thanks @beskep for the fix! By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/424Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.14.0...v3.14.1
Show cyclopts.config.Env variables in the help-page by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/417
cyclopts.config.Env variables in the help-page by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/417
cyclopts.config.Env.show = False.VAR_POSITIONAL argument as a builtin. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/419
*args and no other positional arguments.Parameter.show_default to be a callable. Add HexUInt* types to cyclopts.types that display the default value as hexadecimal in the help-page. By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/410cyclopts.config.Env error when a Parameter re-uses the same environment variable. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/416App.sort_key by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/420Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.13.1...v3.14.0
Fix TypeAlias resolution for multi-token types (e.g. tuple). by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/414
TypeAlias resolution for multi-token types (e.g. tuple). by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/414Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.13.0...v3.13.1
Handle the first block of docstring text as a potential multi-line short description. It is no longer possible to have a long-description without a sh
pytest when subprocessing a python script from within a pytest environment. By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/404functools.partial support. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/396Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.12.0...v3.13.0
add datetime and timedelta support. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/391
datetime and timedelta support. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/391Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.11.2...v3.12.0
Respect individual class field annotated converters. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/386
Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.11.1...v3.11.2
Improve App subclassing by @thejcannon in https://github.com/BrianPugh/cyclopts/pull/384
App subclassing by @thejcannon in https://github.com/BrianPugh/cyclopts/pull/384Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.11.0...v3.11.1
Lots of pydantic-specific improvements in this release.
Lots of pydantic-specific improvements in this release.
pydantic type hints and defer responsibility to pydantic. Notably, pydantic union discriminators now work correctly. By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/379Field.description to the help-resolution-hierarchy. By @pablospe in https://github.com/BrianPugh/cyclopts/pull/375pydantic.PositiveInt) now work.pydantic.ValidationError from calling user's command. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/378Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.10.1...v3.11.0
Fix Config.search_parents when used on relative paths. By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/371
Config.search_parents when used on relative paths. By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/371Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.10.0...v3.10.1
By default, registering a subapp will set it's help and version "show" attribute to False, making --help and --version not show up in the subapp's hel
False, making --help and --version not show up in the subapp's help page. This is done because the previous behavior (showing these flags) mostly cluttered the help-page and wasn't particularly useful. By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/363Parameter.validator to command-signature default-values. Consider the following code:import cyclopts
from pathlib import Path
def command(file: cyclopts.types.ExistingFile = Path("foo.bin")):
pass
cyclopts.run(command)
file would be Path("foo.bin"), but the validator that checks if the file exists would have not ran. This is unintuitive/unexpected to the developer. Now Cyclopts always runs validators, even on default values.
uint64/int64/Email/URL/Port by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/366InvalidCommandError didn't result in printing command suggestions. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/358Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.9.3...v3.10.0
Fix from __future__ import annotations type-resolution. By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/355
from __future__ import annotations type-resolution. By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/355
Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.9.2...v3.9.3
List available commands on InvalidCommandError. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/349
InvalidCommandError. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/349dataclasses.default_factory on the help-page. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/350Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.9.1...v3.9.2
Some typing fixes by @kiyoon in https://github.com/BrianPugh/cyclopts/pull/343
config.Env.split attribute; it wasn't actually used/performing it's intended functionality. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/344pprint traceback with rich by @thejcannon in https://github.com/BrianPugh/cyclopts/pull/340Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.9.0...v3.9.1
Add end_of_options_delimiter="--" option to App (and parsing methods). by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/333
end_of_options_delimiter="--" option to App (and parsing methods). by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/333null values as the string "None". by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/334Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.8.1...v3.9.0
Show choices in help output for Sequence by @aneeshusa in https://github.com/BrianPugh/cyclopts/pull/331
Sequence by @aneeshusa in https://github.com/BrianPugh/cyclopts/pull/331Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.8.0...v3.8.1
Add extension checking to cyclopts.validators.Path. By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/329
cyclopts.validators.Path. By @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/329
Annotated[Path, Parameter(validator=validators.Path(ext=(.jpg, .jpeg)))].BinPath
ExistingBinPath
CsvPath
ExistingCsvPath
ImagePath
ExistingImagePath
JsonPath
ExistingJsonPath
Mp4Path
ExistingMp4Path
TomlPath
ExistingTomlPath
TxtPath
ExistingTxtPath
YamlPath
ExistingYamlPath
-j flag by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/330Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.7.0...v3.8.0
This release primarily extends the features of v3.6.0
This release primarily extends the features of v3.6.0
$ myscript '[1,2,3]'
list[str]). To enable it for these cases, see next bullet point.Parameter configurations:
Parameter.json_dict: Optional[bool] - Whether or not to allow json-like data for dicts. None be default, which is the same as True except when the annotated class is union'd with a str.Parameter.json_list: Optional[bool] - Whether or not to allow json-like data for lists. None be default, which is the same as True except when each element of the annotated class is str.Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.6.0...v3.7.0
Allow parsing of json data if object is dict-like. Works for both environment variables, as well as cli variables. For example, the following are equi
$ movie-maintainer add --movie.title 'Furiosa: A Mad Max Saga' --movie.year 2024
$ movie-maintainer add --movie='{"title": "Mad Max: Fury Road", "year": 2024}'
$ MOVIE='{"title": "Mad Max: Fury Road", "year": 2024}' movie-maintainer add
Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.5.1...v3.6.0
cyclopts.run: fix type-hints for coroutines by @Tinche in https://github.com/BrianPugh/cyclopts/pull/323
cyclopts.run: fix type-hints for coroutines by @Tinche in https://github.com/BrianPugh/cyclopts/pull/323Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.5.0...v3.5.1
Add argument/attribute App.help_on_error that will print the command's help-page before printing any Cyclopts runtime error. Disabled by default by @B
App.help_on_error that will print the command's help-page before printing any Cyclopts runtime error. Disabled by default by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/316MissingArgumentError. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/317Annotated[..., Parameter(...)] on a pydantic BaseModel attribute was accidentally not applied. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/321Parameter.__call__; only fixes an unnecessary copy and code semantics. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/322Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.4.1...v3.5.0
Further improve config-file-caching that was introduced in v3.4.0. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/315
importlib.reload is no longer required.Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.4.0...v3.4.1
cyclopts.run convenience function for terser, simpler short scripts by @Tinche in https://github.com/BrianPugh/cyclopts/pull/305 Simple applications c
cyclopts.run convenience function for terser, simpler short scripts by @Tinche in https://github.com/BrianPugh/cyclopts/pull/305
Simple applications can now be written like:import cyclopts
def main(name: str, age: int):
print(f"Hello {name}, you are {age} years old.")
cyclopts.run(main)
Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.3.1...v3.4.0
The breaking changes are minimal and probably negatively impacts 0 users, but are listed here for completeness.
The breaking changes are minimal and probably negatively impacts 0 users, but are listed here for completeness.
Cyclopts now properly resolves aliases (and similar) for attrs and pydantic.
The cyclopts.field_info.FieldInfo no longer is a subclass of inspect.Parameter; it is now an independent class that mimics many of inspect.Parameter attributes. The class's __init__ now takes names: tuple[str, ...] instead of a single name: str. This is because certain-dataclass-like objects (namely, pydantic) allows for multiple python-variables to be mapped to the same attribute. The class still maintains a name: str property that returns the first element of the names attribute. This single name is used whenever an arbitrary choice for selecting a field's name needs to be used.
It was never intended for users to directly instantiate this class, and the name property makes it backwards compatible for those accessing the object. Probably noone actually accesses FieldInfo objects outside of Cyclopts' internals.
In some situations, an ArgumentOrderError could be erroneously raised when an UnknownOptionError would have been more appropriate. In those situations, an UnknownOptionError is now raised.
Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.3.0...v3.3.1
cyclopts.edit() to launch text editor for user input. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/303
cyclopts.edit() to launch text editor for user input. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/303Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.2.1...v3.3.0
Warn if cyclopts application is invoked with no python arguments within pytest. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/300
Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.2.0...v3.2.1
Allow Parameter to be used as a decorator. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/295 ```python from cyclopts import App, Paramet
from cyclopts import App, Parameter
from dataclasses import dataclass
app = App(name="movie-maintainer")
@Parameter(name="*")
@dataclass
class Movie:
title: str
year: int
@app.command
def add(movie: Movie):
print(f"Adding movie: {movie}")
app()
@Parameter decorator, we Introduce a hidden __cyclopts__ attribute that gets attached to decorated objects. Currently only created/used when @Parameter is used.Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.1.5...v3.2.0
Better handling of nested meta apps by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/291
Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.1.4...v3.1.5
Add App.update method. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/281
App.update method. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/281Annotated is inside another type; namely list[Annotated[...]]. by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/289Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.1.3...v3.1.4
Do not interpret choices/default as rich markup by @BrianPugh in https://github.com/BrianPugh/cyclopts/pull/278
Full Changelog: https://github.com/BrianPugh/cyclopts/compare/v3.1.2...v3.1.3
Your coding agent can read these notes before it upgrades. Set up the MCP server →