Improve import startup with lazy top-level exports

[fede-kamel]

Summary

This PR addresses import-time startup regression tracked in #2819 by making heavy top-level exports lazy.

Key changes:

• Lazily resolve top-level exports in openai.__init__ for:
  • AzureOpenAI
  • AsyncAzureOpenAI
  • pydantic_function_tool
  • AssistantEventHandler
  • AsyncAssistantEventHandler
• Add an eager-import debug/CI mode: OPENAI_EAGER_IMPORT=1
  • In eager mode, all lazy exports are resolved at import time to catch deferred-import breakages.
• Lazily create the internal Azure module-client subclass only when Azure mode is actually used.
• Add an import benchmark helper script: scripts/bench_import.py.
• Add tests for lazy/eager import behavior:
  • tests/test_import_surface.py
  • tests/lib/test_import_surface_live.py (live-gated)

Why this relates to #2819

Issue #2819 reports that import openai is too slow and that eager loading of type-heavy/internal surfaces is a major contributor. This PR reduces startup cost in the default path by moving expensive imports behind first-use access while preserving API compatibility.

Testing done

Unit / behavior tests

• PYTHONPATH=src python3 -m pytest tests/test_import_surface.py -q -o addopts='' -> passed
• PYTHONPATH=src python3 -m pytest tests/test_module_client.py -q -o addopts='' -> passed

Live API-key integration test

• OPENAI_LIVE=1 PYTHONPATH=src OPENAI_API_KEY=... python3 -m pytest tests/lib/test_import_surface_live.py -q -o addopts='' -> passed
• This validates eager-mode import + real API request flow (client.models.list()).

Performance benchmarks

Using scripts/bench_import.py:

• WSL/Linux run (patched branch):
  • lazy avg: 0.1533s
  • eager avg (OPENAI_EAGER_IMPORT=1): 0.2601s
  • delta: +0.1068s (+69.7%)
• Native Windows run from patched branch path:
  • lazy avg: 0.7019s
  • eager avg: 2.9429s
  • delta: +2.2410s (+319.3%)

Interpretation: eager mode is intentionally slower, and the default lazy path materially reduces startup work compared with forced eager loading.

Notes

• This PR keeps behavior-focused tests deterministic and keeps live testing opt-in via OPENAI_LIVE=1 and OPENAI_API_KEY.
• Existing unrelated local worktree changes were excluded from this PR.

[fede-kamel]

Validation summary for #2819:

1. Unit/behavior tests (rebased branch)

• PYTHONPATH=src python3 -m pytest tests/test_import_surface.py -q -o addopts='' -> 2 passed
• PYTHONPATH=src python3 -m pytest tests/test_module_client.py -q -o addopts='' -> 12 passed

2. Live API-key integration test

• OPENAI_LIVE=1 PYTHONPATH=src OPENAI_API_KEY=... python3 -m pytest tests/lib/test_import_surface_live.py -q -o addopts='' -> 1 passed
• This test validates eager-mode import + a real API request (client.models.list()).

3. Performance measurements

• WSL/Linux (patched branch):
  • lazy avg: 0.1533s
  • eager avg (OPENAI_EAGER_IMPORT=1): 0.2601s
  • delta: +0.1068s (+69.7%)
• Native Windows (patched branch path):
  • lazy avg: 0.7019s
  • eager avg: 2.9429s
  • delta: +2.2410s (+319.3%)

Interpretation: default lazy mode reduces import startup work significantly; eager mode remains available for CI/dev verification.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2bd0b97246

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[g0t4]

Two things, about the env var for eager load

• The point of CI is to reproduce the user experience and validate it works. Having an env var change something fundamental with imports will lead to a nightmare of bugs just in CI and then missed bugs in reality.
• Second, if CI needs eager imports for a special set of tests, why not have a script or pytest startup function that performs the imports? That way it is explicit what CI is testing.

I think it's great you're working on a fix for this btw... thank you

[fede-kamel]

Took this feedback and removed the runtime eager-import env var path from openai.__init__.

The branch now keeps lazy imports as the only product behavior and makes the coverage explicit in tests instead:

• unit tests explicitly resolve the lazy exports
• the live test explicitly resolves the lazy exports and performs a real request
• openai.lib re-exports were also made lazy so import openai stays on the lazy path

Validated locally with:

• PYTHONPATH=src .venv/bin/python -m pytest tests/test_import_surface.py tests/test_lazy_types_import.py -q -o addopts=''
• OPENAI_LIVE=1 PYTHONPATH=src .venv/bin/python -m pytest tests/lib/test_import_surface_live.py -q -o addopts=''