Improve IDE Tab-Completion and Type Hinting Support

[jhamon]

Improve IDE Tab-Completion and Type Hinting Support

Summary

This PR enhances IDE tab-completion and type hinting support for the Pinecone Python SDK by ensuring complete type coverage. It adds missing return type annotations, class-level attribute type annotations, completes the type stub file, and ensures the py.typed marker file is included in package distribution.

Problem

Some areas of the codebase lacked complete type annotations, which limited IDE tab-completion and type checking capabilities:

• Some methods were missing return type annotations (e.g., UpsertResponseTransformer.get(), __getattr__())
• Instance attributes lacked class-level type annotations, making it difficult for IDEs to infer types
• The __init__.pyi stub file was incomplete, missing several exported types including deprecated functions, the Admin class, __version__, and various lazy-loaded types
• The py.typed marker file wasn't explicitly configured in the build system, potentially causing issues with type checker discovery

Solution

Enhanced IDE support and type checking by:

• Ensured py.typed marker file is included: Added explicit configuration in pyproject.toml to guarantee the PEP 561 marker file is packaged
• Added missing return type annotations: Added return types to UpsertResponseTransformer.get() (returns UpsertResponse) and __getattr__() (returns Any)
• Added class-level type annotations: Added type annotations for instance attributes in:
  • PluginAware._plugins_loaded
  • UpsertResponseTransformer._apply_result
  • Index class attributes (_config, _openapi_config, _pool_threads, _vector_api, _api_client)
  • IndexAsyncio class attributes (config, _openapi_config, _vector_api, _api_client)
• Completed __init__.pyi stub file: Added all missing exported types including:
  • Deprecated top-level functions (init, create_index, delete_index, etc.)
  • Admin class
  • __version__
  • Missing lazy-loaded types (FilterBuilder, ByocSpec, BackupModel, RestoreJobModel, RestoreJobList, BackupList, and all ReadCapacity and MetadataSchema types)
• Fixed type annotation: Replaced Optional[str] with str | None in vector_grpc.py for consistency

User-Facing Impact

Benefits

• Enhanced IDE Support: Complete type annotations enable better autocomplete, tab-completion, and inline type hints in IDEs like VS Code, PyCharm, and others
• Better Type Checking: More complete type coverage improves static type checking with mypy, pyright, and other tools
• Improved Developer Experience: Developers get better IntelliSense and can catch type errors earlier in their development workflow
• No Breaking Changes: All changes are purely additive - runtime behavior is unchanged

Breaking Changes

None - This is a purely additive change. All existing code continues to work without modification.

Migration Guide

No migration required for users. The changes are internal to the SDK and transparent to users. Users will automatically benefit from improved IDE support when they update to this version.

Example Usage

The improvements are transparent to users, but developers will notice better IDE support:

from pinecone import Pinecone

pc = Pinecone(api_key="your-api-key")
index = pc.Index("my-index")

# IDE now provides better autocomplete and type hints for:
# - index.upsert() method parameters and return type
# - index.query() method parameters and return type
# - All exported types from pinecone package

Technical Details

Type Stub File Completion

The __init__.pyi stub file now includes all exports from __init__.py, ensuring type checkers and IDEs have complete information about what's available in the package. This includes:

• All lazy-loaded types that are dynamically imported
• Deprecated functions that raise helpful error messages
• All enum types, model classes, and dataclasses

Class-Level Attribute Annotations

Adding class-level type annotations for instance attributes (PEP 526) allows IDEs to:

• Provide autocomplete for instance attributes
• Show type information in hover tooltips
• Perform type checking on attribute access

PEP 561 Compliance

Explicitly including py.typed in the package distribution ensures type checkers can discover that the package contains type information, following PEP 561 guidelines.

Testing

• All existing tests pass
• Mypy type checking passes with no errors (192 source files checked, excluding generated code)
• Verified py.typed is included in package distribution
• Verified __init__.pyi stub file matches all exports from __init__.py
• All files compile successfully

Compatibility

• Python Version: Requires Python 3.10+ (already a requirement)
• Backward Compatibility: Fully backward compatible - no API changes
• Type Checkers: Compatible with mypy, pyright, and other modern type checkers