Migrate to Python 3.10+ Type Syntax (#548)

# 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
```python
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
```python
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

Author: jhamon

pinecone/admin/admin.py

@@ -3,7 +3,6 @@
 from pinecone.core.openapi.oauth import API_VERSION
 from pinecone.core.openapi.oauth.apis import OAuthApi
 from pinecone.core.openapi.oauth.models import TokenRequest
-from typing import Optional, Dict
 from pinecone.utils import get_user_agent
 import os
 from copy import deepcopy
@@ -34,14 +33,14 @@ class Admin:
     :param additional_headers: Additional headers to use for the Pinecone API. This is a
         dictionary of key-value pairs. This is primarily used for internal testing
         purposes.
-    :type additional_headers: Optional[Dict[str, str]]
+    :type additional_headers: Optional[dict[str, str]]
     """
 
     def __init__(
         self,
-        client_id: Optional[str] = None,
-        client_secret: Optional[str] = None,
-        additional_headers: Optional[Dict[str, str]] = None,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        additional_headers: dict[str, str] | None = None,
     ):
         """
         Initialize the ``Admin`` class.
@@ -58,7 +57,7 @@ def __init__(
         :param additional_headers: Additional headers to use for the Pinecone API. This is a
           dictionary of key-value pairs. This is primarily used for internal testing
           purposes.
-        :type additional_headers: Optional[Dict[str, str]]
+        :type additional_headers: Optional[dict[str, str]]
         """
 
         if client_id is not None:
@@ -112,7 +111,7 @@ def __init__(
         self._child_api_client.user_agent = get_user_agent(Config())
 
         # Lazily initialize resources
-        from typing import TYPE_CHECKING, Optional
+        from typing import TYPE_CHECKING
 
         if TYPE_CHECKING:
             from pinecone.admin.resources import (
@@ -121,9 +120,9 @@ def __init__(
                 OrganizationResource,
             )
 
-            self._project: Optional[ProjectResource] = None
-            self._api_key: Optional[ApiKeyResource] = None
-            self._organization: Optional[OrganizationResource] = None
+            self._project: ProjectResource | None = None
+            self._api_key: ApiKeyResource | None = None
+            self._organization: OrganizationResource | None = None
         else:
             self._project = None  # type: ignore[assignment]
             self._api_key = None  # type: ignore[assignment]

pinecone/admin/resources/api_key.py

@@ -1,4 +1,6 @@
-from typing import Optional, List
+from __future__ import annotations
+
+from typing import List
 from pinecone.openapi_support import ApiClient
 from pinecone.core.openapi.admin.apis import APIKeysApi
 from pinecone.utils import require_kwargs, parse_non_empty_args
@@ -151,8 +153,8 @@ def create(
         self,
         project_id: str,
         name: str,
-        description: Optional[str] = None,
-        roles: Optional[List[str]] = None,
+        description: str | None = None,
+        roles: List[str] | None = None,
     ):
         """
         Create an API key for a project.
@@ -169,7 +171,7 @@ def create(
         :param roles: The roles of the API key. Available roles include:
             ``ProjectEditor``, ``ProjectViewer``, ``ControlPlaneEditor``,
             ``ControlPlaneViewer``, ``DataPlaneEditor``, ``DataPlaneViewer``
-        :type roles: Optional[List[str]]
+        :type roles: Optional[list[str]]
         :return: The created API key object and value.
         :rtype: {"key": APIKey, "value": str}
 
@@ -210,9 +212,7 @@ def create(
         )
 
     @require_kwargs
-    def update(
-        self, api_key_id: str, name: Optional[str] = None, roles: Optional[List[str]] = None
-    ):
+    def update(self, api_key_id: str, name: str | None = None, roles: List[str] | None = None):
         """
         Update an API key.
 
@@ -226,7 +226,7 @@ def update(
             ``ControlPlaneViewer``, ``DataPlaneEditor``, ``DataPlaneViewer``.
             Existing roles will be removed if not included. If this field is omitted,
             the roles will not be updated.
-        :type roles: Optional[List[str]]
+        :type roles: Optional[list[str]]
         :return: The updated API key.
         :rtype: APIKey
 

pinecone/admin/resources/organization.py

@@ -1,4 +1,3 @@
-from typing import Optional
 from pinecone.openapi_support import ApiClient
 from pinecone.core.openapi.admin.apis import OrganizationsApi
 from pinecone.utils import require_kwargs, parse_non_empty_args
@@ -155,7 +154,7 @@ def describe(self, organization_id: str):
         return self.fetch(organization_id=organization_id)
 
     @require_kwargs
-    def update(self, organization_id: str, name: Optional[str] = None):
+    def update(self, organization_id: str, name: str | None = None):
         """
         Update an organization.
 

pinecone/admin/resources/project.py

@@ -1,4 +1,3 @@
-from typing import Optional
 from pinecone.exceptions import NotFoundException, PineconeException
 from pinecone.openapi_support import ApiClient
 from pinecone.core.openapi.admin.apis import ProjectsApi
@@ -79,7 +78,7 @@ def list(self):
         return self._projects_api.list_projects()
 
     @require_kwargs
-    def fetch(self, project_id: Optional[str] = None, name: Optional[str] = None):
+    def fetch(self, project_id: str | None = None, name: str | None = None):
         """
         Fetch a project by project_id or name.
 
@@ -152,7 +151,7 @@ def fetch(self, project_id: Optional[str] = None, name: Optional[str] = None):
                 return projects[0]
 
     @require_kwargs
-    def get(self, project_id: Optional[str] = None, name: Optional[str] = None):
+    def get(self, project_id: str | None = None, name: str | None = None):
         """Alias for :func:`fetch`
 
         Examples
@@ -179,7 +178,7 @@ def get(self, project_id: Optional[str] = None, name: Optional[str] = None):
         return self.fetch(project_id=project_id, name=name)
 
     @require_kwargs
-    def describe(self, project_id: Optional[str] = None, name: Optional[str] = None):
+    def describe(self, project_id: str | None = None, name: str | None = None):
         """Alias for :func:`fetch`
 
         Examples
@@ -206,7 +205,7 @@ def describe(self, project_id: Optional[str] = None, name: Optional[str] = None)
         return self.fetch(project_id=project_id, name=name)
 
     @require_kwargs
-    def exists(self, project_id: Optional[str] = None, name: Optional[str] = None):
+    def exists(self, project_id: str | None = None, name: str | None = None):
         """
         Check if a project exists by project_id or name.
 
@@ -272,10 +271,7 @@ def exists(self, project_id: Optional[str] = None, name: Optional[str] = None):
 
     @require_kwargs
     def create(
-        self,
-        name: str,
-        max_pods: Optional[int] = None,
-        force_encryption_with_cmek: Optional[bool] = None,
+        self, name: str, max_pods: int | None = None, force_encryption_with_cmek: bool | None = None
     ):
         """
         Create a project.
@@ -328,9 +324,9 @@ def create(
     def update(
         self,
         project_id: str,
-        name: Optional[str] = None,
-        max_pods: Optional[int] = None,
-        force_encryption_with_cmek: Optional[bool] = None,
+        name: str | None = None,
+        max_pods: int | None = None,
+        force_encryption_with_cmek: bool | None = None,
     ):
         """
         Update a project.

pinecone/config/config.py

@@ -1,4 +1,6 @@
-from typing import NamedTuple, Optional, Dict, TYPE_CHECKING
+from __future__ import annotations
+
+from typing import NamedTuple, TYPE_CHECKING
 import os
 
 from pinecone.exceptions import PineconeConfigurationError
@@ -9,7 +11,7 @@
 
 
 # Duplicated this util to help resolve circular imports
-def normalize_host(host: Optional[str]) -> str:
+def normalize_host(host: str | None) -> str:
     if host is None:
         return ""
     if host.startswith("https://"):
@@ -22,12 +24,12 @@ def normalize_host(host: Optional[str]) -> str:
 class Config(NamedTuple):
     api_key: str = ""
     host: str = ""
-    proxy_url: Optional[str] = None
-    proxy_headers: Optional[Dict[str, str]] = None
-    ssl_ca_certs: Optional[str] = None
-    ssl_verify: Optional[bool] = None
-    additional_headers: Optional[Dict[str, str]] = {}
-    source_tag: Optional[str] = None
+    proxy_url: str | None = None
+    proxy_headers: dict[str, str] | None = None
+    ssl_ca_certs: str | None = None
+    ssl_verify: bool | None = None
+    additional_headers: dict[str, str] | None = {}
+    source_tag: str | None = None
 
 
 class ConfigBuilder:
@@ -49,13 +51,13 @@ class ConfigBuilder:
 
     @staticmethod
     def build(
-        api_key: Optional[str] = None,
-        host: Optional[str] = None,
-        proxy_url: Optional[str] = None,
-        proxy_headers: Optional[Dict[str, str]] = None,
-        ssl_ca_certs: Optional[str] = None,
-        ssl_verify: Optional[bool] = None,
-        additional_headers: Optional[Dict[str, str]] = {},
+        api_key: str | None = None,
+        host: str | None = None,
+        proxy_url: str | None = None,
+        proxy_headers: dict[str, str] | None = None,
+        ssl_ca_certs: str | None = None,
+        ssl_verify: bool | None = None,
+        additional_headers: dict[str, str] | None = {},
         **kwargs,
     ) -> Config:
         api_key = api_key or kwargs.pop("api_key", None) or os.getenv("PINECONE_API_KEY")
@@ -83,7 +85,7 @@ def build(
 
     @staticmethod
     def build_openapi_config(
-        config: Config, openapi_config: Optional["OpenApiConfiguration"] = None, **kwargs
+        config: Config, openapi_config: "OpenApiConfiguration" | None = None, **kwargs
     ) -> "OpenApiConfiguration":
         if openapi_config:
             openapi_config = OpenApiConfigFactory.copy(

pinecone/config/openapi_config_factory.py

@@ -1,5 +1,4 @@
 import sys
-from typing import List, Optional, Tuple
 
 import certifi
 import socket
@@ -14,7 +13,7 @@
 
 class OpenApiConfigFactory:
     @classmethod
-    def build(cls, api_key: str, host: Optional[str] = None, **kwargs):
+    def build(cls, api_key: str, host: str | None = None, **kwargs):
         openapi_config = OpenApiConfiguration()
         openapi_config.api_key = {"ApiKeyAuth": api_key}
         openapi_config.host = host
@@ -56,7 +55,7 @@ def _get_socket_options(
         keep_alive_idle_sec: int = TCP_KEEPIDLE,
         keep_alive_interval_sec: int = TCP_KEEPINTVL,
         keep_alive_tries: int = TCP_KEEPCNT,
-    ) -> List[Tuple[int, int, int]]:
+    ) -> list[tuple[int, int, int]]:
         """
         Returns the socket options to pass to OpenAPI's Rest client
         Args:

pinecone/config/openapi_configuration.py

@@ -3,7 +3,7 @@
 import multiprocessing
 
 from pinecone.exceptions import PineconeApiValueError
-from typing import TypedDict, Optional
+from typing import TypedDict
 
 
 class HostSetting(TypedDict):
@@ -297,7 +297,7 @@ def debug(self, value: bool) -> None:
         :param value: The debug status, True or False.
         :type: bool
         """
-        previous_debug: Optional[bool] = getattr(self, "_debug", None)
+        previous_debug: bool | None = getattr(self, "_debug", None)
         self._debug = value
 
         def enable_http_logging():

pinecone/config/pinecone_config.py

@@ -1,4 +1,3 @@
-from typing import Optional, Dict
 import logging
 import json
 import os
@@ -13,9 +12,9 @@
 class PineconeConfig:
     @staticmethod
     def build(
-        api_key: Optional[str] = None,
-        host: Optional[str] = None,
-        additional_headers: Optional[Dict[str, str]] = {},
+        api_key: str | None = None,
+        host: str | None = None,
+        additional_headers: dict[str, str] | None = {},
         **kwargs,
     ) -> Config:
         host = (

pinecone/db_control/db_control.py

@@ -1,5 +1,7 @@
+from __future__ import annotations
+
 import logging
-from typing import Optional, TYPE_CHECKING
+from typing import TYPE_CHECKING
 
 from pinecone.core.openapi.db_control.api.manage_indexes_api import ManageIndexesApi
 from pinecone.openapi_support.api_client import ApiClient
@@ -42,16 +44,16 @@ def __init__(
         )
         """ :meta private: """
 
-        self._index_resource: Optional["IndexResource"] = None
+        self._index_resource: "IndexResource" | None = None
         """ :meta private: """
 
-        self._collection_resource: Optional["CollectionResource"] = None
+        self._collection_resource: "CollectionResource" | None = None
         """ :meta private: """
 
-        self._restore_job_resource: Optional["RestoreJobResource"] = None
+        self._restore_job_resource: "RestoreJobResource" | None = None
         """ :meta private: """
 
-        self._backup_resource: Optional["BackupResource"] = None
+        self._backup_resource: "BackupResource" | None = None
         """ :meta private: """
 
         super().__init__()  # Initialize PluginAware

pinecone/db_control/db_control_asyncio.py

@@ -1,5 +1,7 @@
+from __future__ import annotations
+
 import logging
-from typing import Optional, TYPE_CHECKING
+from typing import TYPE_CHECKING
 
 from pinecone.core.openapi.db_control.api.manage_indexes_api import AsyncioManageIndexesApi
 from pinecone.openapi_support import AsyncioApiClient
@@ -36,16 +38,16 @@ def __init__(self, config: "Config", openapi_config: "OpenApiConfiguration") ->
         )
         """ :meta private: """
 
-        self._index_resource: Optional["IndexResourceAsyncio"] = None
+        self._index_resource: "IndexResourceAsyncio" | None = None
         """ :meta private: """
 
-        self._collection_resource: Optional["CollectionResourceAsyncio"] = None
+        self._collection_resource: "CollectionResourceAsyncio" | None = None
         """ :meta private: """
 
-        self._restore_job_resource: Optional["RestoreJobResourceAsyncio"] = None
+        self._restore_job_resource: "RestoreJobResourceAsyncio" | None = None
         """ :meta private: """
 
-        self._backup_resource: Optional["BackupResourceAsyncio"] = None
+        self._backup_resource: "BackupResourceAsyncio" | None = None
         """ :meta private: """
 
     @property