feat(grpc): add GrpcIndex.describe_namespace (LSB-0050)

## Purpose

Legacy callers using `GRPCIndex.describe_namespace` raised `AttributeError`
because the new `GrpcIndex` did not expose the method. This wires the existing
Rust `GrpcChannel.describe_namespace` RPC through to the Python surface.

## Solution

- Added `describe_namespace(namespace, *, timeout_s)` to `GrpcChannelProtocol`
  in `_protocol.py` so mypy can verify all call sites.
- Added `GrpcIndex.describe_namespace(*, name, timeout, **kwargs)` reproducing
  the same validation logic as `Index.describe_namespace`: accepts the legacy
  `namespace=` kwarg for backcompat, raises `ValidationError` when both or
  neither name arguments are provided, and raises on empty/whitespace names.
- Parses the dict returned by the Rust channel (name, record_count, optional
  schema, optional indexed_fields) into a `NamespaceDescription` struct.
- Added 6 unit tests covering the success path, legacy kwarg alias, both-kwargs
  error, empty-name error, schema+indexed_fields deserialization, and timeout
  forwarding.

## Usage

```python
idx = GrpcIndex(host="...", api_key="...")
ns = idx.describe_namespace(name="movies-en")
print(ns.name, ns.record_count)
```

Author: jhamon

pinecone/grpc/__init__.py

@@ -26,6 +26,12 @@
 )
 from pinecone.grpc._protocol import GrpcChannelProtocol
 from pinecone.grpc.future import PineconeFuture
+from pinecone.models.namespaces.models import (
+    IndexedFields,
+    NamespaceDescription,
+    NamespaceFieldConfig,
+    NamespaceSchema,
+)
 from pinecone.models.vectors.responses import (
     DescribeIndexStatsResponse,
     FetchResponse,
@@ -1316,6 +1322,65 @@ def search_records(
             timeout=timeout,
         )
 
+    def describe_namespace(
+        self,
+        *,
+        name: str | None = None,
+        timeout: float | None = None,
+        **kwargs: str,
+    ) -> NamespaceDescription:
+        """Describe a namespace by name.
+
+        Args:
+            name (str): Name of the namespace to describe.
+            timeout (float | None): Per-call timeout in seconds.
+
+        Returns:
+            :class:`NamespaceDescription` with the namespace name, record count,
+            and schema information.
+
+        Raises:
+            :exc:`ValidationError`: If the name is not a string or is empty/whitespace.
+            :exc:`TypeError`: If unexpected keyword arguments are passed.
+        """
+        legacy_namespace: str | None = kwargs.pop("namespace", None)
+        if kwargs:
+            raise TypeError(
+                f"describe_namespace() got unexpected keyword arguments: {sorted(kwargs)!r}"
+            )
+        if name is not None and legacy_namespace is not None:
+            raise ValidationError("Provide either name= or namespace=, not both")
+        effective: str = name if name is not None else (legacy_namespace or "")
+        if not isinstance(effective, str):
+            raise ValidationError("namespace name must be a string")
+        if not effective or not effective.strip():
+            raise ValidationError("namespace name must be a non-empty string")
+
+        logger.info("Describing namespace %r via gRPC", effective)
+        result = self._channel.describe_namespace(effective, timeout_s=timeout)
+
+        schema: NamespaceSchema | None = None
+        raw_schema = result.get("schema")
+        if raw_schema is not None:
+            schema = NamespaceSchema(
+                fields={
+                    k: NamespaceFieldConfig(filterable=v["filterable"])
+                    for k, v in raw_schema.get("fields", {}).items()
+                }
+            )
+
+        indexed_fields: IndexedFields | None = None
+        raw_indexed = result.get("indexed_fields")
+        if raw_indexed is not None:
+            indexed_fields = IndexedFields(fields=list(raw_indexed))
+
+        return NamespaceDescription(
+            name=result.get("name", ""),
+            record_count=result.get("record_count", 0),
+            schema=schema,
+            indexed_fields=indexed_fields,
+        )
+
     def close(self) -> None:
         """Close the underlying gRPC channel, REST client, and release resources."""
         self._executor.shutdown(wait=True)

pinecone/grpc/_protocol.py

@@ -101,6 +101,15 @@ def describe_index_stats(
         """Describe index statistics."""
         ...
 
+    def describe_namespace(
+        self,
+        namespace: str,
+        *,
+        timeout_s: float | None = None,
+    ) -> dict[str, Any]:
+        """Describe a namespace."""
+        ...
+
     def close(self) -> None:
         """Close the channel and release resources."""
         ...

tests/unit/grpc/test_grpc_index.py

@@ -1,11 +1,14 @@
-"""Unit tests for the GRPCIndex capitalisation alias (BCG-141)."""
+"""Unit tests for the GRPCIndex capitalisation alias (BCG-141) and GrpcIndex.describe_namespace."""
 
 from __future__ import annotations
 
 from unittest.mock import MagicMock, patch
 
+import pytest
+
 import pinecone.grpc
 from pinecone.grpc import GRPCIndex, GrpcIndex
+from pinecone.models.namespaces.models import NamespaceDescription
 
 _MOCK_GRPC_MODULE_PATH = "pinecone._grpc"
 
@@ -20,6 +23,16 @@ def _make_grpc_index_via_alias(mock_channel: MagicMock) -> GRPCIndex:
         )
 
 
+def _make_grpc_index(mock_channel: MagicMock) -> GrpcIndex:
+    mock_module = MagicMock()
+    mock_module.GrpcChannel.return_value = mock_channel
+    with patch.dict("sys.modules", {_MOCK_GRPC_MODULE_PATH: mock_module}):
+        return GrpcIndex(
+            host="https://x-abc.svc.pinecone.io",
+            api_key="k",
+        )
+
+
 def test_legacy_GRPCIndex_alias_imports() -> None:  # noqa: N802
     from pinecone.grpc import GRPCIndex as _GRPCIndex  # noqa: F401
 
@@ -33,3 +46,88 @@ def test_legacy_GRPCIndex_alias_constructs() -> None:  # noqa: N802
     mock_channel.query.return_value = {"matches": [], "namespace": ""}
     idx = _make_grpc_index_via_alias(mock_channel)
     assert isinstance(idx, GrpcIndex)
+
+
+class TestGrpcDescribeNamespace:
+    def test_grpc_describe_namespace_routes_to_channel(self) -> None:
+        mock_channel = MagicMock()
+        mock_channel.describe_namespace.return_value = {
+            "name": "movies",
+            "record_count": 42,
+        }
+        idx = _make_grpc_index(mock_channel)
+
+        result = idx.describe_namespace(name="movies")
+
+        mock_channel.describe_namespace.assert_called_once_with("movies", timeout_s=None)
+        assert isinstance(result, NamespaceDescription)
+        assert result.name == "movies"
+        assert result.record_count == 42
+        assert result.schema is None
+        assert result.indexed_fields is None
+
+    def test_grpc_describe_namespace_accepts_legacy_namespace_kwarg(self) -> None:
+        mock_channel = MagicMock()
+        mock_channel.describe_namespace.return_value = {
+            "name": "movies",
+            "record_count": 7,
+        }
+        idx = _make_grpc_index(mock_channel)
+
+        result = idx.describe_namespace(namespace="movies")  # type: ignore[call-arg]
+
+        mock_channel.describe_namespace.assert_called_once_with("movies", timeout_s=None)
+        assert result.name == "movies"
+        assert result.record_count == 7
+
+    def test_grpc_describe_namespace_both_kwargs_raise(self) -> None:
+        from pinecone.errors.exceptions import ValidationError
+
+        mock_channel = MagicMock()
+        idx = _make_grpc_index(mock_channel)
+
+        with pytest.raises(ValidationError, match=r"name=.*namespace="):
+            idx.describe_namespace(name="movies", namespace="movies")  # type: ignore[call-arg]
+
+    def test_grpc_describe_namespace_empty_name_raises(self) -> None:
+        from pinecone.errors.exceptions import ValidationError
+
+        mock_channel = MagicMock()
+        idx = _make_grpc_index(mock_channel)
+
+        with pytest.raises(ValidationError, match="non-empty"):
+            idx.describe_namespace(name="")
+
+        with pytest.raises(ValidationError, match="non-empty"):
+            idx.describe_namespace(name="   ")
+
+    def test_grpc_describe_namespace_with_schema_and_indexed_fields(self) -> None:
+        mock_channel = MagicMock()
+        mock_channel.describe_namespace.return_value = {
+            "name": "docs",
+            "record_count": 100,
+            "schema": {"fields": {"genre": {"filterable": True}}},
+            "indexed_fields": ["genre", "year"],
+        }
+        idx = _make_grpc_index(mock_channel)
+
+        result = idx.describe_namespace(name="docs")
+
+        assert result.name == "docs"
+        assert result.record_count == 100
+        assert result.schema is not None
+        assert result.schema.fields["genre"].filterable is True
+        assert result.indexed_fields is not None
+        assert result.indexed_fields.fields == ["genre", "year"]
+
+    def test_grpc_describe_namespace_passes_timeout(self) -> None:
+        mock_channel = MagicMock()
+        mock_channel.describe_namespace.return_value = {
+            "name": "ns1",
+            "record_count": 0,
+        }
+        idx = _make_grpc_index(mock_channel)
+
+        idx.describe_namespace(name="ns1", timeout=5.0)
+
+        mock_channel.describe_namespace.assert_called_once_with("ns1", timeout_s=5.0)