v2.4.0

Features

• Added async function support by @nesb1 in #112
• Introduces a new exception: UnknownOptionError (see "Breaking Changes" below).

Breaking Changes

The following outlines incredibly-minor breaking changes:

• Introduces a new exception: UnknownOptionError.
• Change negative-flag-assignment-exception from ValidationError to generic CycloptsError (ValidationError inherits from CycloptsError).
  • e.g. --no-flag=True now raises CycloptsError instead of ValidationError.
  • This may only impact people who were specifically catching a ValidationError for this in a meta-app. This is an esoteric scenario that I imagine it doesn't exist in the wild.
• Change exception for unknown option token from ValidationError to UnknownOptionError.
  • I also imagine this is a rare currently-in-the-wild scenario; anyone attempting to catch this exception in a meta-app is probably catching a CycloptsError instead of a ValidationError.

Bug Fixes

• Fixed incorrectly python_variable->cli_option translated names. Addresses #110.
• Fixes indexing errors when validators/converters raise exceptions without messages.

New Contributors

• @nesb1 made their first contribution in #112

Full Changelog: v2.3.2...v2.4.0

v2.3.2

Bug Fixes

• More fixes for parsing list of tuples with insufficient arguments by @BrianPugh in #109

Full Changelog: v2.3.1...v2.3.2

v2.3.1

Bug Fixes

• Fix convert of Tuple[str]. by @BrianPugh in #106
• Populate missing console for some cyclopts errors by @BrianPugh in #107
• Fix poor handling of missing or non-divisible token_count values. by @BrianPugh in #108

Mentions

• Shoutout to @OrHayat for the well-crafted bug reports!

Full Changelog: v2.3.0...v2.3.1

v2.3.0

Features

• Allow specifying a Rich console in App.init by @BrianPugh in #99
• Allow deleting of commands, e.g. del app['foo']. by @BrianPugh in #91

Full Changelog: v2.2.0...v2.3.0

v2.2.0

What's Changed

• Added App.help_format which allows for rst and markdown docstring formatting. Defaults to rst. by @BrianPugh in #85

Full Changelog: v2.1.2...v2.2.0

v2.1.2

Bug Fixes

• Fix recursive-parent default_parameter resolution by @BrianPugh in #83

Full Changelog: v2.1.1...v2.1.2

v2.1.1

Bug Fixes

• Support python3.10 pipe unions. by @BrianPugh in #80
• Double check function docstring if it has a valid short-description by @BrianPugh in #82
• Improve type hints. by @BrianPugh in #79

Full Changelog: v2.1.0...v2.1.1

v2.1.0

Features

• Expose App.parse_commands to public API (previously internally named _parse_command_chain).

Bug Fixes

• Fix crash when displaying help where the only parameter has show=False.

Documentation

• Added a cookbook example of how to use pyproject.toml in a CLI project.
• Fixed out-of-date meta-app info.

Full Changelog: v2.0.0...v2.1.0

v2.0.0

Cyclopts v2 introduces many new features, and more robust handling of complicated applications.
Cyclopts v2 is mostly backwards compatible with v1. Most breaking changes fall under the "advanced users" category and can be fixed with minimal changes.

Features & Improvements

• Command & Parameter Groups:
  • Every command & parameter belongs to one-or-more groups now.
  • The name of the group is the title of the panel it will show up in on the help-page.
  • A group can have converter and validator:
    • New Group Validator: cyclopts.validator.LimitedChoice:
      • Allows for only a certain number of CLI specifications within the group.
      • Default behavior is "mutually-exclusive" within the group.
• New default group assignment based on parameter positioning:
  • Positional-only arguments now default to being parsed into the App.group_arguments group. This group defaults to Group("Arguments").
  • All other arguments now default to being parsed into the App.group_parameters group. This group defaults to Group("Parameters").
• Improved Pydantic @validate_call support.
• Commands can now be hidden via App.show=False. I.e. decorate a function with @app.command(show=False).
• A custom "usage" string can now be specified via App.usage.
• Improved default error messages by not allowing values that begin with a hyphen by default (and instead treating them as keyword options). This is controlled with the new Parameter.allow_leading_hyphen=False field.
• Iterable types (e.g. List) now consume all remaining valid tokens, regardless if specified as positional or keyword.
• Untyped parameters' type is now inferred from the non-None default value's type. If None or no default is provided, falls back to str.
• The int coercion logic now accepts decimal numbers from the CLI. It will first round, then cast to an int.
• cyclopts.convert (previously cyclopts.coerce) now takes an optional callable converter, allowing custom-converters to leverage convert's list/tuple/etc parsing abilities, while leaving final element-conversion to a custom function.
• Introduce the following Path annotated types:

  ExistingPath, ResolvedPath, ResolvedExistingPath, Directory, ExistingDirectory, ResolvedDirectory, ResolvedExistingDirectory, File, ExistingFile, ResolvedFile, ResolvedExistingFile
  

• Introduce the following Number annotated types:

  PositiveFloat, NonNegativeFloat, NegativeFloat, NonPositiveFloat, PositiveInt, NonNegativeInt, NegativeInt, NonPositiveInt
  

Breaking Changes

Cyclopts v2 is mostly backwards compatible with v1. Most breaking changes fall under the "advanced users" category.

• The new Parameter.allow_leading_hyphen=False feature's default is opposite of the default behavior in Cyclopts v1. For most use-cases, the new behavior is better. This primarily impacts those using a meta-app.
  If using a meta-app, the signature should probably be updated to be like:

  @app.meta.default
  def main(*tokens: Annotated[str, Parameter(show=False, allow_leading_hyphen=True)]):
      ...
  

  • If Parameter.allow_leading_hyphen==False, Iterable types (e.g. List) now consume all remaining tokens until an option is reached.
  • If Parameter.allow_leading_hyphen==True, Iterable types (e.g. List) now consume all remaining tokens.
• Parameter.token_count has been removed. The feature was kind of broken to begin with, and significantly increased code complexity. We can revisit this feature in the future if someone needs it.
• App.help_title_commands has been removed. Use the new App.group_commands feature to modify the default parameters help-page panel title. E.g. app.group_commands = "My Different Commands Title"
• App.help_title_parameters has been removed. Use the new App.group_arguments and App.group_parameters feature to modify the default parameters help-page panel title.
• Renamed cyclopts.coerce to cyclopts.convert for naming consistency.
• Untyped parameters' types are now inferred from the non-None default value's type. If the default is None or no default is provided, falls back to str. E.g.

  # old behavior
  def foo(value = 5):
      # `value` would be interpreted as a string.
      
  # new behavior
  def foo(value = 5):
      # `value` would be interpreted as a `int` because thats `type(5)`.
  

• The Validator and Converter protocols (type-hinting) have been removed and replaced with just Callable. The more-specific type-hinting made typical use-case a bit more tedious than it really needed to be.
• create_bound_arguments is no longer part of the public API.

Bug Fixes

• Allow explicit value setting of a positive boolean flag with an =. I.e. --my-flag=True or --my-flag=false.
• Fixed cyclopts.validators.Path error messages.
• Path validator now only checks if the path is a file/directory if it exists. Previously it would always try to check.
• Many, many, many more...

Special Thanks

Special thanks to @Ravencentric for user-testing and providing quick and useful feedback!

v1.3.0

Features

• Configurable boolean and iterable negative prefixes. Defaults are --no- and --empty-, respectively. by @BrianPugh in #38
• Support multiple validators for each Parameter. by @BrianPugh in #43
• Allow specified App.version to be a callable. by @BrianPugh in #44

Full Changelog: v1.2.0...v1.3.0