Skip to content

feat(handlers): add built-in double-click plot handlers for common types - #248

Merged
matt-pharr merged 6 commits into
developfrom
standard_handlers
May 18, 2026
Merged

feat(handlers): add built-in double-click plot handlers for common types#248
matt-pharr merged 6 commits into
developfrom
standard_handlers

Conversation

@matt-pharr

@matt-pharr matt-pharr commented May 12, 2026

Copy link
Copy Markdown
Owner

Summary

Adds built-in double-click plot handlers so that double-clicking a tree node
whose value is a common scientific type opens a matplotlib plot.

Plot handlers (pdv/default_handlers.py)

  • Default handlers for np.ndarray, pd.Series, pd.DataFrame, and xr.DataArray,
    registered during kernel bootstrap (register_defaults()), overridable by users.
  • Each handler draws onto an explicit fig, ax (no plt.gca() ambiguity) and titles
    the axes with the tree path.
  • Per-type behavior: np.ndarray 1D → line, 2D → imshow + colorbar, 0D/>2D → notice;
    pd.Series/pd.DataFrame.plot(); xr.DataArray.plot() (1D line / 2D
    pcolormesh / >2D histogram).
  • Values that cannot actually be plotted (non-numeric Series/DataFrame,
    object-dtype arrays, …) close the half-built figure and print a [PDV] notice
    instead of raising — a raised exception would reach the renderer as an opaque
    internal.error. The final plt.show() is likewise guarded, so a
    backend-level failure degrades to a notice rather than escaping into
    dispatch_handler.

matplotlib & numpy dependencies

  • matplotlib is now a declared core dependency of pdv-python (>=3.10.5).
    The floor is set by the dependency sweep: matplotlib 3.10.0 has a
    Path.__deepcopy__ infinite-recursion bug that breaks pandas.plot(), and
    3.10.5 is the first release with Python 3.14 wheels.
  • numpy (>=2.2) is now also a core dependency. matplotlib already pulls
    numpy in transitively, and checksum.py / serialization.py import it
    directly — declaring it explicitly guarantees the >=2.2 floor the PDV code
    relies on instead of whatever matplotlib's transitive resolution would pick.
    The data optional extra is consequently now pandas-only; existing
    pdv-python[data] installs are unaffected since numpy still arrives via core.

xarray checksum support (pdv/checksum.py)

  • tree_checksum() now content-hashes xr.DataArray and xr.Dataset nodes
    (KIND_DATAARRAY / KIND_DATASET) instead of falling back to repr(): dims,
    dtype, shape, raw values, coords, and attrs are all fed into the digest. Shared
    Dataset coords are hashed once rather than once per data_var.
  • datetime64 / timedelta64 values (e.g. xarray time coordinates) take the fast
    buffer-protocol path alongside the plain numeric dtypes, rather than the slow
    repr(tolist()) fallback.

Test plan

  • pytest pdv-python/tests/ — 482 passed, 2 skipped.
  • pdv-python/scripts/sweep-deps.shall green (19/19 cells, exit 0:
    Python 3.10–3.14 × extras combos × highest/lowest-direct resolution; install +
    pytest pass in every cell). Re-run after the numpy core-dependency change — the
    lowest-direct cells now floor numpy at 2.2 as a direct dependency.
  • New tests cover the graceful-notice path for non-numeric inputs, 2-D title placement,
    the xr.DataArray histogram fallback, and suppression of the overwrite warning on
    re-registration.

- Implemented default handlers for np.ndarray, pd.Series, pd.DataFrame, and xr.DataArray.
- Handlers register during kernel bootstrap and can be overridden by users.
- Added tests to ensure handlers function correctly and handle edge cases.
- Updated double-click plot handlers to use `ax` for plotting instead of `plt`.
- Introduced `_plot_or_notice` function to handle plotting and error messaging.
- Added support for non-numeric `pd.Series` and object-dtype arrays to print notices instead of raising errors.
- Updated tests to verify behavior for non-numeric data and ensure proper notice printing.
- Added `matplotlib` as a required dependency in `pyproject.toml`.
…ort datetime types and improve error handling
@matt-pharr
matt-pharr merged commit 0862fd8 into develop May 18, 2026
12 checks passed
@matt-pharr
matt-pharr deleted the standard_handlers branch May 18, 2026 22:43
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.

1 participant