Deprecate CommandManager namespace argument

Change-Id: I436944774d7cefc196f7bbdabc6319c9783fe2f2
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>

cliff/commandmanager.py

@@ -16,6 +16,7 @@ import collections.abc
 import importlib.metadata
 import logging
 from typing import TypeAlias
+import warnings
 
 import stevedore
 
@@ -67,8 +68,10 @@ EntryPointT: TypeAlias = EntryPointWrapper | importlib.metadata.EntryPoint
 class CommandManager:
     """Discovers commands and handles lookup based on argv data.
 
-    :param namespace: String containing the entrypoint namespace for the
-        plugins to be loaded. For example, ``'cliff.formatter.list'``.
+    :param namespace: **DEPRECATED** String containing the entrypoint namespace
+        for the plugins to be loaded from by default. For example,
+        ``'cliff.formatter.list'``. :meth:`CommandManager.load_commands` should
+        be preferred.
     :param convert_underscores: Whether cliff should convert underscores to
         spaces in entry_point commands.
     :param ignored_modules: A list of module names to ignore when loading
@@ -77,11 +80,21 @@ class CommandManager:
 
     def __init__(
         self,
-        namespace: str | None,
+        namespace: str | None = None,
         convert_underscores: bool = True,
         *,
         ignored_modules: collections.abc.Iterable[str] | None = None,
     ) -> None:
+        if namespace:
+            # TODO(stephenfin): Remove this functionality in 5.0.0 and make
+            # convert_underscores a kwarg-only argument
+            warnings.warn(
+                f'Initialising {self.__class__!r} with a namespace is '
+                f'deprecated for removal. Prefer loading commands from a '
+                f'given namespace with load_commands instead',
+                DeprecationWarning,
+            )
+
         self.namespace = namespace
         self.convert_underscores = convert_underscores
         self.ignored_modules = ignored_modules or ()
@@ -93,6 +106,8 @@ class CommandManager:
 
     def _load_commands(self) -> None:
         # NOTE(jamielennox): kept for compatibility.
+        # TODO(stephenfin): We can remove this when we remove the 'namespace'
+        # argument
         if self.namespace:
             self.load_commands(self.namespace)
 

releasenotes/notes/deprecate-commandmanager-namespace-argument-2d5169222402f633.yaml

@@ -0,0 +1,13 @@
+---
+deprecations:
+  - |
+    The ``namespace`` argument to ``cliff.commandmanager.CommandManager`` has
+    been deprecated for removal. Users should prefer invoking ``load_commands``
+    instead. For example, instead of::
+
+        cm = commandmanager.CommandManager('foo')
+
+    Do::
+
+        cm = commandmanager.CommandManager()
+        cm.load_plugins('foo')