Merge branch 'main' into chore/namespaceRedesignDataPlane

Signed-off-by: Nicolas <nickdb@amazon.com>

Author: nborges-aws

src/bedrock_agentcore/_utils/namespace.py

@@ -1,6 +1,7 @@
-"""Namespace utilities for data plane API calls."""
+"""Namespace utilities for data plane and control plane API calls."""
 
-from typing import Dict, Optional
+import warnings
+from typing import Dict, List, Optional
 
 
 def build_namespace_params(namespace: Optional[str] = None, namespace_path: Optional[str] = None) -> Dict[str, str]:
@@ -26,3 +27,49 @@ def build_namespace_params(namespace: Optional[str] = None, namespace_path: Opti
     if namespace is not None:
         return {"namespace": namespace}
     return {"namespacePath": namespace_path}
+
+
+def resolve_namespace_templates(
+    namespaces: Optional[List[str]] = None,
+    namespace_templates: Optional[List[str]] = None,
+    param_name: str = "namespaces",
+    new_param_name: Optional[str] = None,
+) -> Optional[List[str]]:
+    """Resolve the deprecated ``namespaces`` kwarg and the new ``namespace_templates`` kwarg.
+
+    Used by control-plane strategy methods. Exactly one (or neither) may be provided.
+    If the deprecated form is used, a ``DeprecationWarning`` is emitted. Returns the
+    resolved list, or ``None`` if neither was provided.
+
+    Args:
+        namespaces: The deprecated parameter value, if any.
+        namespace_templates: The new parameter value, if any.
+        param_name: Base name used in error/warning messages for the deprecated form
+            (e.g. "namespaces" or "reflection_namespaces").
+        new_param_name: Name of the replacement form to reference in messages. Defaults
+            to ``param_name`` with ``"namespaces"`` replaced by ``"namespace_templates"``.
+            Override when the replacement identifier doesn't follow that pattern (for
+            example, a dict key like ``reflection_config['namespaceTemplates']``).
+
+    Raises:
+        ValueError: if both arguments are provided.
+    """
+    if new_param_name is None:
+        new_param_name = param_name.replace("namespaces", "namespace_templates")
+
+    if namespaces is not None and namespace_templates is not None:
+        raise ValueError(
+            f"'{param_name}' and '{new_param_name}' are mutually exclusive. "
+            f"Prefer '{new_param_name}' ('{param_name}' is deprecated)."
+        )
+
+    if namespaces is not None:
+        warnings.warn(
+            f"The '{param_name}' parameter is deprecated and will be removed in a future release. "
+            f"Use '{new_param_name}' instead.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        return namespaces
+
+    return namespace_templates