feat(backcompat): plumb Pinecone(pool_threads=N) through to Index (BC-0110)

- Add `_LegacyIndexKwargs(IndexKwargs)` TypedDict in indexes_helpers.py with
  `pool_threads: NotRequired[int]`; keeps `IndexKwargs` clean for async client
- Store `_legacy_pool_threads: int | None` on `Pinecone` instance (replaces silent
  debug log); `_build_index_kwargs` returns `_LegacyIndexKwargs` and conditionally
  includes `pool_threads` so `Index(**kwargs)` receives it and installs async_req
- Add `tests/unit/test_pinecone_pool_threads.py` with five unit tests covering:
  attribute capture, kwarg propagation, field presence/absence, no-warning, and
  end-to-end install-hook firing via `Pinecone.index(host=...)`

Author: jhamon

pinecone/_client.py

@@ -2,13 +2,12 @@
 
 from __future__ import annotations
 
-import logging
 from dataclasses import replace
 from typing import TYPE_CHECKING, Any, cast
 
 from pinecone._internal.config import PineconeConfig, RetryConfig
 from pinecone._internal.constants import CONTROL_PLANE_API_VERSION, DEFAULT_BASE_URL
-from pinecone._internal.indexes_helpers import IndexKwargs, poll_index_until_ready
+from pinecone._internal.indexes_helpers import _LegacyIndexKwargs, poll_index_until_ready
 from pinecone._internal.validation import require_non_empty
 from pinecone.errors.exceptions import ValidationError
 
@@ -47,8 +46,6 @@
     )
     from pinecone.preview import Preview
 
-logger = logging.getLogger(__name__)
-
 
 class Pinecone:
     """Synchronous Pinecone client for control-plane operations.
@@ -108,13 +105,6 @@ def __init__(
         legacy_pool_threads = kwargs.pop("pool_threads", None)
         if kwargs:
             raise TypeError(f"Pinecone() got unexpected keyword arguments: {sorted(kwargs)!r}")
-        if legacy_pool_threads is not None:
-            logger.debug(
-                "Pinecone(pool_threads=%r) is accepted for backcompat but no "
-                "longer used; the new client uses httpx connection pooling. "
-                "Tune connection_pool_maxsize= instead.",
-                legacy_pool_threads,
-            )
         config = PineconeConfig(
             api_key=api_key or "",
             host=host or "",
@@ -153,6 +143,7 @@ def __init__(
         self._assistants: Assistants | None = None
         self._host_cache: dict[str, str] = {}
         self._preview: Preview | None = None
+        self._legacy_pool_threads: int | None = legacy_pool_threads
 
     def __repr__(self) -> str:
         masked = f"...{self._config.api_key[-4:]}" if len(self._config.api_key) >= 4 else "***"
@@ -372,9 +363,9 @@ def index(
 
         return _Index(**self._build_index_kwargs(resolved_host))
 
-    def _build_index_kwargs(self, host: str) -> IndexKwargs:
-        """Return the kwargs dict for constructing an Index or AsyncIndex."""
-        return IndexKwargs(
+    def _build_index_kwargs(self, host: str) -> _LegacyIndexKwargs:
+        """Return the kwargs dict for constructing an Index."""
+        kwargs: _LegacyIndexKwargs = _LegacyIndexKwargs(
             host=host,
             api_key=self._config.api_key,
             additional_headers=dict(self._config.additional_headers),
@@ -386,6 +377,9 @@ def _build_index_kwargs(self, host: str) -> IndexKwargs:
             source_tag=self._config.source_tag,
             connection_pool_maxsize=self._config.connection_pool_maxsize,
         )
+        if self._legacy_pool_threads is not None:
+            kwargs["pool_threads"] = self._legacy_pool_threads
+        return kwargs
 
     def _resolve_index_host(self, *, name: str, host: str) -> str:
         """Resolve the data plane host from explicit host, cache, or describe call.

pinecone/_internal/indexes_helpers.py

@@ -14,6 +14,7 @@
 from typing import TYPE_CHECKING, Any, TypedDict
 
 import msgspec
+from typing_extensions import NotRequired
 
 from pinecone._internal.validation import require_non_empty
 
@@ -53,6 +54,12 @@ class IndexKwargs(TypedDict):
     connection_pool_maxsize: int
 
 
+class _LegacyIndexKwargs(IndexKwargs):
+    """IndexKwargs extended with the legacy pool_threads field (sync client only)."""
+
+    pool_threads: NotRequired[int]
+
+
 def resolve_enum_value(value: Any) -> Any:
     """Extract ``.value`` from enum-like objects, pass through otherwise."""
     return value.value if hasattr(value, "value") else value

tests/unit/test_pinecone_class.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import logging
 import warnings
 from unittest.mock import MagicMock, patch
 
@@ -489,13 +488,9 @@ def test_pool_threads_kwarg_accepted_silently(self) -> None:
         pc = Pinecone(api_key="x", pool_threads=4)
         assert pc is not None
 
-    def test_pool_threads_kwarg_emits_debug_log(self, caplog: pytest.LogCaptureFixture) -> None:
-        with caplog.at_level(logging.DEBUG, logger="pinecone._client"):
-            Pinecone(api_key="x", pool_threads=4)
-        assert any(
-            "pool_threads" in r.message and "connection_pool_maxsize" in r.message
-            for r in caplog.records
-        )
+    def test_pool_threads_kwarg_stored_as_attribute(self) -> None:
+        pc = Pinecone(api_key="x", pool_threads=4)
+        assert pc._legacy_pool_threads == 4  # type: ignore[attr-defined]
 
     def test_pool_threads_kwarg_does_not_warn(self) -> None:
         with warnings.catch_warnings(record=True) as record:

tests/unit/test_pinecone_pool_threads.py

@@ -0,0 +1,56 @@
+"""Unit tests for Pinecone(pool_threads=N) propagation to Index (BC-0110)."""
+
+from __future__ import annotations
+
+import sys
+import warnings
+
+import pytest
+
+from pinecone import Pinecone
+
+
+def test_pinecone_without_pool_threads_does_not_import_legacy(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delitem(sys.modules, "pinecone._legacy.async_req", raising=False)
+    Pinecone(api_key="k")
+    assert "pinecone._legacy.async_req" not in sys.modules
+
+
+def test_pinecone_pool_threads_propagates_to_attribute() -> None:
+    pc = Pinecone(api_key="k")
+    assert pc._legacy_pool_threads is None  # type: ignore[attr-defined]
+
+    pc2 = Pinecone(api_key="k", pool_threads=8)
+    assert pc2._legacy_pool_threads == 8  # type: ignore[attr-defined]
+
+
+def test_pinecone_index_factory_passes_pool_threads() -> None:
+    pc = Pinecone(api_key="k", pool_threads=4)
+    kwargs = pc._build_index_kwargs("test.svc.pinecone.io")  # type: ignore[attr-defined]
+    assert kwargs["pool_threads"] == 4
+
+
+def test_pinecone_without_pool_threads_omits_field() -> None:
+    pc = Pinecone(api_key="k")
+    kwargs = pc._build_index_kwargs("test.svc.pinecone.io")  # type: ignore[attr-defined]
+    assert "pool_threads" not in kwargs
+
+
+def test_pinecone_pool_threads_emits_no_warning() -> None:
+    with warnings.catch_warnings(record=True) as record:
+        warnings.simplefilter("always")
+        Pinecone(api_key="k", pool_threads=4)
+    assert [w for w in record if issubclass(w.category, DeprecationWarning)] == []
+
+
+def test_pinecone_index_with_pool_threads_installs_async_req() -> None:
+    pc = Pinecone(api_key="k")
+    idx = pc.index(host="test.svc.pinecone.io")
+    assert not hasattr(idx, "_legacy_async_pool")
+
+    pc2 = Pinecone(api_key="k", pool_threads=4)
+    idx2 = pc2.index(host="test.svc.pinecone.io")
+    assert hasattr(idx2, "_legacy_async_pool")
+    assert idx2._legacy_async_pool_threads == 4  # type: ignore[attr-defined]