feat: implement native PEP 0810 lazy loading (#17591)

## Overview
This is an initiative to resolve severe initialization bottlenecks
(~10s-13s) in generated client libraries by adopting **Native Python
3.15 Explicit Lazy Imports (PEP 0810)**.
To avoid introducing maintenance burdens or subtle breaking changes via
custom import hooks, this PR focuses *exclusively* on utilizing native
interpreter standards.

### Implementation Architecture
We modify the upstream GAPIC Generator to emit a native
`__lazy_modules__` set at the top of the `__init__.py` files,
immediately followed by the standard eager imports.
* **Python 3.15+ (Native Acceleration):** The Python 3.15 runtime
natively intercepts the standard imports referenced in the
`__lazy_modules__` set and treats them as fast C-level lazy proxies.
Startup times drop from ~13s to ~200ms, and peak RAM consumption drops
by up to 85%.
* **Python 3.14 and Older (Zero Blast Radius):** Older Python
environments safely ignore the `__lazy_modules__` variable and process
the standard eager imports exactly as they do today. This guarantees
100% backwards compatibility with zero risk.
* **Perfect Static Typing:** Because standard imports are still present
in the file, IDEs (IntelliSense) and static analyzers (MyPy) maintain
zero-friction support.

**Example Structure:**
```python
# 1. Native C-Level Lazy Proxying for Python 3.15+ (PEP 0810)
__lazy_modules__ = {
   f"{__name__}.services.accelerator_types",
   f"{__name__}.services.addresses",
   f"{__name__}.types.compute",
}
# 2. Standard eager imports
# Evaluated instantly by older Python versions. Intercepted natively by Python 3.15.
from .services.accelerator_types import AcceleratorTypesClient
from .services.addresses import AddressesClient
from .types.compute import Address
__all__ = (
    "AcceleratorTypesClient",
    "AddressesClient",
    "Address",
)
```

## 🚀 Performance Benchmarking Results (Disk-Level Cold Start)

We utilized our custom `profiler.py` script #17467 to run 5 iterations
measuring true disk-level cold starts (with `__pycache__` sweeps) on the
`google-cloud-compute` library. The results validate this Phase 1 PEP
810 Native Lazy Loading implementation:

### Python 3.14 (Current Eager Import)
*   **Time (Median):** `23,246.97 ms` (~23.2 seconds)
*   **Memory (Physical RSS):** `224.87 MB`
*   **Code Volume:** Loaded `1,407` modules (`1,040,992` lines of code)

### Python 3.15.0b2 (Phase 1 PEP 810 Lazy Proxy)
*   **Time (Median):** `1,062.87 ms` (~1.06 seconds)
*   **Memory (Physical RSS):** `7.21 MB`
*   **Code Volume:** Loaded `15` modules (`8,064` lines of code)

**Impact:** By natively deferring the 120+ submodules at the C-level, we
bypassed parsing over **1 million lines of code**. This resulted in an
**approximately 22x reduction in startup latency (~95% speedup)**, and a
staggering **96% reduction in peak RAM consumption** (dropping from
~225MB down to just ~7MB).


Related Links:
see #17594 for a demonstration of this generator change applied to
google-cloud-compute package.
Design Doc: go/sdk-performance-design
Towards googleapis/python-aiplatform#4749

Author: hebaalazzeh

packages/gapic-generator/gapic/templates/%namespace/%name_%version/%sub/__init__.py.j2

@@ -12,6 +12,28 @@ __version__ = package_version.__version__
 
 from importlib import metadata
 
+# 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.
+__lazy_modules__ = {
+    {% filter sort_lines -%}
+    {% for subpackage, _ in api.subpackages|dictsort -%}
+    f"{__name__}.{{ subpackage }}",
+    {% endfor -%}
+    {% for service in api.services.values()
+            if service.meta.address.subpackage == api.subpackage_view -%}
+    f"{__name__}.services.{{ service.name|snake_case }}",
+    {% endfor -%}
+    {% for proto in api.protos.values()
+            if proto.meta.address.subpackage == api.subpackage_view -%}
+    f"{__name__}.types.{{ proto.module_name }}",
+    {% endfor -%}
+    {% endfilter %}
+}
+
 {#  Import subpackages. -#}
 {% for subpackage, _ in api.subpackages|dictsort %}
 from . import {{ subpackage }}

packages/gapic-generator/tests/integration/goldens/asset/google/cloud/asset_v1/__init__.py

@@ -22,6 +22,19 @@
 
 from importlib import metadata
 
+# 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.
+__lazy_modules__ = {
+f"{__name__}.services.asset_service",
+f"{__name__}.types.asset_enrichment_resourceowners",
+f"{__name__}.types.asset_service",
+f"{__name__}.types.assets",
+}
+
 
 from .services.asset_service import AssetServiceClient
 from .services.asset_service import AssetServiceAsyncClient

packages/gapic-generator/tests/integration/goldens/credentials/google/iam/credentials_v1/__init__.py

@@ -22,6 +22,18 @@
 
 from importlib import metadata
 
+# 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.
+__lazy_modules__ = {
+f"{__name__}.services.iam_credentials",
+f"{__name__}.types.common",
+f"{__name__}.types.iamcredentials",
+}
+
 
 from .services.iam_credentials import IAMCredentialsClient
 from .services.iam_credentials import IAMCredentialsAsyncClient

packages/gapic-generator/tests/integration/goldens/eventarc/google/cloud/eventarc_v1/__init__.py

@@ -22,6 +22,28 @@
 
 from importlib import metadata
 
+# 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.
+__lazy_modules__ = {
+f"{__name__}.services.eventarc",
+f"{__name__}.types.channel",
+f"{__name__}.types.channel_connection",
+f"{__name__}.types.discovery",
+f"{__name__}.types.enrollment",
+f"{__name__}.types.eventarc",
+f"{__name__}.types.google_api_source",
+f"{__name__}.types.google_channel_config",
+f"{__name__}.types.logging_config",
+f"{__name__}.types.message_bus",
+f"{__name__}.types.network_config",
+f"{__name__}.types.pipeline",
+f"{__name__}.types.trigger",
+}
+
 
 from .services.eventarc import EventarcClient
 from .services.eventarc import EventarcAsyncClient

packages/gapic-generator/tests/integration/goldens/logging/google/cloud/logging_v2/__init__.py

@@ -22,6 +22,22 @@
 
 from importlib import metadata
 
+# 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.
+__lazy_modules__ = {
+f"{__name__}.services.config_service_v2",
+f"{__name__}.services.logging_service_v2",
+f"{__name__}.services.metrics_service_v2",
+f"{__name__}.types.log_entry",
+f"{__name__}.types.logging",
+f"{__name__}.types.logging_config",
+f"{__name__}.types.logging_metrics",
+}
+
 
 from .services.config_service_v2 import ConfigServiceV2Client
 from .services.config_service_v2 import ConfigServiceV2AsyncClient

packages/gapic-generator/tests/integration/goldens/logging_internal/google/cloud/logging_v2/__init__.py

@@ -22,6 +22,22 @@
 
 from importlib import metadata
 
+# 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.
+__lazy_modules__ = {
+f"{__name__}.services.config_service_v2",
+f"{__name__}.services.logging_service_v2",
+f"{__name__}.services.metrics_service_v2",
+f"{__name__}.types.log_entry",
+f"{__name__}.types.logging",
+f"{__name__}.types.logging_config",
+f"{__name__}.types.logging_metrics",
+}
+
 
 from .services.config_service_v2 import BaseConfigServiceV2Client
 from .services.config_service_v2 import BaseConfigServiceV2AsyncClient

packages/gapic-generator/tests/integration/goldens/redis/google/cloud/redis_v1/__init__.py

@@ -22,6 +22,17 @@
 
 from importlib import metadata
 
+# 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.
+__lazy_modules__ = {
+f"{__name__}.services.cloud_redis",
+f"{__name__}.types.cloud_redis",
+}
+
 
 from .services.cloud_redis import CloudRedisClient
 from .services.cloud_redis import CloudRedisAsyncClient

packages/gapic-generator/tests/integration/goldens/redis_selective/google/cloud/redis_v1/__init__.py

@@ -22,6 +22,17 @@
 
 from importlib import metadata
 
+# 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.
+__lazy_modules__ = {
+f"{__name__}.services.cloud_redis",
+f"{__name__}.types.cloud_redis",
+}
+
 
 from .services.cloud_redis import CloudRedisClient
 from .services.cloud_redis import CloudRedisAsyncClient

packages/gapic-generator/tests/integration/goldens/storagebatchoperations/google/cloud/storagebatchoperations_v1/__init__.py

@@ -22,6 +22,18 @@
 
 from importlib import metadata
 
+# 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.
+__lazy_modules__ = {
+f"{__name__}.services.storage_batch_operations",
+f"{__name__}.types.storage_batch_operations",
+f"{__name__}.types.storage_batch_operations_types",
+}
+
 
 from .services.storage_batch_operations import StorageBatchOperationsClient
 from .services.storage_batch_operations import StorageBatchOperationsAsyncClient