From 9392ddd11fa530a30ed55f0cdfb95707adef5517 Mon Sep 17 00:00:00 2001 From: Andy Mikhaylenko Date: Sat, 21 Oct 2023 22:55:54 +0200 Subject: [PATCH] docs: polish --- CHANGES.rst | 42 ++++++++++++++++++++++++++--------------- README.rst | 2 +- src/argh/assembling.py | 35 +++++++++++++++++++++------------- src/argh/decorators.py | 3 +++ src/argh/dispatching.py | 2 +- src/argh/interaction.py | 2 +- 6 files changed, 55 insertions(+), 31 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index e38172e..654cc5e 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -7,6 +7,33 @@ Version 0.30.0 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; @@ -27,21 +54,6 @@ Backwards incompatible changes: pre_call_hook(ns) argh.run_endpoint_function(func, ns, ...) - - A new policy for mapping function arguments to CLI arguments is used by - default (see :class:`argh.assembling.NameMappingPolicy`). - In case you need to retain the CLI mapping but cannot modify the function - signature to use kwonly args for options, consider using this:: - - 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. - Deprecated: - The `@expects_obj` decorator. Rationale: it used to support the old, diff --git a/README.rst b/README.rst index 7f6ff38..3c8ed04 100644 --- a/README.rst +++ b/README.rst @@ -145,7 +145,7 @@ A potentially modular application with more control over the process: "Returns given word as is." return text - def greet(name: str, greeting: str = "Hello") -> str: + def greet(name: str, *, greeting: str = "Hello") -> str: "Greets the user with given name. The greeting is customizable." return f"{greeting}, {name}!" diff --git a/src/argh/assembling.py b/src/argh/assembling.py index 737b958..d57d48e 100644 --- a/src/argh/assembling.py +++ b/src/argh/assembling.py @@ -67,8 +67,8 @@ def func(alpha, beta=1, *, gamma, delta=2): ... prog alpha [beta] --gamma [--delta DELTA] - That is, `alpha` and `--gamma` are mandatory while `beta` and `--delta` - are optional (they have default values). + That is, ``alpha`` and ``--gamma`` are mandatory while ``beta`` and + ``--delta`` are optional (they have default values). * `BY_NAME_IF_HAS_DEFAULT` is very close to the the legacy approach (pre-v0.30). If a function argument has a default value, it becomes an @@ -83,9 +83,10 @@ def func(alpha, beta=1, *, gamma, delta=2): ... prog [--beta BETA] [--delta DELTA] alpha gamma - That is, `alpha` and `gamma` are mandatory and positional, while `--beta` - and `--delta` are optional (they have default values). Note that it's - impossible to have an optional positional or a mandatory named argument. + That is, ``alpha`` and ``gamma`` are mandatory and positional, while + ``--beta`` and ``--delta`` are optional (they have default values). Note + that it's impossible to have an optional positional or a mandatory named + argument. The difference between this policy and the behaviour of Argh before v0.30 is in the treatment of kwonly arguments without default values: @@ -583,15 +584,23 @@ def add_subcommands( These examples are equivalent:: - add_commands(parser, [get, put], group_name="db", - group_kwargs={ - "title": "database commands", - "help": "CRUD for our silly database" - }) + add_commands( + parser, + [get, put], + group_name="db", + group_kwargs={ + "title": "database commands", + "help": "CRUD for our silly database" + } + ) - add_subcommands(parser, "db", [get, put], - title="database commands", - help="CRUD for our database") + add_subcommands( + parser, + "db", + [get, put], + title="database commands", + help="CRUD for our database" + ) """ add_commands(parser, functions, group_name=group_name, group_kwargs=group_kwargs) diff --git a/src/argh/decorators.py b/src/argh/decorators.py index 6c0d845..aad081b 100644 --- a/src/argh/decorators.py +++ b/src/argh/decorators.py @@ -131,6 +131,9 @@ def load( to tune the argument's behaviour or presentation using ordinary function signatures. Readability counts, don't repeat yourself. + The decorator is likely to be deprecated in the upcoming versions + of Argh in favour of typing hints; see :doc:`the_story`. + """ def wrapper(func: Callable) -> Callable: diff --git a/src/argh/dispatching.py b/src/argh/dispatching.py index d3e0a60..fb4b085 100644 --- a/src/argh/dispatching.py +++ b/src/argh/dispatching.py @@ -438,7 +438,7 @@ class EntryPoint: from argh import EntryPoint - app = EntryPoint("main", dict(description="This is a cool app")) + app = EntryPoint("main", {"description": "This is a cool app"}) @app def ls() -> None: diff --git a/src/argh/interaction.py b/src/argh/interaction.py index c9df8ee..ab8f0e3 100644 --- a/src/argh/interaction.py +++ b/src/argh/interaction.py @@ -45,7 +45,7 @@ def confirm( Usage:: - def delete(key, silent=False): + def delete(key, *, silent=False): item = db.get(Item, args.key) if confirm(f"Delete {item.title}", default=True, skip=silent): item.delete()