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

v1.2.0

Features

• App now takes an optional parameter default_parameter: Parameter that allows the configuration of what values a default Parameter uses. Parameters now have a resolution order for determining configuration values. Basically it goes (highest-to-lowest priority)annotated parameter -> parenting app default -> parenting-parenting app default -> .... by @BrianPugh in #33
• New classmethod Parameter.combine which can construct a new, single, Parameter from multiple Parameters.
• New classmethod Parameter.default which is similar to Parameter(), but it will override all parenting Parameters.
• App and Parameter's repr strings have been greatly simplified to only include non-default supplied parameters.

Bug Fixes

• conditionally import typing_extensions by @BrianPugh in #34
• use importlib.metadata to check distribution version. by @BrianPugh in #36
• Handle mutable signature parameter defaults. by @BrianPugh in #37

Breaking Changes

This release technically contains some breaking changes, but realistically no-one should be impacts.

• Removed MultipleParameterAnnotationError; we now handle multiple Parameter resolution. Specifically, for mutliple Parameter in an Annotated, they are evaluated left->right (right-most has highest precedence/priority).
• All of Parameter's defaults are now None. No change in default functionality.

Full Changelog: v1.1.1...v1.2.0

v1.1.1

Bug Fixes

• Fix error-handling of POSITIONAL_ONLY, VAR_KEYWORD, and VAR_POSITIONAL arguments. by @BrianPugh in #27

Full Changelog: v1.1.0...v1.1.1