# Changelog

## 0.32

### 0.32.2
- fix: Negated boolean args rendering default help text in incorrect location.
- fix: Preserve multiline help text formatting.
- fix: Dedent attribute docstrings' content.

### 0.32.1

- fix: kw_only dataclass inheritance incorrect ordering.

### 0.32.0
- feat: Add `epilog=` field on commands for text which should go after the argument help.
- refactor: All root objects (Command/Arg/Subcommand) to have "Final" variants which represent their post-normalization shape.
- feat: Add support for fixed size optional-value num_args arguments (e.g. --foo / --foo 4).
- feat: Add `aliases=` support for subcommands. Each entry is either a string (visible alias) or a `cappa.Alias(name, hidden=..., deprecated=...)` for finer control. Hidden aliases dispatch but are omitted from help and completion; deprecated aliases emit a runtime warning when used. Collisions are detected at construction time.
- fix: Display Args with the same group identity as alternatives in helptext on the same line.
- fix: Ensure automatic bool variants (--foo/--no-foo) are mutually exclusive.
- fix: Allow negative number arguments and option values.
- fix: Precalculate implicit deps during class construction rather than traversing the output shape.
- fix: Thread `output` into `parse_result.instance` resolution in `parse`/`parse_async`/`invoke`/`invoke_async`, so `cappa.Exit` raised from `Arg(parse=...)` callbacks renders an error message instead of silently exiting non-zero.
- refactor: Destructured implementation to be more like Arg handling to fix default and helptext behavior. 
- fix: Destructured args to inherit `default_long` and `default_short`.

## 0.31

### 0.31.0
- fix: Allow options accepting zero-length unbounded num_args.
- feat: Apply default parsing automatically, with Arg.parse_inference == False to disable.

## 0.30

### 0.30.4
- fix: Use of a synchronous context manager inside an `invoke_async` invoke context.
- fix: Stripped type aliases losing e.g. Dep metadata.

### 0.30.3

- fix: Scenario where static defaults were not being shown in helptext.

### 0.30.2

- fix: Prioritize Arg.default over dataclass-level default.

  Technically this might be considered a breaking change, but the original behavior
  was unintended. `Arg.default` should **always** take precedence over inferred
  defaults or class-level defaults.

  This only manifests in cases where someone was supplying both a class-level default
  and an `Arg` level default like: `foo: Annotated[int, Arg(default=5)] = 10`. This
  **should** result in a `5` default but was erroneously yielding `10`.

  There's no obvious practical reason to ever supply both with the old behavior
  because the `Arg.default` would never have an effect. Now, it's possible to
  use the `Arg.default` distinctly from the class level default outside the context
  of use with cappa.

### 0.30.1

- fix: Infer class constructor as default for `Destructured` class.

### 0.30.0

- fix: BREAKING CHANGE: Provide simpler `Destructured[T]` annotation.

  Previously `Annotated[T, Arg(destructured=Destructured())]`, this was
  comparatively verbose, when there is currently practical use for configuring
  `Arg` options on the destructured root argument.

  As such the `Destructured` name has been repurposed as a convenience annotation
  similar to `Subcommands`.

  The forms: `Annotated[T, Destructure]`, `Annotated[T, Arg.destructured()]`,
  `Annotated[T, Arg(destructure=True]`, and `Annotated[T, Arg(destructure=Destructure())]`
  still remain in the event future use is assigned to configuration on the root field.

- fix: Destructured relative context, e.g. counting.
- fix: Add support for explicit type alias `Dep`s.
- fix: Propagation of mutually exclusive options that map to the same `Arg.field_name`.

## 0.29

### 0.29.1

- fix: Lower bounds of dependency versions and test for them.
- feat: Handle python 3.12 syntax for explicit `type <Type>` aliases.
- fix: Explicit choice sequence runtime error.

### 0.29.0

- fix: Undocumented completions.
- docs: Add argument validation documentation.
- feat: Test against python 3.14.
- fix: Apply pyright strict typing.
- fix: Function callables ability to depend on implicit Deps.
- docs: Improve docs relating to `Output`.

## 0.28

### 0.28.1

- fix: Sphinx warning in docutils extension with `--jobs`.

### 0.28.0

- feat: Allow `deps` to be indirect function reference strings.
- feat: Allow styling of individual sections of argument help text.

## 0.27

### 0.27.3
- fix: Make rich/typing-extensions version requirements more precise.

### 0.27.2
- fix: Ensure API doesnt yield pyright errors in user code.

### 0.27.1
- fix: Handle multiple = in explicit arg.

### 0.27.0
- feat: Add "Self" concept for invoke dependencies.

## 0.26

### 0.26.6
- fix: Typo in the exported member `HelpFormattable` 

### 0.26.5
- fix: Coerce `Env(default=None)` to `Empty` to avoid interpreting the value as a string.

### 0.26.4
- fix: Ensure `propagate=True` args supply the correct parent context to the arg's action handler.

### 0.26.3
- fix: Reexport Empty/EmptyType types at the root.

### 0.26.2

- fix: Optional positional arguments should not get a default value from their action.

### 0.26.1

- fix: Default formatting when value is None/Empty and formatter is supplied.

### 0.26.0

- feat: Add `Default` object with associated fallback semantics for sequences of default handlers.
- feat: Add `ValueFrom` for handling default_factory lazily, as well as arbitrary function dispatch.
- feat: Add `State` as object accessible to invoke, Arg.parse, and ValueFrom.callable for sharing
  state amongst different stages of argument parsing.
- fix: Skip non-init fields in dataclasses.
- fix: Required positional arguments in the native parser.
- fix: Infer num_args on unbounded sequence options (e.g. `list[list[str]]` annotation on an option).
- feat: Add DefaultFormatter as optional input to `show_default`.

## 0.25

### 0.25.1

- fix: Perform choices validation after parse/mapping time.

### 0.25.0

- feat: Add `Arg.propagate`.

## 0.24

### 0.24.3

- fix: Incorrect handling of methods in Arg.parse.

### 0.24.2

- fix: Literal contained inside non-variadic tuple should not imply "choices".
- fix: Optional non-variadic tuple should be allowed (None shouldn't fail arity check).

### 0.24.1

- feat: Add Group.section to enable ordering of groups separately from the items within them.
- fix: invoke(help_formatter=...) not applying to explicitly decorated commands.

### 0.24.0
- feat: Support native inference parser for dataclass-like annotation
s.
  Note this contains a minor breaking changes:

  * The `Arg.annotations` attribute was swapped for `Arg.type_view`. This was
    never a documented feature, but rather a side-effect required to implement
    certain built-in parser inferences. Swapping to `type_view` exposes strictly
    more information, and in a nicer interface.

- feat: User defined parsers can access the `TypeView` by accepting it as an argument.
- feat: Add new API for defining subcommands as methods.
- feat: Add Arg.show_default option to optionally avoid displaying default in help text.
- fix: Only show_default on `--*/--no-*` pair bool arguments for the actual default.

## 0.23

### 0.23.0
- fix: Avoid storing has_value=False values in the parser.
- feat: Introduce `Arg.destructure()` and `Arg.has_value`.
- chore: Swap custom MISSING/missing for EmptyType/Empty.
- refactor: Adopt the type-lens package.

## 0.22

### 0.22.5

- fix: Refactor parser combinators into dedicated module, and document the behavior more thoroughly.
- refactor: Pull handling of `--no-*` bool arguments out of the parser
- fix: Only apply `--no-*` handling when there is both a positive and negative variant

### 0.22.4

- fix: Avoid applying annotated type parsing to default value.

### 0.22.3

- fix: Ensure compatibility with python 3.13

### 0.22.2

- fix: Ensure `Arg.choices` is inferred when `T | None` where `T` would have inferred `choices` is encountered.

### 0.22.1

- fix: Route arg help formatting through markdown processing.

### 0.22.0

- feat: Allow "attribute docstrings" as additional method of documenting args.

## 0.21

### 0.21.2

- fix: action inference when `default` is an `Env`.

### 0.21.1

- feat: Update automatic inference to support `date`, `time`, and `datetime` parsing (for isoformat).

### 0.21.0

- feat: Add `help_formatter` system wherein help text rendering can be customized
  to include or exclude things like default values, or choices. Notably changes
  to include default values in help text by default.

## 0.20

### 0.20.1

- feat: Improve union error message.

### 0.20.0

- feat: Implement exclusive argument groups.

## 0.19

### 0.19.1

- fix: Eagerly attempt pydantic BaseModel import to ensure its skipped if unavailable.

### 0.19.0

- feat: Add support for `msgspec` based class definitions.

## 0.18

## 0.18.1

- feat: Add `deprecated` option, allowing deprecation of args, options, and subcommands

### 0.18.0

- feat: Add `default_short=False` and `default_long=False` options to command
  for ease of defining option-heavy commands.

## 0.17

### 0.17.3

- fix: Ensure class default combined with `default=Env(...)` still attempts to
  read env var (rather than just unconditionally taking the class default).

### 0.17.2

- Increase minimum typing_extensions bound to reflect actual dependency.

### 0.17.1

- Fixes bounded-tuple options like `tuple[str, str]` to infer as `num_args=2`
- Fixes bounded-tuple options to fail parsing if you give it a different number
  of values
- Fixes "double sequence" inference on explicit `num_args=N` values which would
  produce sequences. I.e. infer `action=ArgAction.set` in such cases to avoid
  e.x. `num_args=3, action=ArgAction.append`; resulting in nonsensical nested
  sequence `["[]"]`

### 0.17.0

- feat: Add `hidden=True/False` option to Command, which allows hiding
  individual subcommands options.

## 0.16

### 0.16.6

- fix: Correct the testing.CommandRunner deps signature.

### 0.16.5

- fix: Error short help should be contextual to the failing command.

### 0.16.4

- fix: Ensure optional bool retains bool action inference.

### 0.16.3

- fix: Use eval_type_backport to allow new syntax in python 3.8/9.

### 0.16.2

- feat: Improve parse error formatting. Include short help by default.

### 0.16.1

- feat: Support `Dep` on function based commands.

### 0.16.0

- feat: Add support for `BinaryIO` and `TextIO` for representing preconfigured
  file objects to be returned the caller.

## 0.15

### 0.15.4

- feat: Support pydantic v1.

### 0.15.3

- fix: Incorrect error message when using an invalid base class type.

### 0.15.2

- fix: Process `action` inference, taking into account `Optional`/`| None`.

### 0.15.1

- feat: Support explicit context managers as invoke dependencies.

### 0.15.0

- feat: Add docutils directive extension.

## 0.14

### 0.14.3

- fix: Handle TypeError in mapping failures

### 0.14.2

- fix: Default bool fields to `False` when omitted.

### 0.14.1

- fix: zsh completion script error

### 0.14.0

- feat: Support functions as interface for simple CLIs.

## 0.13

### 0.13.2

- Support "discriminated unions" (i.e. unions which have type distinctions that
  affect how they're mapped.)

### 0.13.1

- Prefer the field default (if set), if an `Env` is used, but no default is
  supplied.

### 0.13.0

- Support `yield` in invoke dependencies to support context-manager-like
  dependencies (for example those which require cleanup).

## 0.12

### 0.12.1

- When used in combination with `parse=...`, handle the "optional" part of
  `T | None` **before** `parse`.

### 0.12.0

- Add `invoke_async` to support async invoke functions and dependencies

## 0.11

### 0.11.6

- Disallow certain combinations of apparently incompatible annotations, i.e.
  sequences and scalars

### 0.11.5

- Fix double dash following an invalid option (with num_args>0)

### 0.11.4

- Fix num_args=-1 on options

### 0.11.3

- Continue to parse docstrings without docstring_parser extra
- Fix rendering issue with markdown in docstrings

### 0.11.2

- Make docstring_parser dependency optional
- Fix parser error if option followed unknown argument

### 0.11.1

- (Hopefully) Configure rich properly to deal with line overflow when printing
  terminal escape codes.

### 0.11.0

- Add option for explicit Output object, and add `error_format` option to allow
  customizing output formatting.

## 0.10

### 0.10.2

- Disallow explicit `required=False` in combination with the lack of a field
  level default.

### 0.10.1

- Fix regression resulting from `value_name`/`field_name` split.

### 0.10.0

- Split Arg `value_name`/`field_name`. `value_name` controls help/error output
  naming. `field_name` controls the the destination field on the dataclass
  object.

## 0.9

### 0.9.3

- Ensure output of missing required options is deterministically ordered
- Output all required options when listing out missing required options
- Fix ignore num_args=0 override

### 0.9.2

- Invoke the specific callable subcommand instance being targeted.

### 0.9.1

- Supply the parsed Command instance as an invoke dependency.

### 0.9.0

- Change default backend to `cappa.parser.backend`. To opt into argparse
  backend, explicitly supply it with `backend=cappa.argparse.backend`.

## 0.8

### 0.8.9

- Avoid mutating command when adding meta arguments
- Avoid setting global NO_COLOR env var when disabling color

### 0.8.8

- Clean up help text output formatting
- Show rich-style help text when using argparse backend

### 0.8.7

- Allow defining custom callable as an `action`.
- Improve behavior consuming concatenated short arguments

### 0.8.6

- Improve behavior consuming concatenated short arguments

### 0.8.5

- Add metadata to package distribution

### 0.8.4

- Loosen dependency version specifiers

### 0.8.3

- Fix `Literal["one", "two"]` syntax vs `Literal["one"] | Literal["two"]`
- Apply custom completions to already "valid" arguments values
- Deduplicate the --completion helptext choices

### 0.8.2

- The command's name should now always translate to the prog name
- Explicitly provided argv should now **not** include the prog name

### 0.8.1

- Correct the version long name when long=True.

### 0.8.0

- Implement support for PEP-727 help text inference.

## 0.7

### 0.7.1

- Provide clear error message when a version Arg is supplied without a name.
- Documentation updates

### 0.7.0

- Adds native cappa parser option vs argparse
- Renames render option to "backend"
- Collapse separate `Subcommands` abstraction into Subcommand
- Renames `Subcmd` to `Subcommands`
- Adds support for autocompletion when using new parser
- Removes "rich" extra

  - Adds rich as a required extra dependency

    - It is core to custom/colored help formatting for new parser, and the now
      more-unified stdout/stderr output.

  - rich-argparse needs to now be installed separately, if used

- Adds a new `Output` implicit dependency option
- Adds new theme option (currently only applied to custom parser)
- Adds group option to `Arg` to control how arguments are grouped together in
  help text
- Adds hidden option to `Arg`, to hide arguments from help text.
- Ensures `help=` applies to all levels of subcommands
