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

[hebaalazzeh]

This PR implements PEP 0810 explicit lazy imports in google-cloud-core. On Python 3.15+, this defers loading of heavy inner modules and third-party dependencies (grpcio, cryptography, requests, and protobuf descriptor pools) to reduce serverless cold starts and memory footprints. On Python 3.14 and below, this falls back safely to eager execution with zero backwards-compatibility risk.

Related Links

Design doc: go/sdk:python-lazy-loading

[gemini-code-assist]

Code Review

This pull request refactors the client certificate source helper in the gapic-generator into a shared compat module and introduces PEP 0810 explicit lazy imports (lazy_modules) across several google-cloud-core modules. The review feedback highlights critical issues where adding conditionally imported modules (such as grpc, google.auth.api_key, and grpc._channel) to lazy_modules breaks historical graceful fallback behaviors; because deferred imports bypass the try-except blocks at module load time, they will cause unexpected runtime crashes. Additionally, using importlib.util.find_spec at the module level without error handling is unsafe and should be wrapped in a try-except block to prevent immediate import failures.

[gemini-code-assist]

Using importlib.util.find_spec("google.auth.api_key") at the module level is unsafe and defeats the purpose of lazy imports:

1. Potential Crash (Correctness): If google or google.auth is not installed or fails to import, find_spec will raise a ModuleNotFoundError immediately at module load time. Since this is not wrapped in a try...except block, it will crash the import of google.cloud.client, breaking backwards compatibility.
2. Defeats Lazy Imports (Efficiency): To resolve the spec of a submodule like google.auth.api_key, Python's import system must eagerly import the parent package google.auth. This completely defeats the lazy import of google.auth (which is listed in __lazy_modules__ to be deferred).

Recommendation:
Wrap the find_spec call in a try...except block to prevent crashes, and consider removing google.auth.api_key from __lazy_modules__ to avoid eager loading of google.auth.

Suggested change

	_has_google_auth_api_key = (
	importlib.util.find_spec("google.auth.api_key") is not None
	)
	try:
	_has_google_auth_api_key = (
	importlib.util.find_spec("google.auth.api_key") is not None
	)
	except ModuleNotFoundError:
	_has_google_auth_api_key = False

References

1. Do not replace historical graceful fallback behaviors with exceptions if doing so would introduce breaking changes for downstream users and violate backwards compatibility.

[gemini-code-assist]

If google.auth.api_key is added to __lazy_modules__, any subsequent try...except ImportError block wrapping its import will be rendered useless because the import is deferred and won't raise an exception during module load. To preserve the graceful fallback behavior, it should be excluded from lazy imports.

# google.auth.api_key is excluded from lazy imports to preserve the try-except fallback behavior.

References

1. Do not replace historical graceful fallback behaviors with exceptions if doing so would introduce breaking changes for downstream users and violate backwards compatibility.

[gemini-code-assist]

Under PEP 810 (or any lazy import mechanism), if grpc and google.auth.transport.grpc are added to __lazy_modules__, the import statements inside the subsequent try...except ImportError block are deferred and will not actually execute during module load.

This introduces a major correctness and backwards-compatibility issue:

1. Broken Graceful Fallback: If google.auth.transport.grpc fails to import, the ImportError will not be caught by the try...except block. Instead, the exception will be raised later at runtime when grpc or the transport is first accessed, causing unexpected crashes instead of gracefully falling back to grpc = None.
2. Redundant Try-Except: The try...except block is rendered completely useless because the deferred imports won't raise exceptions during its execution.

Recommendation:
Do not include modules that require conditional import checks and fallbacks (like grpc and google.auth.transport.grpc) in __lazy_modules__.

# grpc and its transport are excluded from lazy imports to preserve the try-except fallback behavior.

References

1. Do not replace historical graceful fallback behaviors with exceptions if doing so would introduce breaking changes for downstream users and violate backwards compatibility.

[gemini-code-assist]

Since grpc._channel is added to __lazy_modules__, the import from grpc._channel import _Rendezvous is deferred and will not execute during module load.

This breaks the graceful fallback behavior:

1. Broken Fallback: If _Rendezvous cannot be imported from grpc._channel, the ImportError will not be caught by the try...except block. Instead, it will be raised at runtime when GrpcRendezvous is first accessed, bypassing the fallback to None and crashing the application.
2. Redundant Try-Except: The try...except block is useless because the deferred import won't raise any exception during module load.

Recommendation:
Do not include grpc._channel in __lazy_modules__ if it relies on a try...except block for fallback.

# grpc and grpc._channel are excluded from lazy imports to preserve the try-except fallback behavior.

References

1. Do not replace historical graceful fallback behaviors with exceptions if doing so would introduce breaking changes for downstream users and violate backwards compatibility.