ENH: Replace custom LazyITKModule with native PEP 562 lazy loading

[thewtex]

The custom LazyITKModule(types.ModuleType) subclass that powered
ITK's Python lazy-loading layer is replaced with the standard-library
PEP 562 (Python 3.7+) module-level __getattr__ / __dir__ protocol.
The same observable contract is preserved: lazy first-touch resolution,
thread-safe first-load via a single recursive lock, factory-loading
hook gated on itkConfig.DefaultFactoryLoading, PEP 366 __package__,
and pickle / cloudpickle round-trip identity through sys.modules
registration.

Motivation:

• The legacy LazyITKModule.__getattribute__ intercepted every
  attribute read just to check a sentinel; PEP 562 only fires on
  miss, so steady-state reads now hit the standard module fast path
  for free.
• The custom ITKLazyLoadLock combined threading.RLock and
  multiprocessing.RLock. Constructing the multiprocessing half pinned
  the multiprocessing start method at import itk time, breaking
  downstream callers that wanted multiprocessing.set_start_method(...)
  after import. The new implementation uses only threading.RLock;
  process boundary isolation already handles the cross-process case
  (each child process re-runs itk/__init__.py against its own
  sys.modules).
• Custom pickle reconstructor (_lazy_itk_module_reconstructor),
  __getstate__, __setstate__, and the eager-mode dispatch branch
  are deleted; standard module pickling and sys.modules['itk.<Mod>']
  registration cover the round-trip with a single 3-line
  __reduce_ex__ shim per synthetic submodule (vanilla
  pickle.dumps(types.ModuleType(...)) raises on CPython 3.12+).

What changes:

• Wrapping/Generators/Python/itk/__init__.py rewritten with
  module-level __getattr__ / __dir__ (PEP 562) and a single
  threading.RLock. Reload-guard branch and eager-mode branch
  removed.
• New Wrapping/Generators/Python/itk/support/_lazy_submodule.py
  exports _make_itk_lazy_submodule(module_name, lazy_attributes, lazy_load_lock) returning a plain types.ModuleType carrying
  PEP 562 __getattr__ / __dir__ / __reduce_ex__.
• Wrapping/Generators/Python/itk/support/lazy.py deleted (181 lines:
  custom subclass, lock, reconstructor, sentinel).
• Wrapping/Generators/Python/Tests/nolazy.py deleted; the eager
  branch it exercised no longer exists.
• itkConfig.LazyLoading and the ITK_PYTHON_LAZYLOADING
  environment-variable reader removed from
  itkConfig.template.in.py. Lazy is now the single mode.
• Tests Tests/lazy.py, Tests/multiprocess_lazy_loading.py, and
  Modules/Filtering/ImageIntensity/wrapping/test/itkImageFilterNumPyInputsTest.py
  drop itkConfig.LazyLoading = ... overrides.
• Tests/lazy.py extended to cover PEP 562 __dir__ (visible
  before load), the factory-loading hook, and stdlib pickle
  round-trip on itk.ITKCommon.

Net diff: 10 files changed, +267 / −335 (net -68 lines).
Validated end-to-end with pixi run --as-is build-python and
pixi run --as-is ctest --test-dir build-python -R Python -E "PythonNoLazyModule" — 172/172 tests pass, including the
PythonLazyModule, PythonMultiprocessLazyLoad, and
PythonGILReleaseSafetyTest regression triplet.

Lazy-only is now the single mode: callers that previously set
itkConfig.LazyLoading = False should remove the assignment (it
will raise AttributeError).

[greptile-apps]

Greptile Summary

This PR replaces the legacy LazyITKModule(types.ModuleType) subclass with the standard PEP 562 module-level __getattr__/__dir__ protocol, removes the eager-loading branch and the ITKLazyLoadLock (which was inadvertently pinning the multiprocessing start method), and introduces per-submodule lazy namespaces via _make_itk_lazy_submodule. The observable contract — lazy first-touch, thread-safe via threading.RLock, factory-loading hook, __package__ PEP 366, and pickle round-trips — is preserved, while steady-state attribute reads now hit the standard module fast path instead of being intercepted by __getattribute__.

Confidence Score: 4/5

Safe to merge; only P2 findings (dead code and a documentation comment inaccuracy).

No P0 or P1 issues found. The double-check locking pattern is correct, thread-safety is preserved, pickle shims are sound, and all removed APIs are cleanly excised. Two P2 findings: an unreachable loaded_modules set in _lazy_submodule.py and a misleading comment in the migration guide.

Wrapping/Generators/Python/itk/support/_lazy_submodule.py (dead loaded_modules variable) and Documentation/docs/migration_guides/itk_6_migration_guide.md (incorrect comment in code example).

Important Files Changed

Filename	Overview
Wrapping/Generators/Python/itk/init.py	Rewritten with module-level PEP 562 getattr/dir, a single threading.RLock, and correct double-check locking; _initialize_module now builds the flat _lazy_attribute_to_module map; eager-mode and reload-guard branches removed.
Wrapping/Generators/Python/itk/support/_lazy_submodule.py	New file providing _make_itk_lazy_submodule; overall logic is sound but loaded_modules is dead code (written but never read).
Wrapping/Generators/Python/itk/support/lazy.py	Deleted (181 lines): LazyITKModule subclass, ITKLazyLoadLock, _lazy_itk_module_reconstructor, and not_loaded sentinel; all consumers updated.
Wrapping/Generators/Python/itkConfig.template.in.py	Removes LazyLoading bool and ITK_PYTHON_LAZYLOADING env-var reader; DefaultFactoryLoading is preserved unchanged.
Documentation/docs/migration_guides/itk_6_migration_guide.md	Adds a well-written migration section, but the inline comment '# this read now raises AttributeError' is incorrect for the two-line example shown (the preceding assignment prevents the error).
Wrapping/Generators/Python/Tests/lazy.py	Extended with PEP 562 dir assertions, factory-hook test, and stdlib pickle round-trip for itk.ITKCommon; itkConfig.LazyLoading override removed.
Wrapping/Generators/Python/Tests/nolazy.py	Deleted — the eager-mode branch it exercised no longer exists; corresponding PythonNoLazyModule CMake test also removed.
Wrapping/Generators/Python/Tests/multiprocess_lazy_loading.py	Drops itkConfig.LazyLoading = True override and updates comments; threading test logic is unchanged.
Modules/Filtering/ImageIntensity/wrapping/test/itkImageFilterNumPyInputsTest.py	Removes itkConfig.LazyLoading = False guard that is no longer meaningful.
Wrapping/Generators/Python/CMakeLists.txt	Updates support file list from support/lazy to support/_lazy_submodule.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant itk as "itk module __getattr__"
    participant Sub as "itk.ITKCommon __getattr__"
    participant Base as "itk.support.base"
    participant Lock as "threading.RLock"

    Caller->>itk: "itk.Image (first access)"
    itk->>Lock: "acquire()"
    itk->>Base: "itk_load_swig_module(ITKCommon, namespace)"
    Base-->>itk: "namespace populated"
    itk->>itk: "globals().update(namespace)"
    itk->>Lock: "release()"
    itk-->>Caller: "Image class"

    Caller->>itk: "itk.Image (subsequent access)"
    Note over itk: "Found in __dict__, __getattr__ skipped"
    itk-->>Caller: "Image class via fast path"

    Caller->>Sub: "itk.ITKCommon.Image (first access)"
    Sub->>Lock: "acquire() shared RLock"
    Sub->>Base: "itk_load_swig_module(ITKCommon, namespace)"
    Base-->>Sub: "namespace populated"
    Sub->>Sub: "m.__dict__.update(namespace)"
    Sub->>Lock: "release()"
    Sub-->>Caller: "Image class"

    Caller->>Sub: "pickle.dumps(itk.ITKCommon)"
    Sub-->>Caller: "(importlib.import_module, itk.ITKCommon)"
    Caller->>Sub: "pickle.loads resolves via sys.modules"
    Sub-->>Caller: "same itk.ITKCommon instance"

Loading

Comments Outside Diff (1)

1. Documentation/docs/migration_guides/itk_6_migration_guide.md, line 33-43 (link)

   Misleading AttributeError comment in migration guide

   The inline comment # this read now raises AttributeError is incorrect for the specific two-line sequence shown. Because the preceding itkConfig.LazyLoading = False assignment successfully sets the attribute on the module object (Python module attributes are mutable), the subsequent if itkConfig.LazyLoading: read returns False — it does not raise AttributeError. The AttributeError only arises when reading LazyLoading without having first written it (i.e., on a fresh import itkConfig with no prior assignment). The current example would mislead users who try to reproduce the error to confirm they need to migrate.

_{Reviews (1): Last reviewed commit: "DOC: Note itkConfig.LazyLoading removal ..." | Re-trigger Greptile}

[thewtex]

Addressed Greptile's two P2 findings in ca131c5:

1. Wrapping/Generators/Python/itk/support/_lazy_submodule.py — loaded_modules dead code. Removed both the loaded_modules: set[str] = set() declaration and the loaded_modules.add(target) call. Confirmed via grep that nothing reads it; the new __reduce_ex__ shim delegates to importlib.import_module rather than replaying loads through a set. PythonLazyModule and PythonMultiprocessLazyLoad pass post-removal.

2. Documentation/docs/migration_guides/itk_6_migration_guide.md — misleading AttributeError comment. Greptile is correct: in the original two-line example, the preceding itkConfig.LazyLoading = False assignment had set the attribute on the module object, so the subsequent read returned False rather than raising. Reworked the example into separately commented write and read patterns and clarified that the AttributeError only occurs on a fresh import itkConfig with no prior assignment.