FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

feat: implement native PEP 0810 lazy loading by hebaalazzeh · Pull Request #17591 · googleapis/google-cloud-python · GitHub

/ google-cloud-python Public

feat: implement native PEP 0810 lazy loading - #17591

Merged
hebaalazzeh merged 4 commits into
mainfrom
prototype-phase1-pep810
Jun 30, 2026
ConversationCommits (4)ChecksFiles changed
Merged

feat: implement native PEP 0810 lazy loading#17591
hebaalazzeh merged 4 commits into
mainfrom
prototype-phase1-pep810

Conversation

hebaalazzeh commented Jun 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

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:

# 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

gemini-code-assist Bot reviewed Jun 29, 2026
View reviewed changes

gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Code Review

This pull request adds a conditional check for Python 3.15+ to define __lazy_modules__ in the initialization file of google-cloud-compute. However, the sys module is not imported, which will cause a NameError at runtime. Since this is a generated file, the generator or templates should be updated to include the necessary import rather than applying manual fixes.

Comment thread packages/google-cloud-compute/google/cloud/compute_v1/__init__.py Outdated
hebaalazzeh force-pushed the prototype-phase1-pep810 branch from 06e45c9 to b277895 Compare June 30, 2026 06:08
hebaalazzeh force-pushed the prototype-phase1-pep810 branch from b277895 to bf13319 Compare June 30, 2026 06:39
hebaalazzeh mentioned this pull request Jun 30, 2026
Closed

hebaalazzeh commented Jun 30, 2026

Copy link
Copy Markdown
Contributor Author

/gemini

hebaalazzeh changed the title Implement Phase 1 Native PEP 0810 Lazy Loading chore: implement native PEP 0810 lazy loading Jun 30, 2026
ohmayr marked this pull request as ready for review June 30, 2026 19:08
ohmayr requested a review from a team as a code owner June 30, 2026 19:08
parthea changed the title chore: implement native PEP 0810 lazy loading feat: implement native PEP 0810 lazy loading Jun 30, 2026
parthea assigned ohmayr and unassigned parthea Jun 30, 2026
parthea requested a review from ohmayr June 30, 2026 19:50
hebaalazzeh merged commit 8a1270c into main Jun 30, 2026
96 checks passed
hebaalazzeh deleted the prototype-phase1-pep810 branch June 30, 2026 19:59
release-please Bot mentioned this pull request Jun 30, 2026
Merged
quirogas pushed a commit that referenced this pull request Jul 7, 2026
chore: release main (#17600)
fc6b861 
🤖 I have created a release *beep* *boop*
---


<details><summary>db-dtypes: 1.7.1</summary>

##
[1.7.1](db-dtypes-v1.7.0...db-dtypes-v1.7.1)
(2026-07-07)


### Bug Fixes

* avoid deprecated unitless operations for NumPy 2.5 compatibility
([#17589](#17589))
([d0b2abc](d0b2abc))
</details>

<details><summary>gapic-generator: 1.37.0</summary>

##
[1.37.0](gapic-generator-v1.36.0...gapic-generator-v1.37.0)
(2026-07-07)


### Features

* implement native PEP 0810 lazy loading
([#17591](#17591))
([8a1270c](8a1270c))


### Bug Fixes

* **deps:** bump google-api-core to 2.25.0
([#17599](#17599))
([8b359e2](8b359e2))
* **tests:** add --cov-append to gapic-generator and proto-plus to
preserve monorepo coverage
([#17603](#17603))
([2ddcf4d](2ddcf4d))
</details>

<details><summary>google-auth: 2.55.2</summary>

##
[2.55.2](google-auth-v2.55.1...google-auth-v2.55.2)
(2026-07-07)


### Bug Fixes

* **auth:** Agentic Identites mTLS gaps fix _is_mtls and SslCredentials.
([#17387](#17387))
([7bfa41a](7bfa41a))
* **auth:** align mTLS discovery and enforce fail-fast transport
configuration.
([#17470](#17470))
([f492d3d](f492d3d))
* **auth:** handle PermissionError on workload certificates to avoid
startup hang and crash
([#17568](#17568))
([f538ad8](f538ad8))
</details>

<details><summary>google-cloud-agentregistry: 0.1.0</summary>

## 0.1.0 (2026-07-07)


### Features

* **google/cloud/agentregistry/v1:** add google-cloud-agentregistry
([#17565](#17565))
([f479800](f479800))
</details>

<details><summary>google-cloud-biglake-hive: 0.3.1</summary>

##
[0.3.1](google-cloud-biglake-hive-v0.3.0...google-cloud-biglake-hive-v0.3.1)
(2026-07-07)


### Features

* update googleapis and regenerate
([#17635](#17635))
([9638879](9638879))
</details>

<details><summary>google-cloud-bigquery: 3.42.2</summary>

##
[3.42.2](google-cloud-bigquery-v3.42.1...google-cloud-bigquery-v3.42.2)
(2026-07-07)


### Bug Fixes

* **bigquery:** avoid SSLError retry loop
([#17489](#17489))
([8248d8e](8248d8e))
* include amended user agent in read client
([#17592](#17592))
([c43caee](c43caee))
</details>

<details><summary>google-cloud-binary-authorization: 1.18.0</summary>

##
[1.18.0](google-cloud-binary-authorization-v1.17.0...google-cloud-binary-authorization-v1.18.0)
(2026-07-07)


### Features

* update googleapis and regenerate
([#17635](#17635))
([9638879](9638879))
</details>

<details><summary>google-cloud-chronicle: 0.6.2</summary>

##
[0.6.2](google-cloud-chronicle-v0.6.1...google-cloud-chronicle-v0.6.2)
(2026-07-07)


### Features

* update googleapis and regenerate
([#17635](#17635))
([9638879](9638879))
</details>

<details><summary>google-cloud-dataform: 0.11.2</summary>

##
[0.11.2](google-cloud-dataform-v0.11.1...google-cloud-dataform-v0.11.2)
(2026-07-07)


### Features

* update googleapis and regenerate
([#17635](#17635))
([9638879](9638879))
</details>

<details><summary>google-cloud-dataproc: 5.30.0</summary>

##
[5.30.0](google-cloud-dataproc-v5.29.0...google-cloud-dataproc-v5.30.0)
(2026-07-07)


### Features

* update googleapis and regenerate
([#17635](#17635))
([9638879](9638879))
</details>

<details><summary>google-cloud-datastore: 2.26.0</summary>

##
[2.26.0](google-cloud-datastore-v2.25.0...google-cloud-datastore-v2.26.0)
(2026-07-07)


### Features

* update googleapis and regenerate
([#17635](#17635))
([9638879](9638879))
</details>

<details><summary>google-cloud-dialogflow: 2.50.0</summary>

##
[2.50.0](google-cloud-dialogflow-v2.49.0...google-cloud-dialogflow-v2.50.0)
(2026-07-07)


### Features

* update googleapis and regenerate
([#17635](#17635))
([9638879](9638879))
</details>

<details><summary>google-cloud-kms: 3.15.0</summary>

##
[3.15.0](google-cloud-kms-v3.14.0...google-cloud-kms-v3.15.0)
(2026-07-07)


### Features

* update googleapis and regenerate
([#17635](#17635))
([9638879](9638879))
</details>

<details><summary>google-cloud-logging: 3.16.1</summary>

##
[3.16.1](google-cloud-logging-v3.16.0...google-cloud-logging-v3.16.1)
(2026-07-07)


### Documentation

* **logging:** fix StructuredLogHandler docstring parameter name
([#17625](#17625))
([32862f0](32862f0)),
closes
[#17604](#17604)
</details>

<details><summary>google-cloud-modelarmor: 0.7.1</summary>

##
[0.7.1](google-cloud-modelarmor-v0.7.0...google-cloud-modelarmor-v0.7.1)
(2026-07-07)


### Features

* update googleapis and regenerate
([#17635](#17635))
([9638879](9638879))
</details>

<details><summary>google-cloud-network-security: 0.13.3</summary>

##
[0.13.3](google-cloud-network-security-v0.13.2...google-cloud-network-security-v0.13.3)
(2026-07-07)


### Features

* update googleapis and regenerate
([#17635](#17635))
([9638879](9638879))
</details>

<details><summary>google-cloud-saasplatform-saasservicemgmt:
0.7.1</summary>

##
[0.7.1](google-cloud-saasplatform-saasservicemgmt-v0.7.0...google-cloud-saasplatform-saasservicemgmt-v0.7.1)
(2026-07-07)


### Features

* update googleapis and regenerate
([#17635](#17635))
([9638879](9638879))
</details>

<details><summary>google-cloud-securesourcemanager: 0.6.1</summary>

##
[0.6.1](google-cloud-securesourcemanager-v0.6.0...google-cloud-securesourcemanager-v0.6.1)
(2026-07-07)


### Features

* update googleapis and regenerate
([#17635](#17635))
([9638879](9638879))
</details>

<details><summary>google-cloud-storage: 3.12.1</summary>

##
[3.12.1](google-cloud-storage-v3.12.0...google-cloud-storage-v3.12.1)
(2026-07-07)


### Bug Fixes

* **storage:** log occasional (1 in 5 million) additional bytes received
from GCS in read path
([#17423](#17423))
([335c12f](335c12f))
</details>

<details><summary>google-cloud-support: 0.5.1</summary>

##
[0.5.1](google-cloud-support-v0.5.0...google-cloud-support-v0.5.1)
(2026-07-07)


### Features

* update googleapis and regenerate
([#17635](#17635))
([9638879](9638879))
</details>

<details><summary>proto-plus: 1.28.1</summary>

##
[1.28.1](proto-plus-v1.28.0...proto-plus-v1.28.1)
(2026-07-07)


### Bug Fixes

* **tests:** add --cov-append to gapic-generator and proto-plus to
preserve monorepo coverage
([#17603](#17603))
([2ddcf4d](2ddcf4d))
</details>

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

---------

Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>
This was referenced Jul 8, 2026
Merged
Closed
hebaalazzeh added a commit that referenced this pull request Jul 15, 2026
feat: lazy imports gapic v1 (#17673)
84fa2bc 
## Description
This PR initiates the rollout of our PEP 0810 lazy-loading architecture
to google-api-core, starting with the `gapic_v1` module.

By applying Python 3.15's native explicit lazy imports, we defer the
eager execution of inner modules (like `method.py` and `config.py`)
which recursively pull in massive third-party C-extensions like
`grpcio`. This acts as the first step in addressing the high
initialization latency and peak memory footprints we're seeing on
Serverless cold-starts.

Older Python runtimes (3.14 and below) safely ignore the
`__lazy_modules__` set and fall back to standard eager execution,
meaning this introduces zero backwards compatibility risk.

*(Note: We use fully-qualified, hardcoded module strings rather than
dynamic `__name__` injection, and provide explicit type annotations
(`Set[str]`), to ensure static analysis tools and type checkers can
safely infer the proxies without complaints).*

## Related Documents
* **Design Doc:** go/sdk:api-core-lazy-loading
* **Original GAPIC Generator Implementation PR:** #17591
hebaalazzeh mentioned this pull request Jul 15, 2026
Merged
hebaalazzeh added a commit that referenced this pull request Jul 15, 2026
feat: lazy imports gapic v1 (#17673)
63caee8 
## Description
This PR initiates the rollout of our PEP 0810 lazy-loading architecture
to google-api-core, starting with the `gapic_v1` module.

By applying Python 3.15's native explicit lazy imports, we defer the
eager execution of inner modules (like `method.py` and `config.py`)
which recursively pull in massive third-party C-extensions like
`grpcio`. This acts as the first step in addressing the high
initialization latency and peak memory footprints we're seeing on
Serverless cold-starts.

Older Python runtimes (3.14 and below) safely ignore the
`__lazy_modules__` set and fall back to standard eager execution,
meaning this introduces zero backwards compatibility risk.

*(Note: We use fully-qualified, hardcoded module strings rather than
dynamic `__name__` injection, and provide explicit type annotations
(`Set[str]`), to ensure static analysis tools and type checkers can
safely infer the proxies without complaints).*

## Related Documents
* **Design Doc:** go/sdk:api-core-lazy-loading
* **Original GAPIC Generator Implementation PR:** #17591
hebaalazzeh added a commit that referenced this pull request Jul 15, 2026
feat: implement PEP 0810 lazy loading in operations_v1 (#17724)
22c5304 
This PR implements PEP 0810 explicit lazy imports in `google-api-core`'s
`operations_v1` package.

On Python 3.15+, this defers loading of long-running operations clients
and transports to avoid eagerly importing heavy dependencies like
`grpcio` and `cryptography` during import time. This falls back safely
to eager execution on Python 3.14 and below with zero
backwards-compatibility risk.

### Related Links
- **Design Doc**: go/sdk:api-core-lazy-loading
- **GAPIC Implementation PR**: #17591

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Anthonios Partheniou <partheniou@google.com>
hebaalazzeh added a commit that referenced this pull request Aug 10, 2026
feat(core): implement PEP 0810 explicit lazy imports in google-cloud-…
9935b7a 
…core

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
- GAPIC Implementation PR: #17591
- google-api-core gapic_v1 PR: #17673
- google-api-core operations_v1 PR: #17724
- google-auth transport PR: #17679
hebaalazzeh added a commit that referenced this pull request Aug 10, 2026
feat(core): implement PEP 0810 explicit lazy imports in google-cloud-…
3bd0d3d 
…core

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
- GAPIC Implementation PR: #17591
- google-api-core gapic_v1 PR: #17673
- google-api-core operations_v1 PR: #17724
- google-auth transport PR: #17679
hebaalazzeh added a commit that referenced this pull request Aug 10, 2026
feat(core): implement PEP 0810 explicit lazy imports in google-cloud-…
88be17b 
…core

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
- GAPIC Implementation PR: #17591
- google-api-core gapic_v1 PR: #17673
- google-api-core operations_v1 PR: #17724
- google-auth transport PR: #17679
hebaalazzeh added a commit that referenced this pull request Aug 10, 2026
feat(core): implement PEP 0810 explicit lazy imports in google-cloud-…
8f73f3b 
…core

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
- GAPIC Implementation PR: #17591
- google-api-core gapic_v1 PR: #17673
- google-api-core operations_v1 PR: #17724
- google-auth transport PR: #17679
hebaalazzeh added a commit that referenced this pull request Aug 10, 2026
feat(core): implement PEP 0810 explicit lazy imports in google-cloud-…
b7f4f01 
…core

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
- GAPIC Implementation PR: #17591
- google-api-core gapic_v1 PR: #17673
- google-api-core operations_v1 PR: #17724
- google-auth transport PR: #17679
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

parthea parthea approved these changes
ohmayr ohmayr approved these changes
+1 more reviewer
gemini-code-assist[bot] gemini-code-assist[bot] left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

ohmayr

hebaalazzeh

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

Back | FazBrowse Home | New Git URL