feat(backcompat): restore friendly AttributeError for removed top-level functions (BCG-012, BCG-252)

Intercepts access to 11 removed module-level names (init, create_index,
delete_index, list_indexes, describe_index, configure_index, scale_index,
create_collection, delete_collection, describe_collection, list_collections)
in __getattr__ and raises AttributeError with legacy-verbatim migration
guidance including an Example: block.

Adds parametrised unit tests covering all 12 names (11 + init call-form).

Author: jhamon

pinecone/__init__.py

@@ -545,6 +545,137 @@
 }
 
 
+_REMOVED_TOPLEVEL_FUNCTIONS: tuple[str, ...] = (
+    "init",
+    "create_index",
+    "delete_index",
+    "list_indexes",
+    "describe_index",
+    "configure_index",
+    "scale_index",
+    "create_collection",
+    "delete_collection",
+    "describe_collection",
+    "list_collections",
+)
+
+_REMOVED_FUNCTION_EXAMPLES: dict[str, str] = {
+    "init": """
+    import os
+    from pinecone import Pinecone, ServerlessSpec
+
+    pc = Pinecone(
+        api_key=os.environ.get("PINECONE_API_KEY")
+    )
+
+    # Now do stuff
+    if 'my_index' not in pc.list_indexes().names():
+        pc.create_index(
+            name='my_index',
+            dimension=1536,
+            metric='euclidean',
+            spec=ServerlessSpec(
+                cloud='aws',
+                region='us-west-2'
+            )
+        )
+""",
+    "list_indexes": """
+    from pinecone import Pinecone
+
+    pc = Pinecone(api_key='YOUR_API_KEY')
+
+    index_name = "quickstart" # or your index name
+
+    if index_name not in pc.list_indexes().names():
+        # do something
+""",
+    "describe_index": """
+    from pinecone import Pinecone
+
+    pc = Pinecone(api_key='YOUR_API_KEY')
+    pc.describe_index('my_index')
+""",
+    "create_index": """
+    from pinecone import Pinecone, ServerlessSpec
+
+    pc = Pinecone(api_key='YOUR_API_KEY')
+    pc.create_index(
+        name='my-index',
+        dimension=1536,
+        metric='euclidean',
+        spec=ServerlessSpec(
+            cloud='aws',
+            region='us-west-2'
+        )
+    )
+""",
+    "delete_index": """
+    from pinecone import Pinecone
+
+    pc = Pinecone(api_key='YOUR_API_KEY')
+    pc.delete_index('my_index')
+""",
+    "scale_index": """
+    from pinecone import Pinecone
+
+    pc = Pinecone(api_key='YOUR_API_KEY')
+    pc.configure_index('my_index', replicas=2)
+""",
+    "create_collection": """
+    from pinecone import Pinecone
+
+    pc = Pinecone(api_key='YOUR_API_KEY')
+    pc.create_collection(name='my_collection', source='my_index')
+""",
+    "list_collections": """
+    from pinecone import Pinecone
+
+    pc = Pinecone(api_key='YOUR_API_KEY')
+    pc.list_collections()
+""",
+    "delete_collection": """
+    from pinecone import Pinecone
+
+    pc = Pinecone(api_key='YOUR_API_KEY')
+    pc.delete_collection('my_collection')
+""",
+    "describe_collection": """
+    from pinecone import Pinecone
+
+    pc = Pinecone(api_key='YOUR_API_KEY')
+    pc.describe_collection('my_collection')
+""",
+    "configure_index": """
+    from pinecone import Pinecone
+
+    pc = Pinecone(api_key='YOUR_API_KEY')
+    pc.configure_index('my_index', replicas=2)
+""",
+}
+
+
+def _removed_function_message(name: str) -> str:
+    example = _REMOVED_FUNCTION_EXAMPLES[name]
+    if name == "init":
+        return (
+            "init is no longer a top-level attribute of the pinecone package.\n\n"
+            "Please create an instance of the Pinecone class instead.\n\n"
+            f"Example:\n{example}\n"
+        )
+    if name == "scale_index":
+        return (
+            "scale_index is no longer a top-level attribute of the pinecone package.\n\n"
+            "Please create a client instance and call the configure_index method instead.\n\n"
+            f"Example:\n{example}\n"
+        )
+    return (
+        f"{name} is no longer a top-level attribute of the pinecone package.\n\n"
+        f"To use {name}, please create a client instance and call the method there instead.\n\n"
+        f"Example:\n{example}\n"
+    )
+
+
 def __getattr__(name: str) -> Any:
     if name == "ValidationError":
         import warnings
@@ -558,6 +689,8 @@ def __getattr__(name: str) -> Any:
 
         globals()["ValidationError"] = ValidationError
         return ValidationError
+    if name in _REMOVED_TOPLEVEL_FUNCTIONS:
+        raise AttributeError(_removed_function_message(name))
     if name in _LAZY_IMPORTS:
         module_path, attr = _LAZY_IMPORTS[name]
         import importlib

tests/unit/test_removed_top_level_functions.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import pytest
+
+import pinecone
+
+REMOVED_NAMES = [
+    "init",
+    "create_index",
+    "delete_index",
+    "list_indexes",
+    "describe_index",
+    "configure_index",
+    "scale_index",
+    "create_collection",
+    "delete_collection",
+    "describe_collection",
+    "list_collections",
+]
+
+
+@pytest.mark.parametrize("name", REMOVED_NAMES)
+def test_removed_function_raises_attribute_error(name: str) -> None:
+    with pytest.raises(AttributeError) as exc_info:
+        getattr(pinecone, name)
+    msg = str(exc_info.value)
+    assert name in msg
+    assert "no longer a top-level attribute of the pinecone package" in msg
+    assert "Example:" in msg
+
+
+def test_removed_function_calls_raise_attribute_error() -> None:
+    with pytest.raises(AttributeError):
+        pinecone.init()  # type: ignore[attr-defined]