fix(indexes): raise IndexTerminatedError for Terminating/Disabled states during polling

## Purpose

`poll_index_until_ready` and `async_poll_index_until_ready` only escaped
the polling loop on `InitializationFailed`. Indexes entering `Terminating`
or `Disabled` states caused the poller to spin until timeout, giving the
caller a generic `PineconeTimeoutError` instead of an actionable error.

## Solution

Added `IndexTerminatedError(PineconeError)` to `pinecone/errors/exceptions.py`
and exported it from `pinecone/errors/__init__.py`. Both sync and async pollers
in `pinecone/_internal/indexes_helpers.py` now check for `Terminating`/`Disabled`
immediately after the `InitializationFailed` guard and raise `IndexTerminatedError`
with the index name and terminal state string. Unit tests cover all three
terminal states (plus the ready success path) for both sync and async variants.

Author: jhamon

pinecone/_internal/indexes_helpers.py

@@ -321,9 +321,14 @@ def poll_index_until_ready(
 
     Raises:
         IndexInitFailedError: If the index enters ``InitializationFailed`` state.
+        IndexTerminatedError: If the index enters ``Terminating`` or ``Disabled`` state.
         PineconeTimeoutError: If *timeout* seconds elapse without becoming ready.
     """
-    from pinecone.errors.exceptions import IndexInitFailedError, PineconeTimeoutError
+    from pinecone.errors.exceptions import (
+        IndexInitFailedError,
+        IndexTerminatedError,
+        PineconeTimeoutError,
+    )
 
     start = time.monotonic()
     while True:
@@ -332,6 +337,8 @@ def poll_index_until_ready(
             return idx
         if idx.status.state == "InitializationFailed":
             raise IndexInitFailedError(name)
+        if idx.status.state in ("Terminating", "Disabled"):
+            raise IndexTerminatedError(name, idx.status.state)
         if timeout is not None:
             elapsed = time.monotonic() - start
             if elapsed >= timeout:
@@ -359,9 +366,14 @@ async def async_poll_index_until_ready(
 
     Raises:
         IndexInitFailedError: If the index enters ``InitializationFailed`` state.
+        IndexTerminatedError: If the index enters ``Terminating`` or ``Disabled`` state.
         PineconeTimeoutError: If *timeout* seconds elapse without becoming ready.
     """
-    from pinecone.errors.exceptions import IndexInitFailedError, PineconeTimeoutError
+    from pinecone.errors.exceptions import (
+        IndexInitFailedError,
+        IndexTerminatedError,
+        PineconeTimeoutError,
+    )
 
     start = time.monotonic()
     while True:
@@ -370,6 +382,8 @@ async def async_poll_index_until_ready(
             return idx
         if idx.status.state == "InitializationFailed":
             raise IndexInitFailedError(name)
+        if idx.status.state in ("Terminating", "Disabled"):
+            raise IndexTerminatedError(name, idx.status.state)
         if timeout is not None:
             elapsed = time.monotonic() - start
             if elapsed >= timeout:

pinecone/errors/__init__.py

@@ -7,6 +7,7 @@
     ConflictError,
     ForbiddenError,
     IndexInitFailedError,
+    IndexTerminatedError,
     NotFoundError,
     PineconeConnectionError,
     PineconeError,
@@ -24,6 +25,7 @@
     "ConflictError",
     "ForbiddenError",
     "IndexInitFailedError",
+    "IndexTerminatedError",
     "NotFoundError",
     "PineconeConnectionError",
     "PineconeError",

pinecone/errors/exceptions.py

@@ -210,6 +210,21 @@ def __init__(self, index_name: str) -> None:
         self.index_name = index_name
 
 
+class IndexTerminatedError(PineconeError):
+    """Raised when polling an index that has entered a terminal non-init state.
+
+    Terminal states include ``Terminating`` and ``Disabled``.
+    """
+
+    def __init__(self, name: str, state: str) -> None:
+        super().__init__(
+            f"Index '{name}' entered terminal state '{state}'. "
+            f"Check status with pc.describe_index(name='{name}')."
+        )
+        self.name = name
+        self.state = state
+
+
 class PineconeTimeoutError(PineconeError, TimeoutError):
     """Raised when an operation exceeds its timeout.
 

tests/unit/test_indexes_helpers.py

@@ -2,16 +2,21 @@
 
 from __future__ import annotations
 
+from unittest.mock import AsyncMock, MagicMock
+
 import pytest
 
 from pinecone._internal.indexes_helpers import (
     _normalize_schema,
+    async_poll_index_until_ready,
     build_byoc_body,
     build_create_body,
     build_integrated_body,
+    poll_index_until_ready,
     validate_read_capacity,
 )
-from pinecone.errors.exceptions import ValidationError
+from pinecone.errors.exceptions import IndexInitFailedError, IndexTerminatedError, ValidationError
+from pinecone.models.indexes.index import IndexModel, IndexSpec, IndexStatus, ServerlessSpecInfo
 from pinecone.models.indexes.specs import ByocSpec, EmbedConfig, IntegratedSpec, ServerlessSpec
 
 
@@ -358,3 +363,71 @@ def test_build_integrated_body_method_schema_bare_input_gets_wrapped() -> None:
         schema={"genre": {"filterable": True}},
     )
     assert body["schema"] == {"fields": {"genre": {"filterable": True}}}
+
+
+# poll_index_until_ready terminal-state tests
+
+
+def _make_index(state: str, ready: bool = False) -> IndexModel:
+    return IndexModel(
+        name="test-index",
+        dimension=1536,
+        metric="cosine",
+        host="test-index.svc.pinecone.io",
+        spec=IndexSpec(serverless=ServerlessSpecInfo(cloud="aws", region="us-east-1")),
+        status=IndexStatus(ready=ready, state=state),
+        deletion_protection="disabled",
+        tags=None,
+    )
+
+
+def test_poll_index_until_ready_raises_on_terminating() -> None:
+    describe_fn = MagicMock(return_value=_make_index("Terminating"))
+    with pytest.raises(IndexTerminatedError) as exc_info:
+        poll_index_until_ready(describe_fn, "test-index", timeout=10)
+    assert exc_info.value.state == "Terminating"
+    assert exc_info.value.name == "test-index"
+
+
+def test_poll_index_until_ready_raises_on_disabled() -> None:
+    describe_fn = MagicMock(return_value=_make_index("Disabled"))
+    with pytest.raises(IndexTerminatedError) as exc_info:
+        poll_index_until_ready(describe_fn, "test-index", timeout=10)
+    assert exc_info.value.state == "Disabled"
+    assert exc_info.value.name == "test-index"
+
+
+def test_poll_index_until_ready_still_raises_on_initialization_failed() -> None:
+    describe_fn = MagicMock(return_value=_make_index("InitializationFailed"))
+    with pytest.raises(IndexInitFailedError):
+        poll_index_until_ready(describe_fn, "test-index", timeout=10)
+
+
+def test_poll_index_until_ready_returns_on_ready(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("pinecone._internal.indexes_helpers.time.sleep", lambda *_: None)
+    ready_index = _make_index("Ready", ready=True)
+    describe_fn = MagicMock(return_value=ready_index)
+    result = poll_index_until_ready(describe_fn, "test-index", timeout=10)
+    assert result.status.ready is True
+
+
+async def test_async_poll_index_until_ready_raises_on_terminating() -> None:
+    describe_fn = AsyncMock(return_value=_make_index("Terminating"))
+    with pytest.raises(IndexTerminatedError) as exc_info:
+        await async_poll_index_until_ready(describe_fn, "test-index", timeout=10)
+    assert exc_info.value.state == "Terminating"
+    assert exc_info.value.name == "test-index"
+
+
+async def test_async_poll_index_until_ready_raises_on_disabled() -> None:
+    describe_fn = AsyncMock(return_value=_make_index("Disabled"))
+    with pytest.raises(IndexTerminatedError) as exc_info:
+        await async_poll_index_until_ready(describe_fn, "test-index", timeout=10)
+    assert exc_info.value.state == "Disabled"
+    assert exc_info.value.name == "test-index"
+
+
+async def test_async_poll_index_until_ready_still_raises_on_initialization_failed() -> None:
+    describe_fn = AsyncMock(return_value=_make_index("InitializationFailed"))
+    with pytest.raises(IndexInitFailedError):
+        await async_poll_index_until_ready(describe_fn, "test-index", timeout=10)