---------------------------
Backwards incompatible changes:
- A new policy for mapping function arguments to CLI arguments is used by
default (see :class:`argh.assembling.NameMappingPolicy`).
The following function does **not** map to ``func foo [--bar]`` anymore::
def func(foo, bar=None):
...
Since this release it maps to ``func foo [bar]`` instead.
Please update the function this way to keep `bar` an "option"::
def func(foo, *, bar=None):
...
If you cannot modify the function signature to use kwonly args for options,
please consider explicitly specifying the legacy name mapping policy::
set_default_command(
func, name_mapping_policy=NameMappingPolicy.BY_NAME_IF_HAS_DEFAULT
)
- The name mapping policy `BY_NAME_IF_HAS_DEFAULT` slightly deviates from the
old behaviour. Kwonly arguments without default values used to be marked as
required options (``--foo FOO``), now they are treated as positionals
(``foo``). Please consider the new default policy (`BY_NAME_IF_KWONLY`) for
a better treatment of kwonly.
- Removed previously deprecated features (184 → 188):
- argument help string in annotations — reserved for type hints;
- `argh.SUPPORTS_ALIASES`;
- `argh.safe_input()`;
- previously renamed arguments for `add_commands()`: `namespace`,
`namespace_kwargs`, `title`, `description`, `help`;
- `pre_call` argument in `dispatch()`. The basic usage remains simple but
more granular functions are now available for more control.
Instead of this::
argh.dispatch(..., pre_call=pre_call_hook)
please use this::
func, ns = argh.parse_and_resolve(...)
pre_call_hook(ns)
argh.run_endpoint_function(func, ns, ...)
Deprecated:
- The `expects_obj` decorator. Rationale: it used to support the old,
"un-pythonic" style of usage, which essentially lies outside the scope of
Argh. If you are not using the mapping of function arguments onto CLI, then
you aren't reducing the amount of code compared to vanilla Argparse.
- The `add_help_command` argument in `dispatch()`.
Rationale: it doesn't add much to user experience; it's not much harder to
type ``--help`` than it is to type ``help``; moreover, the option can be
added anywhere, unlike its positional counterpart.
Enhancements:
- Added support for Python 3.12.
- Added type annotations to existing Argh code (185 → 189).
- The `dispatch()` function has been refactored, so in case you need finer
control over the process, two new, more granular functions can be used:
- `endpoint_function, namespace = argh.parse_and_resolve(...)`
- `argh.run_endpoint_function(endpoint_function, namespace, ...)`
Please note that the names may change in the upcoming versions.
- Configurable name mapping policy has been introduced for function argument
to CLI argument translation (191 → 199):
- `BY_NAME_IF_KWONLY` (default and recommended).
- `BY_NAME_IF_HAS_DEFAULT` (close to pre-v.0.30 behaviour);
Please check API docs on :class:`argh.assembling.NameMappingPolicy` for
details.