Migrate to Python 3.10+ Type Syntax

[jhamon]

Migrate to Python 3.10+ Type Syntax

Summary

This PR modernizes the Pinecone Python SDK's type annotations by migrating from legacy typing module syntax to Python 3.10+ built-in type syntax. All Union[X, Y] usages are replaced with X | Y, all Optional[X] usages are replaced with X | None, and deprecated typing aliases (Dict, Tuple) are replaced with built-in types (dict, tuple).

Problem

The SDK was using legacy type annotation syntax that has been superseded by cleaner, more readable Python 3.10+ syntax:

• Union[X, Y] is verbose and less readable than X | Y
• Optional[X] is redundant when X | None is more explicit
• Dict and Tuple from typing are deprecated in favor of built-in dict and tuple (PEP 585)

Since the SDK already requires Python 3.10+, we can take advantage of these modern syntax improvements.

Solution

Migrated all type annotations throughout the codebase to use Python 3.10+ syntax:

• Replaced Union[X, Y] with X | Y syntax
• Replaced Optional[X] with X | None syntax
• Replaced Dict with dict and Tuple with tuple in non-generated code
• Added from __future__ import annotations where needed for forward references
• Used List from typing only where necessary to avoid conflicts with methods named list

User-Facing Impact

Benefits

• Cleaner, More Readable Code: Modern type syntax is more concise and easier to read
• Better IDE Support: IDEs better understand the modern syntax and provide improved autocomplete
• Future-Proof: Aligns with Python's direction and best practices for Python 3.10+
• No Breaking Changes: All changes are purely syntactic - runtime behavior is unchanged

Breaking Changes

None - This is a purely syntactic 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.

Example Usage

The changes are internal, but here's how the improved type annotations look:

Before

from typing import Union, Optional, Dict, List

def search(
    query: Union[str, Dict[str, Any]],
    top_k: int,
    filter: Optional[Dict[str, Any]] = None,
    namespace: Optional[str] = None
) -> Dict[str, List[ScoredVector]]:
    ...

After

from typing import List  # Only needed where 'list' method conflicts

def search(
    query: str | dict[str, Any],
    top_k: int,
    filter: dict[str, Any] | None = None,
    namespace: str | None = None
) -> dict[str, List[ScoredVector]]:
    ...

Technical Details

Type Alias Handling

For type aliases that reference forward-declared types, we use TypeAlias with proper TYPE_CHECKING guards to ensure mypy can resolve types correctly while maintaining runtime compatibility.

Naming Conflicts

In classes with methods named list, we continue to use List from typing to avoid shadowing the built-in type. This affects:

• ApiKeyResource.list() method
• IndexAsyncioInterface.list() method
• _IndexAsyncio.list() method
• GRPCIndex.list() method

Generated Code

Generated files in pinecone/core/ are not modified, as they are automatically generated from OpenAPI specifications. These will be updated when the code generation templates are updated in a future PR.

Testing

• All existing tests pass (414 unit tests, 4 skipped)
• Mypy type checking passes with no errors (353 source files checked)
• 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