Skip to content

docs: fix conflicting lazy heavy import guidance in STYLEGUIDE.md (#759) - #920

Open
chethanuk wants to merge 1 commit into
NVIDIA-NeMo:mainfrom
chethanuk:fix/issue-759-ship
Open

docs: fix conflicting lazy heavy import guidance in STYLEGUIDE.md (#759)#920
chethanuk wants to merge 1 commit into
NVIDIA-NeMo:mainfrom
chethanuk:fix/issue-759-ship

Conversation

@chethanuk

Copy link
Copy Markdown

📋 Summary

STYLEGUIDE.md and lazy_heavy_imports.py recommend opposite import forms for lazy-loading
heavy dependencies. from data_designer.lazy_heavy_imports import pd, np is an attribute read
against the module's PEP-562 __getattr__ facade, so it fires while the consuming module is
still importing and pandas loads eagerly — the facade buys nothing. Only
import data_designer.lazy_heavy_imports as lazy + lazy.pd stays lazy, which is what the
module's own docstring already requires and what test_lazy_imports.py already asserts. This
aligns the guide to the form that actually works.

🔗 Related Issue

Fixes #759

🔄 Changes

  • STYLEGUIDE.md: rewrite the four blocks that taught the from ... import pd, np form to use
    the import ... as lazy / lazy.pd form instead. Each example gains a call site and
    from __future__ import annotations so the snippets are runnable modules rather than
    illustrations that raise NameError if copy-pasted.
  • scripts/benchmarks/benchmark_engine_v2.py: convert the tree's only remaining user of the
    banned form to the alias pattern.
  • packages/data-designer/tests/test_lazy_imports.py: add
    test_scripts_avoid_from_lazy_heavy_imports_pattern, extending the existing
    packages/*/src/** guard to scripts/** — the gap that let the benchmark script drift.

🧪 Testing

  • make testtest_lazy_imports.py: 1 failed, 4 passed before the fix (fails on
    benchmark_engine_v2.py); 5 passed after
  • make lint / make format-check — all checks passed
  • make test-interface — 1119 passed, 1 skipped, 1 pre-existing failure
    (test_import_performance, an environmental make perf-import timeout under machine load,
    reproduced identically on main with none of this branch's changes applied)
  • Benchmark script re-run at a fixed seed, before and after conversion: identical
    dataset_hash

✅ Checklist

  • Follows commit message conventions
  • Commits are signed off (DCO) — squashed to one commit, git commit -s
  • Architecture docs updated — N/A (docs/test/script only, no architecture change)

Note: issue #759 does not currently carry the triaged label; the upstream
linked-issue workflow may gate on that independent of this PR.

Fixes #759

STYLEGUIDE.md recommended `from data_designer.lazy_heavy_imports import pd, np`,
which is an attribute read against the PEP-562 facade and therefore imports
pandas eagerly while the consuming module is still importing. Only
`import data_designer.lazy_heavy_imports as lazy` + `lazy.pd` stays lazy,
which is what lazy_heavy_imports.py's docstring already requires and what
test_lazy_imports.py already asserts.

Rewrites the four STYLEGUIDE.md blocks to the alias form, gives each snippet a
call site so the TYPE_CHECKING imports are motivated, and adds
`from __future__ import annotations` so the annotations resolve at def-time.
Converts scripts/benchmarks/benchmark_engine_v2.py, the tree's only remaining
user of the banned form.

Also extends test_lazy_imports.py's guard to cover scripts/, since it
previously only globbed packages/*/src and missed
scripts/benchmarks/benchmark_engine_v2.py's banned from-import form.

Signed-off-by: ChethanUK <chethanuk@outlook.com>
@chethanuk
chethanuk requested a review from a team as a code owner September 5, 2026 05:25
@github-actions

github-actions Bot commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

Linked Issue Check

Issue #759 has not been triaged yet. A maintainer needs to review
the issue and add the triaged label for this check to pass.

You can continue working on the PR in the meantime. The check will
re-run automatically once the issue is triaged.

@github-actions

github-actions Bot commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

Thank you for your submission! We ask that you sign our Developer Certificate of Origin before we can accept your contribution. You can sign the DCO by adding a comment below using this text:


I have read the DCO document and I hereby sign the DCO.


You can retrigger this bot by commenting recheck in this Pull Request. Posted by the DCO Assistant Lite bot.

@greptile-apps

greptile-apps Bot commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This PR corrects the lazy-heavy-import guidance and aligns the remaining benchmark usage with the genuinely deferred import pattern.

  • Rewrites STYLEGUIDE examples to use module-level lazy access with runnable, annotation-safe call sites.
  • Converts the benchmark’s NumPy and pandas accesses to the lazy facade.
  • Adds a regression test preventing eager facade attribute imports under scripts/**.

Confidence Score: 5/5

The PR appears safe to merge, with the documentation, benchmark conversion, and regression test consistently enforcing the intended lazy-import behavior.

The lazy facade returns and caches the real dependency modules, all converted accesses are behaviorally equivalent, and the new test correctly detects the prohibited import pattern in the intended scripts tree.

Important Files Changed

Filename Overview
STYLEGUIDE.md Replaces eager from-import examples with accurate lazy module-alias guidance and concrete call sites.
packages/data-designer/tests/test_lazy_imports.py Adds a correctly rooted recursive guard against eager lazy-facade imports in Python scripts.
scripts/benchmarks/benchmark_engine_v2.py Preserves benchmark behavior while deferring NumPy and pandas imports until their first runtime use.

Reviews (1): Last reviewed commit: "docs: teach the lazy import form that is..." | Re-trigger Greptile

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Conflicting guidance on lazy heavy imports

1 participant