feat(core): implement PEP 0810 explicit lazy imports in google-cloud-core

packages/google-cloud-core/.flake8

@@ -9,3 +9,11 @@ exclude =
  .git,
  *.pyc,
  conf.py
+# PEP 0810 lazy imports require __lazy_modules__ to precede import statements,
+# which causes flake8 to flag module-level imports as E402.
+per-file-ignores =
+ google/cloud/_helpers/__init__.py: E402
+ google/cloud/_http/__init__.py: E402
+ google/cloud/client/__init__.py: E402
+ google/cloud/exceptions/__init__.py: E402
+ google/cloud/operation/__init__.py: E402

packages/google-cloud-core/google/cloud/_helpers/__init__.py

@@ -25,7 +25,25 @@
 import os
 import re
 from threading import local as Local
-from typing import Union
+from typing import Set, Union
+
+# PEP 0810: Explicit Lazy Imports
+# Python 3.15+ natively intercepts and defers these imports.
+# Developers can disable this behavior and force eager imports.
+# For more information, see:
+# https://docs.python.org/3.15/library/sys.html#sys.set_lazy_imports_filter
+# Older Python versions safely ignore this variable.
+# NOTE: We statically define all modules here to ensure static analysis tools
+# (mypy, pyright, Ruff) can easily parse them. If support is not present, the
+# imports are ignored, making their presence safe.
+__lazy_modules__: Set[str] = {
+ "google.auth",
+ "google.auth.transport.grpc",
+ "google.auth.transport.requests",
+ "google.protobuf.duration_pb2",
+ "google.protobuf.timestamp_pb2",
+ "grpc",
+}
 
 import google.auth
 import google.auth.transport.requests

packages/google-cloud-core/google/cloud/_http/__init__.py

@@ -19,10 +19,25 @@
 import json
 import os
 import platform
-from typing import Optional
+from typing import Optional, Set
 from urllib.parse import urlencode
 import warnings
 
+# PEP 0810: Explicit Lazy Imports
+# Python 3.15+ natively intercepts and defers these imports.
+# Developers can disable this behavior and force eager imports.
+# For more information, see:
+# https://docs.python.org/3.15/library/sys.html#sys.set_lazy_imports_filter
+# Older Python versions safely ignore this variable.
+# NOTE: We statically define all modules here to ensure static analysis tools
+# (mypy, pyright, Ruff) can easily parse them. If support is not present, the
+# imports are ignored, making their presence safe.
+__lazy_modules__: Set[str] = {
+ "google.api_core.client_info",
+ "google.cloud.exceptions",
+ "google.cloud.version",
+}
+
 from google.api_core.client_info import ClientInfo
 from google.cloud import exceptions
 from google.cloud import version

packages/google-cloud-core/google/cloud/client/__init__.py

@@ -18,8 +18,29 @@
 import json
 import os
 from pickle import PicklingError
-from typing import Tuple
-from typing import Union
+from typing import Set, Tuple, Union
+
+# PEP 0810: Explicit Lazy Imports
+# Python 3.15+ natively intercepts and defers these imports.
+# Developers can disable this behavior and force eager imports.
+# For more information, see:
+# https://docs.python.org/3.15/library/sys.html#sys.set_lazy_imports_filter
+# Older Python versions safely ignore this variable.
+# NOTE: We statically define all modules here to ensure static analysis tools
+# (mypy, pyright, Ruff) can easily parse them. If support is not present, the
+# imports are ignored, making their presence safe.
+__lazy_modules__: Set[str] = {
+ "google.api_core.client_options",
+ "google.api_core.exceptions",
+ "google.auth",
+ "google.auth.api_key",
+ "google.auth.environment_vars",
+ "google.auth.credentials",
+ "google.auth.transport.requests",
+ "google.cloud._helpers",
+ "google.oauth2",
+ "google.oauth2.service_account",
+}
 
 import google.api_core.client_options
 import google.api_core.exceptions

packages/google-cloud-core/google/cloud/exceptions/__init__.py

@@ -21,6 +21,23 @@
 # Avoid the grpc and google.cloud.grpc collision.
 from __future__ import absolute_import
 
+from typing import Set
+
+# PEP 0810: Explicit Lazy Imports
+# Python 3.15+ natively intercepts and defers these imports.
+# Developers can disable this behavior and force eager imports.
+# For more information, see:
+# https://docs.python.org/3.15/library/sys.html#sys.set_lazy_imports_filter
+# Older Python versions safely ignore this variable.
+# NOTE: We statically define all modules here to ensure static analysis tools
+# (mypy, pyright, Ruff) can easily parse them. If support is not present, the
+# imports are ignored, making their presence safe.
+__lazy_modules__: Set[str] = {
+ "google.api_core.exceptions",
+ "grpc",
+ "grpc._channel",
+}
+
 from google.api_core import exceptions
 
 try:

packages/google-cloud-core/google/cloud/operation/__init__.py

@@ -14,7 +14,23 @@
 
 """Wrap long-running operations returned from Google Cloud APIs."""
 
-from typing import Dict
+from typing import Dict, Set
+
+# PEP 0810: Explicit Lazy Imports
+# Python 3.15+ natively intercepts and defers these imports.
+# Developers can disable this behavior and force eager imports.
+# For more information, see:
+# https://docs.python.org/3.15/library/sys.html#sys.set_lazy_imports_filter
+# Older Python versions safely ignore this variable.
+# NOTE: We statically define all modules here to ensure static analysis tools
+# (mypy, pyright, Ruff) can easily parse them. If support is not present, the
+# imports are ignored, making their presence safe.
+__lazy_modules__: Set[str] = {
+ "google.longrunning",
+ "google.longrunning.operations_pb2",
+ "google.protobuf",
+ "google.protobuf.json_format",
+}
 
 from google.longrunning import operations_pb2
 from google.protobuf import json_format