cyclopts 3.0.0

v3.0.0

on Python PyPI

Features

• Advanced parsing of user-defined classes (including pydantic/attrs/dataclasses/namedtuple).
• Support parsing of typeddict/dict.
• Improved error message precision/accuracy/helpfulness.
• New convenience types: UInt8, Int8, UInt16, Int16, Uint32, Int32, Json.
• Number and Path validators now work with sequences (e.g. list[Path]).
• Additional POSITIONAL_ONLY parameters may follow an iterable POSITIONAL_ONLY parameter. This allows for programs like:

  @app.default
  def foo(inputs: list[Path], output: Path, /):
      pass

  $ python my-program.py input_files/*.txt output.txt

• Now supports the bare -- special token for forcing all subsequent CLI tokens to be parsed as positional argument. This mimics getopt behavior.
• Add "new" group validator cyclopts.validators.MutuallyExclusive. Performs same action as the default LimitedChoice(), but may be more intuitive/obvious for developers reading application code.
• Improved help-page formatting.
• Various minor bug fixes.

Breaking Changes/Features

• Drop python3.8 support; add python3.13 support.

• Remove Group.converter and App.converter. Their use-cases are a bit contrived, don't provide much value, and increase the maintenance burden of the Cyclopts codebase.

• Change in custom Parameter.converter. Previously, the converter had signature:

  def converter(type_, *values: str): ...

  The new signature is:

  def converter(type_, tokens: Sequence[Token]): ...

  See the new Token class. This allows for raising a CoercionError for the particular offending token, which will result in a more helpful error message for the user.

• App.parse_args and App.parse_known_args now return an additional value, ignored, which is a dictionary mapping python-variable-names to their type annotation of parameters with parse=False.

• Different CLI parsing scheme that is more directly similar to python's function rules. If a python variable is POSITIONAL_OR_KEYWORD, and a value is specified by keyword, subsequent POSITIONAL_OR_KEYWORD parameters in the function signature must be specified by keyword.

• When an iterable-like datatype is specified by keyword, only a single element's worth of tokens will be consumed. To restore the old behavior where tokens are consumed until an option-like argument is reached, set Parameter.consume_multiple = True.

• Parameter.negative_bool values must no longer start with --. E.g. if it was previously --no-, it should now be no-. A ValueError is raised if it starts with a hyphen.

• Parameter.negative_iterable values must no longer start with --. E.g. if it was previously --empty-, it should now be empty-. A ValueError is raised if it starts with a hyphen.

• Parameter.required field actually impacts whether or not the Parameter is mandatory. Previously it was only reflected in the help page.