Lazy-load top-level imports and defer setup

[cvanelteren]

This PR rewires ultraplot’s import path to lazy‑load modules/registries and defer setup/registration work until first access, moves docstring snippet setup into ultraplot.internals.docstring with lazy snippet resolution, and defers optional dependency imports (IPython/pyplot/cartopy/basemap) while preserving the public API.

Import time report (python -X importtime -c "import ultraplot", Python 3.13.11):

• Logs: import_before_lazy.log, import_after_lazy.log
• Total before: 838.4 ms
• Total after: 12.2 ms
• Delta: -826.2 ms (~98.5% reduction)

Top ultraplot modules (before):

  838.4 ms | 49.4 ms | ultraplot
  408.8 ms |  0.6 ms | ultraplot.internals
  289.4 ms |  7.7 ms | ultraplot.config
  209.5 ms |  0.4 ms | ultraplot.internals.docstring
   51.3 ms |  0.6 ms | ultraplot.axes
   29.9 ms | 14.6 ms | ultraplot.axes.cartesian
   15.0 ms | 14.8 ms | ultraplot.axes.plot
    8.6 ms |  6.2 ms | ultraplot.axes.base
    6.7 ms |  6.5 ms | ultraplot.axes.geo
    5.8 ms |  5.8 ms | ultraplot.scale
    3.7 ms |  3.7 ms | ultraplot.figure
    3.4 ms |  3.4 ms | ultraplot.axes.polar

Top external modules (before):

  281.7 ms |  0.3 ms | IPython
  211.0 ms |  2.1 ms | IPython.terminal.embed
  158.4 ms |  0.3 ms | matplotlib.axes
  126.9 ms |  2.3 ms | IPython.terminal.interactiveshell
  118.3 ms |  5.2 ms | matplotlib.axes._base
  114.9 ms |  7.4 ms | matplotlib
   95.1 ms |  6.5 ms | matplotlib.offsetbox
   69.8 ms |  1.1 ms | IPython.core.application
   64.4 ms |  0.7 ms | IPython.terminal.debugger
   60.5 ms |  1.6 ms | numpy
   60.5 ms |  1.0 ms | matplotlib.rcsetup
   58.9 ms |  4.8 ms | IPython.core.completer

Top ultraplot modules (after):

   12.2 ms | 0.2 ms | ultraplot
    0.2 ms | 0.2 ms | ultraplot._version

Top external modules (after):

    8.2 ms | 1.1 ms | ast
    5.7 ms | 0.5 ms | re
    5.3 ms | 1.6 ms | site
    3.6 ms | 1.2 ms | enum
    3.5 ms | 0.2 ms | pathlib
    2.5 ms | 0.5 ms | functools
    1.9 ms | 1.0 ms | collections
    1.8 ms | 0.6 ms | pathlib._local
    1.6 ms | 0.4 ms | os
    1.4 ms | 0.5 ms | pathlib._abc
    1.4 ms | 0.3 ms | re._compiler
    1.3 ms | 0.5 ms | encodings

Closes #395

[cvanelteren]

This change set reworks ultraplot’s import path to be lazy by default: ultraplot/__init__.py no longer star‑imports everything up front, instead mapping attributes to their modules via __all__ and deferring setup/registration until first access, while still exposing registry classes and optional dependencies (pyplot, cartopy, basemap, and legend) on demand and guarding pytest_plugins. Internals now avoid eager submodule imports and only pull in rcsetup or matplotlib rcParams when needed, and the warnings alias was reverted back to the canonical warnings name. Docstring snippet setup was moved into ultraplot.internals.docstring with a lazy resolver to import modules that register missing snippets, and matplotlib imports inside _concatenate_inherited are delayed. config_inline_backend now imports IPython lazily. Net effect: import time drops from ~838 ms to ~12 ms on my machine while keeping API behavior intact; targeted tests pass, and the full suite progressed without failures before timeout.

[codecov]

Codecov Report

❌ Patch coverage is 84.67153% with 63 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
ultraplot/_lazy.py	82.69%	12 Missing and 15 partials ⚠️
ultraplot/__init__.py	78.94%	17 Missing and 7 partials ⚠️
ultraplot/tests/test_imports.py	92.00%	4 Missing and 2 partials ⚠️
ultraplot/config.py	60.00%	2 Missing ⚠️
ultraplot/internals/__init__.py	91.30%	1 Missing and 1 partial ⚠️
ultraplot/internals/docstring.py	92.59%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[cvanelteren]

In my effors I made the situation worse -- putting this to draft temporarily.

[beckermr]

This PR is very very complex. Is there a simpler way to do this?

[beckermr]

This documentation appears to be wrong.

[cvanelteren]

I am not sure I follow -- could you clarify what is wrong?

[beckermr]

Where is this method called?

[cvanelteren]

This method is called when a key is missing and attempts to lazy load it

[cvanelteren]

This PR is very very complex. Is there a simpler way to do this?

There are simpler ways to do this, but they’re either less future‑proof or they change the public API. UltraPlot currently pulls many internal modules into the top level, and those imports drag in heavy dependencies, which stack up in import time.

This PR keeps the API unchanged while making imports lazy. It (a) auto‑discovers new modules as the package evolves and (b) defers internal/external imports until they’re actually accessed, rather than at import time.

I did try to untangle the eager imports, but they’re too intertwined to cleanly separate. The alternatives are either (a) drop top‑level symbols, which would break user expectations (e.g., uplt.Colormap becomes uplt.colors.Colormap), or (b) accept the current import cost.

Proposed review route: start with ultraplot/_lazy.py and ultraplot/__init__.py for the core mechanism, then ultraplot/internals/__init__.py and ultraplot/internals/docstring.py for supporting lazy wiring, then ultraplot/internals/rcsetup.py and ultraplot/config.py for the toggle, and finish with ultraplot/tests/test_imports.py plus any docs or unrelated changes.