Review and update Pinecone class docstrings

Author: jhamon

pinecone/__init__.pyi

@@ -79,16 +79,59 @@ from pinecone.db_control.models import (
     ServerlessSpecDefinition,
     PodSpec,
     PodSpecDefinition,
+    ByocSpec,
+    BackupModel,
+    BackupList,
+    RestoreJobModel,
+    RestoreJobList,
 )
+from pinecone.db_control.models.serverless_spec import (
+    ScalingConfigManualDict,
+    ReadCapacityDedicatedConfigDict,
+    ReadCapacityOnDemandDict,
+    ReadCapacityDedicatedDict,
+    ReadCapacityDict,
+    MetadataSchemaFieldConfig,
+)
+from pinecone.db_data.filter_builder import FilterBuilder
 from pinecone.db_control.types import ConfigureIndexEmbed, CreateIndexForModelEmbedTypedDict
 from pinecone.pinecone import Pinecone
 from pinecone.pinecone_asyncio import PineconeAsyncio
+from pinecone.admin import Admin
+from pinecone.utils import __version__
+
+# Deprecated top-level functions
+def init(*args: object, **kwargs: object) -> None: ...
+def create_index(*args: object, **kwargs: object) -> None: ...
+def delete_index(*args: object, **kwargs: object) -> None: ...
+def list_indexes(*args: object, **kwargs: object) -> None: ...
+def describe_index(*args: object, **kwargs: object) -> None: ...
+def configure_index(*args: object, **kwargs: object) -> None: ...
+def scale_index(*args: object, **kwargs: object) -> None: ...
+def create_collection(*args: object, **kwargs: object) -> None: ...
+def delete_collection(*args: object, **kwargs: object) -> None: ...
+def describe_collection(*args: object, **kwargs: object) -> None: ...
+def list_collections(*args: object, **kwargs: object) -> None: ...
 
 # Re-export all the types
 __all__ = [
+    "__version__",
+    # Deprecated top-level functions
+    "init",
+    "create_index",
+    "delete_index",
+    "list_indexes",
+    "describe_index",
+    "configure_index",
+    "scale_index",
+    "create_collection",
+    "delete_collection",
+    "describe_collection",
+    "list_collections",
     # Primary client classes
     "Pinecone",
     "PineconeAsyncio",
+    "Admin",
     # Config classes
     "Config",
     "ConfigBuilder",
@@ -139,6 +182,7 @@ __all__ = [
     "UpdateRequest",
     "NamespaceDescription",
     "ImportErrorMode",
+    "FilterBuilder",
     # Error classes
     "VectorDictionaryMissingKeysError",
     "VectorDictionaryExcessKeysError",
@@ -166,7 +210,18 @@ __all__ = [
     "ServerlessSpecDefinition",
     "PodSpec",
     "PodSpecDefinition",
+    "ByocSpec",
+    "BackupModel",
+    "BackupList",
+    "RestoreJobModel",
+    "RestoreJobList",
     # Control plane types
     "ConfigureIndexEmbed",
     "CreateIndexForModelEmbedTypedDict",
+    "ScalingConfigManualDict",
+    "ReadCapacityDedicatedConfigDict",
+    "ReadCapacityOnDemandDict",
+    "ReadCapacityDedicatedDict",
+    "ReadCapacityDict",
+    "MetadataSchemaFieldConfig",
 ]

pinecone/db_data/index.py

@@ -107,10 +107,13 @@ class UpsertResponseTransformer:
     while delegating other methods to the underlying ApplyResult.
     """
 
-    def __init__(self, apply_result: ApplyResult):
+    _apply_result: ApplyResult
+    """ :meta private: """
+
+    def __init__(self, apply_result: ApplyResult) -> None:
         self._apply_result = apply_result
 
-    def get(self, timeout=None):
+    def get(self, timeout: float | None = None) -> UpsertResponse:
         openapi_response = self._apply_result.get(timeout)
         from pinecone.utils.response_info import extract_response_info
 
@@ -123,7 +126,7 @@ def get(self, timeout=None):
             upserted_count=openapi_response.upserted_count, _response_info=response_info
         )
 
-    def __getattr__(self, name):
+    def __getattr__(self, name: str) -> Any:
         # Delegate other methods to the underlying ApplyResult
         return getattr(self._apply_result, name)
 
@@ -134,6 +137,21 @@ class Index(PluginAware, IndexInterface):
     For improved performance, use the Pinecone GRPC index client.
     """
 
+    _config: "Config"
+    """ :meta private: """
+
+    _openapi_config: "OpenApiConfiguration"
+    """ :meta private: """
+
+    _pool_threads: int
+    """ :meta private: """
+
+    _vector_api: VectorOperationsApi
+    """ :meta private: """
+
+    _api_client: ApiClient
+    """ :meta private: """
+
     _bulk_import_resource: "BulkImportResource" | None
     """ :meta private: """
 

pinecone/db_data/index_asyncio.py

@@ -65,6 +65,7 @@
 from .query_results_aggregator import QueryNamespacesResults
 
 if TYPE_CHECKING:
+    from pinecone.config import Config, OpenApiConfiguration
     from .resources.asyncio.bulk_import_asyncio import BulkImportResourceAsyncio
     from .resources.asyncio.namespace_asyncio import NamespaceResourceAsyncio
 
@@ -168,6 +169,18 @@ async def main():
     Failing to do this may result in error messages appearing from the underlyling aiohttp library.
     """
 
+    config: "Config"
+    """ :meta private: """
+
+    _openapi_config: "OpenApiConfiguration"
+    """ :meta private: """
+
+    _vector_api: AsyncioVectorOperationsApi
+    """ :meta private: """
+
+    _api_client: AsyncioApiClient
+    """ :meta private: """
+
     _bulk_import_resource: "BulkImportResourceAsyncio" | None
     """ :meta private: """
 

pinecone/db_data/interfaces.py

@@ -244,11 +244,38 @@ def upsert_from_dataframe(
     ):
         """Upserts a dataframe into the index.
 
-        Args:
-            df: A pandas dataframe with the following columns: id, values, sparse_values, and metadata.
-            namespace: The namespace to upsert into.
-            batch_size: The number of rows to upsert in a single batch.
-            show_progress: Whether to show a progress bar.
+        :param df: A pandas dataframe with the following columns: id, values, sparse_values, and metadata.
+        :type df: pandas.DataFrame
+        :param namespace: The namespace to upsert into.
+        :type namespace: str, optional
+        :param batch_size: The number of rows to upsert in a single batch.
+        :type batch_size: int, optional
+        :param show_progress: Whether to show a progress bar.
+        :type show_progress: bool, optional
+
+        .. code-block:: python
+
+            import pandas as pd
+            from pinecone import Pinecone
+
+            pc = Pinecone()
+            idx = pc.Index(host="your-index-host")
+
+            # Create a dataframe with vector data
+            df = pd.DataFrame({
+                'id': ['id1', 'id2', 'id3'],
+                'values': [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6], [0.7, 0.8, 0.9]],
+                'metadata': [{'key': 'value1'}, {'key': 'value2'}, {'key': 'value3'}]
+            })
+
+            # Upsert the dataframe
+            idx.upsert_from_dataframe(
+                df=df,
+                namespace="my-namespace",
+                batch_size=100,
+                show_progress=True
+            )
+
         """
         pass
 
@@ -276,7 +303,7 @@ def upsert_records(self, namespace: str, records: list[dict]) -> UpsertResponse:
                 Pinecone,
                 CloudProvider,
                 AwsRegion,
-                EmbedModel
+                EmbedModel,
                 IndexEmbed
             )
 
@@ -382,7 +409,7 @@ def search(
                 Pinecone,
                 CloudProvider,
                 AwsRegion,
-                EmbedModel
+                EmbedModel,
                 IndexEmbed
             )