Update dependency cyclopts to v5 by renovate[bot] · Pull Request #22 · libranet/uv-developer

renovate · 2026-09-24T01:59:43Z

ℹ️ Note

This PR body was truncated due to platform limits.

This PR contains the following updates:

Package	Change	Age	Confidence
cyclopts	`>=3.24,<4` → `>=5.1,<6`

Release Notes

BrianPugh/cyclopts (cyclopts)

`v5.1.0`

Compare Source

Features

Support bool union'd with other types.
- fix: support bare and negative flags on unions containing bool (e.g. bool | list[str]) by @BrianPugh in #973
- fix: show the specific choices/value error for bad values on unions with a bool flag by @BrianPugh in #974
- fix: support bool and other members alongside an enum.Flag in a union (e.g. bool | MyFlag) by @BrianPugh in #975
- fix: let --x. options select a non-Flag member of a union with an enum.Flag by @BrianPugh in #977

Full Changelog: BrianPugh/cyclopts@v5.0.0...v5.1.0

`v5.0.0`

Compare Source

Check out the new "Migrating to v5" docs page, covering each intentional breaking change with before/after examples.

All v4 features up to 4.25.3 have been merged into this release.

Breaking

Dropped Python 3.10 support (Python 3.10 EoL is Oct 31, 2026) #889
Removed fuzzy command-matching. Command names must match exactly.
- It was a temporary v4 backwards-compat shim (#666) for the PascalCase → pascal-case name-transform change, retrying by stripping dashes/underscores on no exact match. Removed as cleanup for the major release.
```
@app.command
def MyCommand(): ...   # registers as "my-command"
# v4: `mycommand` fuzzy-matched -> my-command
# v5: `mycommand` no longer resolves; use `my-command`
```

Fallthrough parsing: child wins. Previously a meta app claimed any keyword parameter it recognized regardless of token position — even after a subcommand, and even if the subcommand defined the same name. In v5 (default parse_mode="fallthrough"), when both levels define the same name, the subcommand wins for tokens placed after it.

@app.meta.default
def main(
    *tokens: Annotated[str, Parameter(show=False, allow_leading_hyphen=True)],
    verbose: Annotated[bool, Parameter(alias="-v")] = False,
):
    app(tokens)

@app.command
def greet(name: str, *, version: Annotated[bool, Parameter(alias="-v")] = False):
    ...

$ myapp greet -v Alice          # after the subcommand: CHANGED
# v4: meta verbose=True;  greet version=False
# v5: meta verbose=False; greet version=True   (child wins)

$ myapp -v greet Alice          # before the subcommand: unchanged
# v4: meta verbose=True;  greet version=False
# v5: meta verbose=True;  greet version=False

Only placement after the subcommand changed. To reject parent-level parameters placed after a subcommand entirely, use parse_mode="strict".

Forwarded *tokens preserve the -- delimiter. A forwarding meta's raw-stream capture parameter (*tokens with allow_leading_hyphen=True) now keeps a user-typed end-of-options delimiter, so the re-parse inside app(tokens) still treats the trailing tokens as positional.
```
$ myapp sub -- -x
# v4: meta captured ("sub", "-x")        -> Error: Unknown option: -x.
# v5: meta captured ("sub", "--", "-x")  -> inner parse keeps -x positional
```
Wrappers that manually re-inserted -- as a workaround will now see it twice — remove the workaround. Leaf commands (that don't forward) are unchanged: the delimiter is consumed as a marker and never appears in bound values.

A greedy *args subcommand claims all post-command tokens. A subcommand whose only positional parameter is *args with allow_leading_hyphen=True genuinely claims every token after the command; meta parameters placed after such a subcommand no longer bubble up.

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

@app.command
def sub(*args: Annotated[str, Parameter(allow_leading_hyphen=True)]):
    ...

$ myapp sub --user=alice
# v4: meta user=alice;   sub args=()
# v5: meta user=default; sub args=('--user=alice',)

Place meta parameters before the subcommand, or give the subcommand explicit keyword parameters instead of a catch-all.

User parameters shadow --help / --version. A command may now define its own parameter named like an auto-registered help/version flag; the token binds to the user's parameter instead of triggering the handler, and the command's help page lists the user's parameter.
```
@app.command
def sub(*, version: bool = False):
    return version
```
```
$ myapp sub --version
# v4: printed the app version
# v5: binds the version parameter to True
```
Shadowing is per-flag (--help still works when only --version is shadowed), and commands taking **kwargs are NOT affected — they keep automatic --help/--version. If a command shadows --help, a --version token in the same invocation triggers version printing (interception runs before binding).
cyclopts tree: -d now disables descriptions. Previously -d was a positive alias for --description — a no-op, since descriptions are on by default. It is now a negative alias (equivalent to --no-description), as originally intended.
```
$ cyclopts tree my_script.py -d
# v4: descriptions shown (flag was a no-op)
# v5: descriptions hidden
```
Parse errors exit with code 2. CLI usage errors (unknown option, missing argument, coercion failure, ...) now exit with code 2, matching argparse and Click. Previously they exited with 1, indistinguishable from a command that ran and reported failure (the default result_action maps a False return to exit code 1). Application-level exit codes and 130 for keyboard interrupts are unchanged.
```
$ myapp --bogus; echo $?
# v4: 1
# v5: 2
```
--version respects the -- delimiter. A --version token after the end-of-options delimiter is positional data, not a version request — matching how --help already behaved.
```
$ myapp -- --version
# v4: printed the app version (command never ran)
# v5: the command runs; "--version" is bound positionally
```
result_action names are validated eagerly. An invalid action name now raises a descriptive ValueError (listing the valid actions) at App construction, attribute assignment, or invocation-time override — before any command executes. Previously an invalid name was silently accepted and only raised a bare, message-less ValueError at result-handling time, after the command had already run.
```
App(result_action="bogus")          # ValueError, raised immediately
app(tokens, result_action="bogus")  # ValueError, command never runs
```

Features

App.parse_mode — hierarchical parameter scoping between meta apps and subcommands. Two modes:
- "fallthrough" (default): meta parameters may appear anywhere in the token stream; post-command tokens the subcommand leaves unconsumed bubble up to the meta. When both levels define the same flag, the child wins.
- "strict": parameters bind only at the command level where they appear — Click/Typer-style scoping. A meta parameter placed after a subcommand is rejected with a scope-aware hint (Did you mean to place it directly after "myapp"?), and help pages exclude parent meta parameters at the child level. Shell completion respects both modes.
parse_mode is inherited by subapps unless explicitly overridden. See the new "Parse Mode" docs page.

Combined short options are resolved against the MERGED flag namespace of both levels — the person typing myapp cmd -xvf doesn't know which level implements each flag, so a single GNU left-to-right scan of the merged table routes each character to its owner (subcommand wins same-letter collisions; the first value-taking option absorbs the remainder or next token as its value; unknown characters are reported by the subcommand).
```
# meta owns -v and -u (value-taking); cmd owns -x and -f:
$ myapp cmd -xvf        # -x -f -> cmd; -v -> meta
$ myapp cmd -xuroot     # -x -> cmd; meta user="root" (attached value)
$ myapp cmd -xu alice   # -x -> cmd; meta user="alice" (next token)
```
Other cross-scope cases: a meta flag interleaved between a child option and its value binds at the meta while the child pairs its option with the value, and a meta option missing its value reports the real "requires an argument" error instead of a misleading "Unknown option".
Variable token-lengths within a Union. Members that consume a different number of tokens can now coexist. Order matters: the longer (multi-token) member should come first so it gets first claim on the tokens.
```
def main(value: tuple[int, int] | int): ...
# --value 5      -> 5
# --value 1 2    -> (1, 2)
```
On v4 this raises Cannot Union types that consume different numbers of tokens.
list[Union[...]] with differing token-lengths. Each element is matched independently against the union members.
```
def main(coords: list[tuple[int, int] | int]): ...
```

null/none (case-insensitive) parse to None. Applies to optional types. Union ordering decides the result: a member that legitimately accepts the literal string wins first.

def main(value: int | None): ...      # --value none  -> None
def main(path: Path | None): ...      # --path none   -> Path("none")  (Path matches first)
def main(value: str | None): ...      # --value none  -> "none"        (str matches first)
# works inside collections too:  list[int | None]  "1 none 3" -> [1, None, 3]

ArgumentCollection.copy(), including copy(reset_tokens=True) for a copy whose Arguments share metadata but carry fresh empty token lists.
Dynamic per-parameter shell completion #917
- A Parameter.completer callable receives a CompletionContext and returns context-aware suggestions, so completions can depend on values only known at runtime (git branches, running containers, rows from a database). Works in bash/zsh/fish.
- ```
def complete_user(ctx):
    return load_users()  # e.g. {"alice": "admin", "bob": "member"} -> {value: description}

@app.command
def promote(user: Annotated[str, Parameter(completer=complete_user)]): ...
```
Parameter.metavar and type-derived value placeholders #919
- Keyword-only parameters now show a value placeholder in the help panel (e.g. --config PATH), separating a value's shape from a positional parameter's display identifier.
- Set Parameter.metavar to override the placeholder, or turn it off via the formatter. Closes #885.
- ```
def main(config: Annotated[Path, Parameter(metavar="FILE")]): ...  # shows "--config FILE"
```
Themeable help colors #916
- Every color in the help output is now a bare cyclopts.* Rich named style, so you can recolor any part of the help page by supplying your own theme; your overrides win over the built-in defaults.
- This includes the panel border (cyclopts.border), the usage line (cyclopts.usage), parameter/command names (cyclopts.name), and the metadata annotation styles ([default], [choices], [required], ...).
Per-group help panel styling via Group.theme #916
- A Group can now carry its own theme (a dict or Rich Theme) to style just that group's panel independently of the rest of the help page.
- ```
danger = Group("Danger Zone", theme={"cyclopts.border": "red", "cyclopts.name": "bright_red"})
```
App.interactive_shell() improvements #941
- New intro banner (supports Rich markup; None uses the default banner, "" prints nothing).
- New history option (True for a default history-file location, or a path) backed by readline.
- New remap_flags so bare help/version words at the root map to their long flags.
- quit words and registered commands are handled more robustly, with registered commands and meta commands taking precedence over quit words.
- readline is now imported lazily.

Fixes

fix(help): show CHOICE metavar for choice parameters and collapse variadic-collection metavars to X... by @BrianPugh in #949

Misc

RST help now uses rich-rst v2 (has friendly licensing). Dependency pin moved from rich-rst>=1.3.1,<3 to rich-rst>=2.0.1,<3.

Full Changelog: BrianPugh/cyclopts@v4.25.3...v5.0.0

`v4.25.3`

Compare Source

Bug Fixes

Fix nested json-object parsing by routing JSON-object tokens through the Argument layer (#953) by @BrianPugh in #954
Recognize a JSON-object token for types whose fields consume all tokens by @BrianPugh in #955
Explain unhashable element types when converting to set/frozenset by @BrianPugh in #956

Full Changelog: BrianPugh/cyclopts@v4.25.2...v4.25.3

`v4.25.2`

Compare Source

Bug Fixes

reject NaN in numeric range validators by @kudala-bharani in #942

New Contributors

@kudala-bharani made their first contribution in #942

Full Changelog: BrianPugh/cyclopts@v4.25.1...v4.25.2

`v4.25.1`

Compare Source

Bug Fixes

Keep allow_leading_hyphen=True positional values intact when a later char matches a short option by @BrianPugh in #934
Honor subcommand-level configuration via the invoked command's app-stack (#933) by @BrianPugh in #938

Internal

ci: fail a hung test in 60s via pytest-timeout instead of stalling the job by @BrianPugh in #937

special thanks to @yilei for identifying these bugs!

Full Changelog: BrianPugh/cyclopts@v4.25.0...v4.25.1

`v4.25.0`

Compare Source

Features

Interactive shell no longer exits on Ctrl-C or malformed input by @BrianPugh in #925
- Report unbalanced quotes as a TokenizationError instead of a raw ValueError by @BrianPugh in #926

Bug Fixes

fix(docs): render root default_command params/usage in RST (Sphinx) by @BrianPugh in #924

Docs

Fix link formatting in Sphinx to be blue even in code blocks by @relativityspace-jsmith in #922

Internal

ci: fix pre-commit cache key so hook environments are actually reused by @BrianPugh in #928
ci: make codecov statuses informational (non-blocking) by @BrianPugh in #930
ci: speed up CI ~40% by parallelizing lint/type-check/docs and caching setup by @BrianPugh in #931
Remove low-value restatement comments by @BrianPugh in #929

New Contributors

@relativityspace-jsmith made their first contribution in #922

Full Changelog: BrianPugh/cyclopts@v4.24.0...v4.25.0

`v4.24.0`

Compare Source

Features

Add Parameter.choices by @BrianPugh in #921
Configurable encoding for file Config sources by @BrianPugh in #918
Add "sys_exit_if_non_zero_else_return" result action and document result_action modes by @BrianPugh in #907
Sphinx: add :anchor-prefix:/:anchor-suffix: to namespace ref labels by @BrianPugh in #913

Bug Fixes

register field-name CLI options when pydantic validate_by_name is set by @xyf5432 in #909
Use module name for unnamed apps and drop duplicate root anchors when generating RST documentation by @BrianPugh in #912

Docs

Refresh Typer comparison pages against Typer 0.27.1 by @BrianPugh in #911
Document remapping metadata annotation styles via theme by @BrianPugh in #915
- Note: color-management is much better handled in the upcoming v5.

New Contributors

@xyf5432 made their first contribution in #909

Full Changelog: BrianPugh/cyclopts@v4.23.3...v4.24.0

`v4.23.3`

Compare Source

Bug Fixes

Fix deprecated not being rendered by @wallento in #900
Split JSON documents on newlines when rendering decode errors by @dylanpulver in #902
Render flattened subapp commands in generated docs by @BrianPugh in #905
Handle a config file whose document root is empty or not a mapping by @dylanpulver in #906

New Contributors

@wallento made their first contribution in #900
@dylanpulver made their first contribution in #902

Full Changelog: BrianPugh/cyclopts@v4.23.2...v4.23.3

`v4.23.2`

Compare Source

What's Changed

Add type-hints to help copy methods by @Ichunjo in #899

New Contributors

@Ichunjo made their first contribution in #899

Full Changelog: BrianPugh/cyclopts@v4.23.1...v4.23.2

`v4.23.1`

Compare Source

Bug Fixes

Honor a dict value type's Parameter annotation by @BrianPugh in #890
Fix Number, Path, and Slice validators silently skipping set, frozenset, and dict elements by @BrianPugh in #891
Skip var-keyword parameters in shell completion generation by @BrianPugh in #897

Full Changelog: BrianPugh/cyclopts@v4.23.0...v4.23.1

`v4.23.0`

Compare Source

Performing this as a minor release as it may break setups who rely on strict snapshot testing.

Bug Fixes

Fix inconsistent whitespace after parameter colon in markdown docs (#887) by @BrianPugh in #888

Full Changelog: BrianPugh/cyclopts@v4.22.5...v4.23.0

`v4.22.5`

Compare Source

Bug Fixes

Various fixes around abstract collection types:

Fix TypeError when an abstract collection parameter is given no values by @BrianPugh in #881
Support Collection, Container, and Reversible type hints by @BrianPugh in #882
Add --empty-* flags for abstract collection hints by @BrianPugh in #883

Full Changelog: BrianPugh/cyclopts@v4.22.4...v4.22.5

`v4.22.4`

Compare Source

Bug Fixes

Singularize the ConsumeMultipleError noun when the count is 1 by @BrianPugh in #879

Full Changelog: BrianPugh/cyclopts@v4.22.3...v4.22.4

`v4.22.3`

Compare Source

Bug Fixes

Fix parsing Enum types with __init__ defined. by @BrianPugh in #877

Full Changelog: BrianPugh/cyclopts@v4.22.2...v4.22.3

`v4.22.2`

Compare Source

Bug Fixes

Fix spurious MissingArgumentError for explicitly-supplied empty mappings by @BrianPugh in #871
Honor an attached =value on Parameter.count=True flags instead of silently dropping it by @BrianPugh in #872
Report a clean error when a config node expected to be a table is not by @BrianPugh in #873

Full Changelog: BrianPugh/cyclopts@v4.22.1...v4.22.2

`v4.22.1`

Compare Source

Bug Fixes

Split iterable Parameter(env_var=...) values via env_var_split by @chuenchen309 in #866
Report the offending value when a boolean flag gets a non-bool =value by @chuenchen309 in #865

Full Changelog: BrianPugh/cyclopts@v4.22.0...v4.22.1

`v4.22.0`

Compare Source

Bug Fixes

Fix config search_parents=False still walking parent directories by @chuenchen309 in #864
Fix reject malformed timedelta strings instead of silently ignoring garbage by @chuenchen309 in #863
Fix parsing signed base-prefixed ints (-0xFF, +0o17) by @chuenchen309 in #862

Full Changelog: BrianPugh/cyclopts@v4.21.2...v4.22.0

`v4.21.2`

Compare Source

Bug Fixes

Fix -- delimiter leaking into an "Unknown option" error by @chuenchen309 in #861

New Contributors

@chuenchen309 made their first contribution in #861

Full Changelog: BrianPugh/cyclopts@v4.21.1...v4.21.2

`v4.21.1`

Compare Source

Bug Fixes

complete zsh subcommands after meta positionals by @Sanjays2402 in #860

New Contributors

@Sanjays2402 made their first contribution in #860

Full Changelog: BrianPugh/cyclopts@v4.21.0...v4.21.1

`v4.21.0`

Compare Source

Feature

Add Parameter.negative_alias to append extra names to a flag's negative form (e.g. a short -d) without dropping the generated --no-*/--empty-* names. Mirrors name/alias. By @BrianPugh in #859

Bug Fixes

Fix #857: a dataclass command with a default_factory field could raise a spurious "Input should be a valid list" validation error simply because pydantic was imported anywhere in the program. Factory defaults are now invoked during introspection, so the produced value (rather than the <factory> sentinel) is used as the default and shown in help text — consistent across dataclass, attrs, and pydantic. By @BrianPugh in #858

Full Changelog: BrianPugh/cyclopts@v4.20.0...v4.21.0

`v4.20.0`

Compare Source

Features

Add cyclopts tree command and App.command_tree() by @BrianPugh in #845

Bug Fixes

Fix the leading-hyphen regression introduced by #639. by @yilei in #843
Propagate consume_multiple to nested structured-type fields by @BrianPugh in #846

New Contributors

@yilei made their first contribution in #843

Full Changelog: BrianPugh/cyclopts@v4.19.0...v4.20.0

`v4.19.0`

Compare Source

Features

New Attribute: Parameter.short_alias to automatically generate short aliases for parameters. by @mgielda in #831
Add ArgumentCollection.filter_by(missing=...) for required/conditionally-required fields. by @BrianPugh in #840

New Contributors

@mgielda made their first contribution in #831

Full Changelog: BrianPugh/cyclopts@v4.18.0...v4.19.0

`v4.18.0`

Compare Source

Features

Added native slice support by @BrianPugh in #835
- slice type-hints are now properly handled.
- Added cyclopts.validators.Slice
- Added cyclopts.types.NonEmptySlice convenience type.

Bug Fixes

Fix dropped Parameter metadata in nested Annotated/Optional/NewType types by @BrianPugh in #838

Full Changelog: BrianPugh/cyclopts@v4.17.0...v4.18.0

`v4.17.0`

Compare Source

Features & Bug Fixes

handle async commands in default_dispatcher for interactive shells by @BrianPugh in #827
Allow Parameter.show_default to be a string to display. by @BrianPugh in #833

Publishing

Add PyPI publish attestations to releases by @shaanmajid in #828
Harden PyPI publish workflow by @shaanmajid in #829

New Contributors

@shaanmajid made their first contribution in #828

Full Changelog: BrianPugh/cyclopts@v4.16.1...v4.17.0

`v4.16.1`

Compare Source

Bug Fixes

Fix fish completion for positional args and run fish tests in ci by @BrianPugh in #823
fix zsh completion recursion when prog_name matches a builtin helper by @BrianPugh in #825

Misc

add ubuntu-24.04-arm to the CI testing matrix by @BrianPugh in #822
docs: add missing typer Option imports in flag negation examples by @SAY-5 in #824

New Contributors

@SAY-5 made their first contribution in #824

Full Changelog: BrianPugh/cyclopts@v4.16.0...v4.16.1

`v4.16.0`

Compare Source

Features

Return-value objects can now declare their own exit code by defining a __cyclopts_returncode__ method, which is honored by all built-in result_action handlers. Custom result_action callables can opt in via the new cyclopts.resolve_returncode helper. By @BrianPugh in #818
PEP 692 support: when **kwargs is annotated as Unpack[SomeTypedDict], the TypedDict's fields are promoted to top-level CLI options instead of the generic --[KEYWORD] catch-all. Per-field Required / NotRequired markers are respected independently of the parent kwargs argument. By @BrianPugh in #819
CycloptsError.msg now accepts a rich.Text instance. Cyclopts' error-message style palette is exposed as cyclopts.exceptions.STYLE_OFFENDING_VALUE, STYLE_NAME, STYLE_VALID_CHOICE, STYLE_SUGGESTION, and STYLE_SOURCE . By @BrianPugh in #814

Full Changelog: BrianPugh/cyclopts@v4.15.0...v4.16.0

`v4.15.0`

Compare Source

Features

AddedApp.synonym, which declares alternate command name(s) that trigger a "Did you mean..." suggestion without registering the command under those names. Useful when a user types a semantically-equivalent word (e.g. remove vs uninstall) that the built-in fuzzy matcher would miss because the words aren't spelled similarly. Accepts a single str or an iterable of strings. Synonyms are not runnable and are hidden from --help.
```
@app.command(synonym=["remove", "rm"])
def uninstall(name: str): ...
```
```
$ my-script remove mypackage
Unknown command "remove". Did you mean "uninstall"? Available commands: uninstall.
```
If multiple commands declare the same synonym, all matching commands are suggested (Did you mean "uninstall" or "purge"?).
By @BrianPugh in #815

Full Changelog: BrianPugh/cyclopts@v4.14.1...v4.15.0

`v4.14.1`

Compare Source

What's Changed

use trusted publishing when uploading to pypi by @BrianPugh in #812

Full Changelog: BrianPugh/cyclopts@v4.14.0...v4.14.1

`v4.14.0`

Compare Source

What's Changed

Increase rich-rst version constraint upper-bound from <2.0.0 to <3.0.0 by @germa89 in #810

New Contributors

@germa89 made their first contribution in #810

Full Changelog: BrianPugh/cyclopts@v4.13.0...v4.14.0

`v4.13.0`

Compare Source

Features

Friendlier error message for enum/literal choices by @BrianPugh in #806
Add more rich formatting to CycloptsError printing. by @BrianPugh in #808

Full Changelog: BrianPugh/cyclopts@v4.12.0...v4.13.0

`v4.12.0`

Compare Source

Features

Allow for validators to be string(s) (class method forward reference) by @BrianPugh in #803

Full Changelog: BrianPugh/cyclopts@v4.11.2...v4.12.0

`v4.11.2`

Compare Source

Bug Fixes

Fix _should_attempt_json_list for detecting list[str] | None and Annotated annotations by @BrianPugh in #800

Full Changelog: BrianPugh/cyclopts@v4.11.1...v4.11.2

`v4.11.1`

Compare Source

Bug Fixes

Include meta-apps when assembling usage string by @BrianPugh in #793
Add missing python3.14 classifier by @BrianPugh in #796
Fix untyped boolean negative name derivation by @BrianPugh in #798
Various completion fixes by @BrianPugh in #794

Full Changelog: BrianPugh/cyclopts@v4.11.0...v4.11.1

`v4.11.0`

Compare Source

Features

Added usage_name override for configuring docs creation by @BrianPugh in #791
Added granular help for dict[str, dataclass-like] params by @wrongbad in #787

Bug Fixes

Improved type hints/completion for attrs converter functions. by @BrianPugh in #784
Fix token_count for discriminated unions by @BrianPugh in #789

Misc Internal

prefer using consistent is_annotated over get_origin by @BrianPugh in #792

New Contributors

@wrongbad made their first contribution in #787

Full Changelog: BrianPugh/cyclopts@v4.10.2...v4.11.0

`v4.10.2`

Compare Source

Features

Convenience Types:
- NormFloat - A float in the range [0, 1]
- SignedNormFloat - A float in the range [-1, 1]
- PercentInt - An int in the range [0, 100]
- By @BrianPugh in #778

Bug Fixes

Fix handling of Union'd iterables by @BrianPugh in #781

Full Changelog: BrianPugh/cyclopts@v4.10.1...v4.10.2

`v4.10.1`

Compare Source

Bug Fixes

Fix ValueError when parsing pre-release Pydantic versions by @BrianPugh in #775

Full Changelog: BrianPugh/cyclopts@v4.10.0...v4.10.1

`v4.10.0`

Compare Source

Features

New App.error_formatter field to control out CycloptsError are displayed. The formatter receives a CycloptsError and returns any rich-printable object, replacing the default CycloptsPanel. Can be set at app creation or passed as a runtime override to parse_args / __call__ / run_async. by @BrianPugh in #771

By default (without error_formatter), errors are displayed in a Rich panel:

$ my-app foo
╭─ Error ─────────────────────────────────────────────────╮
│ Invalid value "foo" for "VALUE": unable to convert      │
│ "foo" into int.                                         │
╰─────────────────────────────────────────────────────────╯

With a custom formatter, you can simplify or restyle the output:

from cyclopts import App, CycloptsError

def my_error_formatter(e: CycloptsError):
    return f"[bold red]error:[/bold red] {e}"

app = App(error_formatter=my_error_formatter)

@app.default
def main(value: int):
    pass

app()

$ my-app foo
error: Invalid value "foo" for "VALUE": unable to convert "foo" into int.

Full Changelog: BrianPugh/cyclopts@v4.9.0...v4.10.0

`v4.9.0`

Compare Source

Features

Parameter.consume_multiple now accepts int or tuple[int, int] for min/max element bounds.
- An int sets a minimum (e.g. consume_multiple=2 requires at least 2 values).
- A tuple sets both bounds (e.g. consume_multiple=(1, 3) requires 1–3 values).
- Violations raise ConsumeMultipleError.
```
# Require 1–3 space-separated values: --files a.txt b.txt c.txt
files: Annotated[list[str], Parameter(consume_multiple=(1, 3))]
```
By @BrianPugh in #764
New field Parameter.allow_repeating controls whether an option can be specified multiple times.
- False raises RepeatArgumentError on repeat (useful with consume_multiple).
- True allows repeats for any type; scalars use last-wins semantics.
- None (default) preserves existing behavior: lists accumulate, scalars error.
```
# Allow --files a b c, but not --files a --files b
files: Annotated[list[str], Parameter(consume_multiple=True, allow_repeating=False)]
# Last value wins: --color red --color blue → "blue"
color: Annotated[str, Parameter(allow_repeating=True)]
```
By @BrianPugh in #768
New field App.help_prologue displays text before the "Usage" line in help output.
Inherited by subcommands; override per-command or set to "" to disable.
```
app = App(help_prologue="myapp v1.0.0 — https://example.com")
```
By @tahv in #769

Bug Fixes

Positional-only list parameters no longer consume tokens that appear after interleaved keyword arguments. a b --bar 8 d now correctly errors instead of silently assigning d to the positional list. By @BrianPugh in #766

Other

Added contributing guide. By @BrianPugh in #767

New Contributors

@tahv made their first contribution in #769

Full Changelog: BrianPugh/cyclopts@v4.8.0...v4.9.0

`v4.8.0`

Compare Source

Features

Lazy Loading --help improvements.

Previously, running --help on a parent command would import and resolve all lazy child commands, negating much of the startup-time benefits. Now, parent --help displays lazy commands without triggering any imports.

To show descriptions for lazy commands in --help output, provide help= at registration time:

app.command("myapp.commands:deploy", help="Deploy the application.")

Other metadata (group=, show=, sort_key=) can also be provided at registration time and will be used for help display without resolving the command.

Lazy commands are now only resolved when:

The specific command is executed
The specific command's own --help is requested (e.g., myapp deploy --help)
The command is accessed directly via app["command_name"]

Thanks to @zzstoatzz for the initial contribution in #757.

Full Changelog: BrianPugh/cyclopts@v4.7.0...v4.8.0

`v4.7.0`

Compare Source

Features

Better "just works" shell-completion install location for oh-my-zsh users. By @BrianPugh in #758

Bug Fixes

Fix shell-completion for nested inner annotations (e.g. list[ExistingFile]). by @BrianPugh in #760

Full Changelog: BrianPugh/cyclopts@v4.6.0...v4.7.0

`v4.6.0`

Compare Source

Features

Added Parameter.requires_equals. When enabled, values for keywords must be provided by an =. For example, --foo=bar. --foo bar would raise an error telling the user to use a =. Defaults to False (same behavior as before). by @BrianPugh in #751

Full Changelog: BrianPugh/cyclopts@v4.5.4...v4.6.0

`v4.5.4`

Compare Source

Bug Fixes

Fix short-flag deduplication logic. Previously if 2 same-letter flags were provided (e.g. -n and -N), only -n would be displayed on the help page. Does not impact actual value parsing. By @BrianPugh in #748

Docs

Reference correct callable in entrypoints example by @joelostblom in #746

Full Changelog: BrianPugh/cyclopts@v4.5.3...v4.5.4

`v4.5.3`

Compare Source

Bug Fixes

List correct values when unsupported value passed to Enum param by @joelostblom in #745

New Contributors

@joelostblom made their first contribution in #745

Full Changelog: BrianPugh/cyclopts@v4.5.2...v4.5.3

`v4.5.2`

Compare Source

Bug Fixes

Resolve lazy commands when generating shell completion by @BrianPugh in #743

Full Changelog: BrianPugh/cyclopts@v4.5.1...v4.5.2

`v4.5.1`

Compare Source

Bug Fixes

Fix Annotated/Decorator Parameter resolution when Optional by @BrianPugh in #741

Full Changelog: BrianPugh/cyclopts@v4.5.0...v4.5.1

`v4.5.0`

Compare Source

Features

Introduces cyclopts.types.StdioPath. This type subclasses pathlib.Path. If the special string - is supplied, then the object will read/write to stdin/stdout. Only available on python >=3.12 by @BrianPugh in [#737](http

❗ Important

✂ PR body was truncated to here.

Configuration

📅 Schedule: (UTC)

Branch creation
- At any time (no schedule defined)
Automerge
- At any time (no schedule defined)

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

If you want to rebase/retry this PR, check this box

This PR was generated by Mend Renovate. View the repository job log.

renovate · 2026-09-24T01:59:45Z

⚠️ Artifact update problem

Renovate failed to update an artifact related to this branch. You probably do not want to merge this PR as-is.

♻ Renovate will retry this branch, including artifacts, only when one of the following happens:

any of the package files in this branch needs updating, or
the branch becomes conflicted, or
you click the rebase/retry checkbox if found above, or
you rename this PR's title to start with "rebase!" to trigger it manually

The artifact failure details are included below:

File name: uv.lock

Downloading cpython-3.9.25-linux-x86_64-gnu (download) (27.0MiB)
 Downloaded cpython-3.9.25-linux-x86_64-gnu (download)
Using CPython 3.9.25
error: No solution found when resolving dependencies for split (markers: python_full_version >= '3.14')
  cause: Because only cyclopts<=5.0.0b3 is available and your project depends on cyclopts>=5.1,<6, we can conclude that your project's requirements are unsatisfiable.

hint: While the active Python version is 3.9, the resolution failed for other Python versions supported by your project. Consider limiting your project's supported Python versions using `requires-python`.

hint: `cyclopts` was filtered by `exclude-newer` to only include packages uploaded before 2026-09-19T20:10:42.323084062Z. The latest version satisfying the requirement is v5.1.0, published at 2026-09-29T19:02:23.499Z. Consider using `exclude-newer-package` to override the cutoff for this package.

renovate Bot requested a review from woutervh as a code owner September 24, 2026 01:59

Update dependency cyclopts to v5

8253ac7

renovate Bot force-pushed the renovate/cyclopts-5.x branch from e477840 to 8253ac7 Compare September 29, 2026 20:10

Navigation Menu

Update dependency cyclopts to v5 - #22

Update dependency cyclopts to v5#22
renovate[bot] wants to merge 1 commit into
mainfrom
renovate/cyclopts-5.x

renovate Bot commented Sep 24, 2026 •

edited

Loading

Uh oh!

renovate Bot commented Sep 24, 2026 •

edited

Loading

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

0 participants

Conversation

renovate Bot commented Sep 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Release Notes

Features

Breaking

Features

Fixes

Misc

Bug Fixes

Bug Fixes

New Contributors

Bug Fixes

Internal

Features

Bug Fixes

Docs

Internal

New Contributors

Features

Bug Fixes

Docs

New Contributors

Bug Fixes

New Contributors

What's Changed

New Contributors

Bug Fixes

Bug Fixes

Bug Fixes

Bug Fixes

Bug Fixes

Bug Fixes

Bug Fixes

Bug Fixes

Bug Fixes

New Contributors

Bug Fixes

New Contributors

Feature

Bug Fixes

Features

Bug Fixes

New Contributors

Features

New Contributors

Features

Bug Fixes

Features & Bug Fixes

Publishing

New Contributors

Bug Fixes

Misc

New Contributors

Features

Features

What's Changed

What's Changed

New Contributors

Features

Features

Bug Fixes

Bug Fixes

Features

Bug Fixes

Misc Internal

New Contributors

Features

Bug Fixes

Bug Fixes

Features

Features

Bug Fixes

Other

New Contributors

Features

Features

Bug Fixes

Features

Bug Fixes

renovate Bot commented Sep 24, 2026 •

edited

Loading

renovate Bot commented Sep 24, 2026 •

edited

Loading