Skip to content

perf(import): load tool submodules on demand and defer ingest metadata - #396

Draft
airmang wants to merge 1 commit into
mainfrom
fix/lazy-tools-import-386
Draft

airmang wants to merge 1 commit into
mainfrom
fix/lazy-tools-import-386

Conversation

@airmang

@airmang airmang commented Oct 2, 2026

Copy link
Copy Markdown
Owner

First HwpxDocument.to_bytes() loaded every tool module through hwpx.tools.__init__, including exporters, viewers, diff, and mail merge. Tool exports and the previously reachable submodules now resolve on first access through static imports; save loads only the package validator and its required document validator. The Markdown converter also imports importlib.metadata only when it looks up the distribution version.

Existing exports, __all__, dir(), star imports, object identities, and static types are preserved. A targeted module setter preserves the doc_diff function when Python attaches its same-named child, including direct-child-first imports. Save validation remains intact.

Fixes #386.

Validation

  • Full suite: 5769 passed, 19 skipped, 1 xfailed; coverage gate passed. Final import/diff rerun: 22 passed, including 12 new cold-process cases. Five import-cost checks failed before the change.
  • Ruff, mypy (120-file scope plus both changed modules), pyright, typing scope, product boundary, public hygiene, error census, capabilities verification, and size ratchet pass.
  • Rebuilt wheel installed in an isolated environment with only lxml: deferred imports, all exports, doc_diff import ordering/function replacement, version lookup, and save/reopen pass with warnings treated as errors.
  • Three externally authored government documents (tests/fixtures/m3_gongmun_gold/NOTICE.md): all six unchanged/edited save-reopen cases pass, with every saved ZIP member byte-identical to main for the same operation.

Local measurements

11 interleaved fresh isolated processes per tree, identical Python 3.13 interpreter/dependencies, bytecode warmed once; medians:

main change
import hwpx 59.0 ms 58.0 ms
First to_bytes() 21.9 ms 15.8 ms
Tool modules after first save (including the package) 12 3
importlib.metadata after plain import loaded deferred

The hwpx-module import bound remains 97. Timings are observations on this machine.

This branch has not been deployed

No deployments
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.

Import cost: load hwpx.tools submodules on demand, defer importlib.metadata in ingest

1 participant