docs: polish

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,

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}!"
 

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)

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:

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:

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()