Expose namespace controls in Python SDK

Author: durable-workflow-ops

src/durable_workflow/__init__.py

@@ -19,6 +19,8 @@
 from .client import (
     BridgeAdapterOutcome,
     Client,
+    NamespaceDescription,
+    NamespaceList,
     ScheduleAction,
     ScheduleBackfillResult,
     ScheduleDescription,
@@ -147,6 +149,8 @@
     "ChildWorkflowFailed",
     "Client",
     "ContinueAsNew",
+    "NamespaceDescription",
+    "NamespaceList",
     "AUTH_COMPOSITION_CONTRACT_SCHEMA",
     "AUTH_COMPOSITION_CONTRACT_VERSION",
     "AUTH_COMPOSITION_REQUIRED_EFFECTIVE_CONFIG_FIELDS",

src/durable_workflow/client.py

@@ -70,7 +70,7 @@ def _route_for_metrics(path: str) -> str:
             parts[3] = "{run_id}"
     elif parts[0] == "schedules" and len(parts) >= 2:
         parts[1] = "{schedule_id}"
-    elif parts[0] == "search-attributes" and len(parts) >= 2:
+    elif parts[0] in {"namespaces", "search-attributes"} and len(parts) >= 2:
         parts[1] = "{name}"
     elif parts[0] == "workers" and len(parts) >= 2:
         parts[1] = "{worker_id}"
@@ -109,6 +109,36 @@ class WorkflowList:
     next_page_token: str | None = None
 
 
+@dataclass
+class NamespaceDescription:
+    """Server configuration for one workflow namespace."""
+
+    name: str
+    description: str | None = None
+    retention_days: int | None = None
+    status: str | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> NamespaceDescription:
+        return cls(
+            name=str(data.get("name", "")),
+            description=data.get("description"),
+            retention_days=data.get("retention_days"),
+            status=data.get("status"),
+            created_at=data.get("created_at"),
+            updated_at=data.get("updated_at"),
+        )
+
+
+@dataclass
+class NamespaceList:
+    """Namespaces visible to the current control-plane identity."""
+
+    namespaces: list[NamespaceDescription]
+
+
 @dataclass
 class WorkflowRun:
     """Current server view of one durable run in a workflow execution chain."""
@@ -1040,6 +1070,93 @@ async def health(self) -> dict[str, Any]:
             )
         return result
 
+    # ── Namespaces ────────────────────────────────────────────────────
+    async def list_namespaces(self) -> NamespaceList:
+        """List namespaces visible to the current control-plane identity."""
+        data = await self._request("GET", "/namespaces")
+        if not isinstance(data, dict):
+            raise ServerError(
+                200,
+                {
+                    "reason": "invalid_namespace_response",
+                    "message": f"expected JSON object, got {type(data).__name__}",
+                },
+            )
+        items = data.get("namespaces", [])
+        return NamespaceList(
+            namespaces=[
+                NamespaceDescription.from_dict(item)
+                for item in items
+                if isinstance(item, dict)
+            ],
+        )
+
+    async def describe_namespace(self, name: str) -> NamespaceDescription:
+        """Return configuration and status for one namespace."""
+        data = await self._request("GET", f"/namespaces/{quote(name, safe='')}", context=name)
+        if not isinstance(data, dict):
+            raise ServerError(
+                200,
+                {
+                    "reason": "invalid_namespace_response",
+                    "message": f"expected JSON object, got {type(data).__name__}",
+                },
+            )
+        return NamespaceDescription.from_dict(data)
+
+    async def create_namespace(
+        self,
+        name: str,
+        *,
+        description: str | None = None,
+        retention_days: int = 30,
+    ) -> NamespaceDescription:
+        """Create a workflow namespace and return the server representation."""
+        data = await self._request(
+            "POST",
+            "/namespaces",
+            json={
+                "name": name,
+                "description": description,
+                "retention_days": retention_days,
+            },
+            context=name,
+        )
+        if not isinstance(data, dict):
+            raise ServerError(
+                200,
+                {
+                    "reason": "invalid_namespace_response",
+                    "message": f"expected JSON object, got {type(data).__name__}",
+                },
+            )
+        return NamespaceDescription.from_dict(data)
+
+    async def update_namespace(
+        self,
+        name: str,
+        *,
+        description: str | None = None,
+        retention_days: int | None = None,
+    ) -> NamespaceDescription:
+        """Update namespace metadata. Only provided fields are sent."""
+        body: dict[str, Any] = {}
+        if description is not None:
+            body["description"] = description
+        if retention_days is not None:
+            body["retention_days"] = retention_days
+
+        data = await self._request("PUT", f"/namespaces/{quote(name, safe='')}", json=body, context=name)
+        if not isinstance(data, dict):
+            raise ServerError(
+                200,
+                {
+                    "reason": "invalid_namespace_response",
+                    "message": f"expected JSON object, got {type(data).__name__}",
+                },
+            )
+        return NamespaceDescription.from_dict(data)
+
     # ── Task queues ────────────────────────────────────────────────────
     async def list_task_queues(self) -> TaskQueueList:
         """List task queues with server-side admission status.

src/durable_workflow/sync.py

@@ -7,6 +7,8 @@
 
 from .client import Client as AsyncClient
 from .client import (
+    NamespaceDescription,
+    NamespaceList,
     ScheduleAction,
     ScheduleBackfillResult,
     ScheduleDescription,
@@ -281,6 +283,46 @@ def describe_task_queue(self, name: str) -> TaskQueueDescription:
         result: TaskQueueDescription = _run(self._async.describe_task_queue(name))
         return result
 
+    def list_namespaces(self) -> NamespaceList:
+        result: NamespaceList = _run(self._async.list_namespaces())
+        return result
+
+    def describe_namespace(self, name: str) -> NamespaceDescription:
+        result: NamespaceDescription = _run(self._async.describe_namespace(name))
+        return result
+
+    def create_namespace(
+        self,
+        name: str,
+        *,
+        description: str | None = None,
+        retention_days: int = 30,
+    ) -> NamespaceDescription:
+        result: NamespaceDescription = _run(
+            self._async.create_namespace(
+                name,
+                description=description,
+                retention_days=retention_days,
+            )
+        )
+        return result
+
+    def update_namespace(
+        self,
+        name: str,
+        *,
+        description: str | None = None,
+        retention_days: int | None = None,
+    ) -> NamespaceDescription:
+        result: NamespaceDescription = _run(
+            self._async.update_namespace(
+                name,
+                description=description,
+                retention_days=retention_days,
+            )
+        )
+        return result
+
     def get_history(self, workflow_id: str, run_id: str) -> Any:
         return _run(self._async.get_history(workflow_id, run_id))
 

tests/fixtures/control-plane/namespace-create-parity.json

@@ -0,0 +1,42 @@
+{
+  "schema": "durable-workflow.polyglot.control-plane-request-fixture",
+  "operation": "namespace.create",
+  "request": {
+    "method": "POST",
+    "path": "/namespaces",
+    "body": {
+      "name": "billing",
+      "description": "Billing workflows",
+      "retention_days": 90
+    }
+  },
+  "cli": {
+    "argv": {
+      "name": "billing",
+      "--description": "Billing workflows",
+      "--retention": "90",
+      "--json": true
+    }
+  },
+  "sdk_python": {
+    "args": {
+      "name": "billing",
+      "description": "Billing workflows",
+      "retention_days": 90
+    }
+  },
+  "response_body": {
+    "name": "billing",
+    "description": "Billing workflows",
+    "retention_days": 90,
+    "status": "active",
+    "created_at": "2026-04-02T00:00:00Z",
+    "updated_at": "2026-04-02T00:00:00Z"
+  },
+  "semantic_body": {
+    "name": "billing",
+    "description": "Billing workflows",
+    "retention_days": 90,
+    "status": "active"
+  }
+}

tests/fixtures/control-plane/namespace-describe-parity.json

@@ -0,0 +1,33 @@
+{
+  "schema": "durable-workflow.polyglot.control-plane-request-fixture",
+  "operation": "namespace.describe",
+  "request": {
+    "method": "GET",
+    "path": "/namespaces/billing"
+  },
+  "cli": {
+    "argv": {
+      "name": "billing",
+      "--json": true
+    }
+  },
+  "sdk_python": {
+    "args": {
+      "name": "billing"
+    }
+  },
+  "response_body": {
+    "name": "billing",
+    "description": "Billing workflows",
+    "retention_days": 90,
+    "status": "active",
+    "created_at": "2026-04-02T00:00:00Z",
+    "updated_at": "2026-04-16T12:00:00Z"
+  },
+  "semantic_body": {
+    "name": "billing",
+    "description": "Billing workflows",
+    "retention_days": 90,
+    "status": "active"
+  }
+}

tests/fixtures/control-plane/namespace-list-parity.json

@@ -0,0 +1,47 @@
+{
+  "schema": "durable-workflow.polyglot.control-plane-request-fixture",
+  "operation": "namespace.list",
+  "request": {
+    "method": "GET",
+    "path": "/namespaces"
+  },
+  "cli": {
+    "argv": {
+      "--json": true
+    }
+  },
+  "sdk_python": {
+    "args": {}
+  },
+  "response_body": {
+    "namespaces": [
+      {
+        "name": "default",
+        "description": "Default namespace",
+        "retention_days": 30,
+        "status": "active",
+        "created_at": "2026-04-01T00:00:00Z",
+        "updated_at": "2026-04-15T12:00:00Z"
+      },
+      {
+        "name": "billing",
+        "description": "Billing workflows",
+        "retention_days": 90,
+        "status": "active",
+        "created_at": "2026-04-02T00:00:00Z",
+        "updated_at": "2026-04-16T12:00:00Z"
+      }
+    ]
+  },
+  "semantic_body": {
+    "namespace_names": ["default", "billing"],
+    "retention_days": {
+      "default": 30,
+      "billing": 90
+    },
+    "statuses": {
+      "default": "active",
+      "billing": "active"
+    }
+  }
+}

tests/fixtures/control-plane/namespace-update-parity.json

@@ -0,0 +1,41 @@
+{
+  "schema": "durable-workflow.polyglot.control-plane-request-fixture",
+  "operation": "namespace.update",
+  "request": {
+    "method": "PUT",
+    "path": "/namespaces/billing",
+    "body": {
+      "description": "Billing workflows and reports",
+      "retention_days": 120
+    }
+  },
+  "cli": {
+    "argv": {
+      "name": "billing",
+      "--description": "Billing workflows and reports",
+      "--retention": "120",
+      "--json": true
+    }
+  },
+  "sdk_python": {
+    "args": {
+      "name": "billing",
+      "description": "Billing workflows and reports",
+      "retention_days": 120
+    }
+  },
+  "response_body": {
+    "name": "billing",
+    "description": "Billing workflows and reports",
+    "retention_days": 120,
+    "status": "active",
+    "created_at": "2026-04-02T00:00:00Z",
+    "updated_at": "2026-04-17T12:00:00Z"
+  },
+  "semantic_body": {
+    "name": "billing",
+    "description": "Billing workflows and reports",
+    "retention_days": 120,
+    "status": "active"
+  }
+}