chore: deprecate dispatch(..., namespace=N)

The argument `namespace` is deprecated for the following public
functions:

- `dispatch()`
- `parse_and_resolve()`

CHANGES.rst

@@ -9,6 +9,14 @@ Enhancements:
 
 - Added `always_flush` argument to `dispatch()` (issue #145)
 
+Deprecated:
+
+- the `namespace` argument in `argh.dispatch()` and `argh.parse_and_resolve()`.
+  Rationale: continued API cleanup.  It's already possible to mutate the
+  namespace object between parsing and calling the endpoint; it's unlikely that
+  anyone would need to specify a custom namespace class or pre-populate it
+  before parsing.  Please file an issue if you have a valid use case.
+
 Version 0.30.5 (2023-12-25)
 ---------------------------
 

src/argh/dispatching.py

@@ -143,6 +143,10 @@ def dispatch(
         that support for combined default and nested functions may be broken
         if a different type of object is forced.
 
+        .. deprecated:: 0.31
+
+          This argument will be removed soon after v0.31.
+
     :param always_flush:
 
         If the output stream is not a terminal (i.e. redirected to a file or
@@ -211,6 +215,12 @@ def parse_and_resolve(
     .. versionadded:: 0.30
 
     Parses CLI arguments and resolves the endpoint function.
+
+    :param namespace:
+
+        .. deprecated:: 0.31
+
+          This argument will be removed soon after v0.31.
     """
     if completion:
         autocomplete(parser)