feat: support namespace home_node and update endpoint

The server gained an optional home_node on namespace create plus a new
PUT /namespaces/{name} to modify it, and a read-only state field on the
namespace object. Bring the client to parity:

- Namespace model gains home_node and state (Literal active/deleting)
- create() accepts optional home_node; new update() backed by PUT
- create/get/list/update share a _ns_from_dict parser
- sync/async .pyi stubs updated; NamespaceState exported from outputs
- mock, unit, and integration tests for the new fields and update()

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jfrancoa

integration/test_namespaces.py

@@ -18,6 +18,13 @@ def _skip_if_unsupported(client: weaviate.WeaviateClient) -> None:
         pytest.skip(f"Namespaces require Weaviate {major}.{minor}.{patch}+")
 
 
+def _a_storage_candidate(client: weaviate.WeaviateClient) -> str:
+    """Return a node name usable as a ``home_node`` (must be a real storage candidate)."""
+    nodes = client.cluster.nodes()
+    assert nodes, "expected at least one cluster node"
+    return nodes[0].name
+
+
 def test_create_and_get_namespace(client_factory: ClientFactory) -> None:
     with client_factory(ports=NS_PORTS, auth_credentials=ADMIN_KEY) as client:
         _skip_if_unsupported(client)
@@ -32,6 +39,43 @@ def test_create_and_get_namespace(client_factory: ClientFactory) -> None:
             client.namespaces.delete(name="testns")
 
 
+def test_create_namespace_with_home_node(client_factory: ClientFactory) -> None:
+    with client_factory(ports=NS_PORTS, auth_credentials=ADMIN_KEY) as client:
+        _skip_if_unsupported(client)
+
+        home_node = _a_storage_candidate(client)
+        ns = client.namespaces.create(name="homenodens", home_node=home_node)
+        try:
+            assert ns.name == "homenodens"
+            assert ns.home_node == home_node
+            assert ns.state == "active"
+
+            fetched = client.namespaces.get(name="homenodens")
+            assert fetched is not None
+            assert fetched.home_node == home_node
+        finally:
+            client.namespaces.delete(name="homenodens")
+
+
+def test_update_namespace_home_node(client_factory: ClientFactory) -> None:
+    with client_factory(ports=NS_PORTS, auth_credentials=ADMIN_KEY) as client:
+        _skip_if_unsupported(client)
+
+        home_node = _a_storage_candidate(client)
+        # Create without a home_node so the cluster auto-selects, then pin it explicitly.
+        client.namespaces.create(name="updatens")
+        try:
+            updated = client.namespaces.update(name="updatens", home_node=home_node)
+            assert updated.name == "updatens"
+            assert updated.home_node == home_node
+
+            fetched = client.namespaces.get(name="updatens")
+            assert fetched is not None
+            assert fetched.home_node == home_node
+        finally:
+            client.namespaces.delete(name="updatens")
+
+
 def test_get_nonexistent_namespace_returns_none(client_factory: ClientFactory) -> None:
     with client_factory(ports=NS_PORTS, auth_credentials=ADMIN_KEY) as client:
         _skip_if_unsupported(client)

mock_tests/test_namespaces.py

@@ -100,10 +100,76 @@ def handler(request: Request) -> Response:
 
     assert isinstance(ns, Namespace)
     assert ns.name == "myns"
+    assert ns.home_node is None
+    assert ns.state is None
     assert captured["body"] == {}
     server.check_assertions()
 
 
+def test_namespaces_create_sends_home_node_when_provided(
+    ns_client: Tuple[weaviate.WeaviateClient, HTTPServer],
+) -> None:
+    """When ``home_node`` is provided, ``create`` must carry it in the request body.
+
+    Dropping ``body['home_node'] = home_node`` would silently ignore the caller's
+    placement choice and let the server auto-select instead.
+    """
+    client, server = ns_client
+    captured: Dict[str, Any] = {}
+
+    def handler(request: Request) -> Response:
+        captured["body"] = json.loads(request.get_data(as_text=True) or "{}")
+        return Response(
+            json.dumps({"name": "myns", "home_node": "node1", "state": "active"}),
+            status=201,
+        )
+
+    server.expect_request("/v1/namespaces/myns", method="POST").respond_with_handler(handler)
+
+    ns = client.namespaces.create(name="myns", home_node="node1")
+
+    assert ns.name == "myns"
+    assert ns.home_node == "node1"
+    assert ns.state == "active"
+    assert captured["body"] == {"home_node": "node1"}
+    server.check_assertions()
+
+
+# ---------------------------------------------------------------------------
+# update
+# ---------------------------------------------------------------------------
+
+
+def test_namespaces_update_sends_put_and_parses_response(
+    ns_client: Tuple[weaviate.WeaviateClient, HTTPServer],
+) -> None:
+    """``update`` must PUT ``{"home_node": ...}`` and return the updated namespace.
+
+    The server requires ``home_node`` in the body; sending anything else (or the
+    wrong HTTP verb) would break the modify-placement contract.
+    """
+    client, server = ns_client
+    captured: Dict[str, Any] = {}
+
+    def handler(request: Request) -> Response:
+        captured["body"] = json.loads(request.get_data(as_text=True) or "{}")
+        return Response(
+            json.dumps({"name": "myns", "home_node": "node2", "state": "active"}),
+            status=200,
+        )
+
+    server.expect_request("/v1/namespaces/myns", method="PUT").respond_with_handler(handler)
+
+    ns = client.namespaces.update(name="myns", home_node="node2")
+
+    assert isinstance(ns, Namespace)
+    assert ns.name == "myns"
+    assert ns.home_node == "node2"
+    assert ns.state == "active"
+    assert captured["body"] == {"home_node": "node2"}
+    server.check_assertions()
+
+
 # ---------------------------------------------------------------------------
 # get
 # ---------------------------------------------------------------------------
@@ -121,6 +187,30 @@ def test_namespaces_get_returns_namespace_when_found(
 
     assert ns is not None
     assert ns.name == "customer1"
+    assert ns.home_node is None
+    assert ns.state is None
+    server.check_assertions()
+
+
+def test_namespaces_get_parses_home_node_and_state(
+    ns_client: Tuple[weaviate.WeaviateClient, HTTPServer],
+) -> None:
+    """``get`` must surface the ``home_node`` and ``state`` fields from the response.
+
+    These fields were added to the server's namespace object after the client's
+    initial implementation; this guards against the parser silently ignoring them.
+    """
+    client, server = ns_client
+    server.expect_request("/v1/namespaces/customer1", method="GET").respond_with_json(
+        {"name": "customer1", "home_node": "node1", "state": "deleting"}, status=200
+    )
+
+    ns = client.namespaces.get(name="customer1")
+
+    assert ns is not None
+    assert ns.name == "customer1"
+    assert ns.home_node == "node1"
+    assert ns.state == "deleting"
     server.check_assertions()
 
 
@@ -161,6 +251,28 @@ def test_namespaces_list_all_parses_array(
     server.check_assertions()
 
 
+def test_namespaces_list_all_parses_home_node_and_state(
+    ns_client: Tuple[weaviate.WeaviateClient, HTTPServer],
+) -> None:
+    """``list_all`` must surface ``home_node`` and ``state`` for each namespace."""
+    client, server = ns_client
+    server.expect_request("/v1/namespaces", method="GET").respond_with_json(
+        [
+            {"name": "ns1", "home_node": "node1", "state": "active"},
+            {"name": "ns2"},
+        ],
+        status=200,
+    )
+
+    namespaces = client.namespaces.list_all()
+
+    assert namespaces[0].home_node == "node1"
+    assert namespaces[0].state == "active"
+    assert namespaces[1].home_node is None
+    assert namespaces[1].state is None
+    server.check_assertions()
+
+
 def test_namespaces_list_all_handles_null_response(
     ns_client: Tuple[weaviate.WeaviateClient, HTTPServer],
 ) -> None:
@@ -216,11 +328,12 @@ def test_namespaces_delete_accepts_202(
     "method_call",
     [
         lambda c: c.namespaces.create(name="x"),
+        lambda c: c.namespaces.update(name="x", home_node="n"),
         lambda c: c.namespaces.get(name="x"),
         lambda c: c.namespaces.list_all(),
         lambda c: c.namespaces.delete(name="x"),
     ],
-    ids=["create", "get", "list_all", "delete"],
+    ids=["create", "update", "get", "list_all", "delete"],
 )
 def test_namespaces_methods_require_1_38(
     ns_client_old: weaviate.WeaviateClient,

test/test_namespaces.py

@@ -1,4 +1,5 @@
 from weaviate.classes.rbac import Actions, Permissions
+from weaviate.namespaces.models import Namespace
 from weaviate.rbac.models import (
     NamespacesAction,
     NamespacesPermissionOutput,
@@ -106,6 +107,23 @@ def test_actions_namespaces_enum_accessible() -> None:
     assert Actions.Namespaces.MANAGE.value == "manage_namespaces"
 
 
+# --- Namespace model ---
+
+
+def test_namespace_optional_fields_default_to_none() -> None:
+    ns = Namespace(name="customer1")
+    assert ns.name == "customer1"
+    assert ns.home_node is None
+    assert ns.state is None
+
+
+def test_namespace_all_fields_set() -> None:
+    ns = Namespace(name="customer1", home_node="node1", state="active")
+    assert ns.name == "customer1"
+    assert ns.home_node == "node1"
+    assert ns.state == "active"
+
+
 # --- UserDB.namespace field ---
 
 

weaviate/namespaces/async_.pyi

@@ -5,7 +5,8 @@ from weaviate.namespaces.base import _NamespacesExecutor
 from weaviate.namespaces.models import Namespace
 
 class _NamespacesAsync(_NamespacesExecutor[ConnectionAsync]):
-    async def create(self, *, name: str) -> Namespace: ...
+    async def create(self, *, name: str, home_node: Optional[str] = None) -> Namespace: ...
+    async def update(self, *, name: str, home_node: str) -> Namespace: ...
     async def get(self, *, name: str) -> Optional[Namespace]: ...
     async def list_all(self) -> List[Namespace]: ...
     async def delete(self, *, name: str) -> None: ...

weaviate/namespaces/base.py

@@ -1,22 +1,32 @@
-from typing import Generic, List, Optional
+from typing import Any, Dict, Generic, List, Optional, cast
 
 from httpx import Response
 
 from weaviate.connect import executor
 from weaviate.connect.v4 import ConnectionType, _ExpectedStatusCodes
-from weaviate.namespaces.models import Namespace
+from weaviate.namespaces.models import Namespace, NamespaceState
 from weaviate.util import _decode_json_response_dict, _decode_json_response_list
 
 
 class _NamespacesExecutor(Generic[ConnectionType]):
     def __init__(self, connection: ConnectionType):
         self._connection = connection
 
-    def create(self, *, name: str) -> executor.Result[Namespace]:
+    @staticmethod
+    def _ns_from_dict(data: Dict[str, Any]) -> Namespace:
+        return Namespace(
+            name=data["name"],
+            home_node=data.get("home_node"),
+            state=cast(Optional[NamespaceState], data.get("state")),
+        )
+
+    def create(self, *, name: str, home_node: Optional[str] = None) -> executor.Result[Namespace]:
         """Create a new namespace.
 
         Args:
             name: The namespace name. Must be 3-36 lowercase alphanumeric characters starting with a letter.
+            home_node: The cluster node to place this namespace's shards on. Must be a current storage
+                candidate. When omitted, the cluster picks one automatically.
 
         Returns:
             The created Namespace.
@@ -26,17 +36,50 @@ def create(self, *, name: str) -> executor.Result[Namespace]:
         def resp(res: Response) -> Namespace:
             parsed = _decode_json_response_dict(res, "Create namespace")
             assert parsed is not None
-            return Namespace(name=parsed["name"])
+            return self._ns_from_dict(parsed)
+
+        body: Dict[str, Any] = {}
+        if home_node is not None:
+            body["home_node"] = home_node
 
         return executor.execute(
             response_callback=resp,
             method=self._connection.post,
             path=f"/namespaces/{name}",
-            weaviate_object={},
+            weaviate_object=body,
             error_msg=f"Could not create namespace '{name}'",
             status_codes=_ExpectedStatusCodes(ok_in=[201], error="Create namespace"),
         )
 
+    def update(self, *, name: str, home_node: str) -> executor.Result[Namespace]:
+        """Update the home node of an existing namespace.
+
+        Changing the home node only affects future placement decisions; existing live shards
+        are not moved.
+
+        Args:
+            name: The name of the namespace to update.
+            home_node: The cluster node to use for future placements. Must be a current storage candidate.
+
+        Returns:
+            The updated Namespace.
+        """
+        self._connection._weaviate_version.check_is_at_least_1_38_0("namespaces")
+
+        def resp(res: Response) -> Namespace:
+            parsed = _decode_json_response_dict(res, "Update namespace")
+            assert parsed is not None
+            return self._ns_from_dict(parsed)
+
+        return executor.execute(
+            response_callback=resp,
+            method=self._connection.put,
+            path=f"/namespaces/{name}",
+            weaviate_object={"home_node": home_node},
+            error_msg=f"Could not update namespace '{name}'",
+            status_codes=_ExpectedStatusCodes(ok_in=[200], error="Update namespace"),
+        )
+
     def get(self, *, name: str) -> executor.Result[Optional[Namespace]]:
         """Get a namespace by name.
 
@@ -53,7 +96,7 @@ def resp(res: Response) -> Optional[Namespace]:
                 return None
             parsed = _decode_json_response_dict(res, "Get namespace")
             assert parsed is not None
-            return Namespace(name=parsed["name"])
+            return self._ns_from_dict(parsed)
 
         return executor.execute(
             response_callback=resp,
@@ -73,7 +116,7 @@ def list_all(self) -> executor.Result[List[Namespace]]:
 
         def resp(res: Response) -> List[Namespace]:
             parsed = _decode_json_response_list(res, "List namespaces")
-            return [Namespace(name=ns["name"]) for ns in (parsed or [])]
+            return [self._ns_from_dict(ns) for ns in (parsed or [])]
 
         return executor.execute(
             response_callback=resp,

weaviate/namespaces/models.py

@@ -1,6 +1,11 @@
 from dataclasses import dataclass
+from typing import Literal, Optional
+
+NamespaceState = Literal["active", "deleting"]
 
 
 @dataclass
 class Namespace:
     name: str
+    home_node: Optional[str] = None
+    state: Optional[NamespaceState] = None

weaviate/namespaces/sync.pyi

@@ -5,7 +5,8 @@ from weaviate.namespaces.base import _NamespacesExecutor
 from weaviate.namespaces.models import Namespace
 
 class _Namespaces(_NamespacesExecutor[ConnectionSync]):
-    def create(self, *, name: str) -> Namespace: ...
+    def create(self, *, name: str, home_node: Optional[str] = None) -> Namespace: ...
+    def update(self, *, name: str, home_node: str) -> Namespace: ...
     def get(self, *, name: str) -> Optional[Namespace]: ...
     def list_all(self) -> List[Namespace]: ...
     def delete(self, *, name: str) -> None: ...

weaviate/outputs/namespaces.py

@@ -1,3 +1,3 @@
-from weaviate.namespaces.models import Namespace
+from weaviate.namespaces.models import Namespace, NamespaceState
 
-__all__ = ["Namespace"]
+__all__ = ["Namespace", "NamespaceState"]