uhi

What it is and what it does

UHI is a standards library that defines how histogram objects should behave across different scientific Python libraries. It provides type protocols—especially PlottableHistogram—that libraries like boost-histogram, hist, and uproot conform to, enabling code to work with histograms from multiple sources without knowing their concrete type. The package includes runtime-checkable protocols so you can use isinstance() to verify conformance, plus a utility to convert NumPy-style histogram tuples (counts, edges) into objects that match the standard interface.

The package is designed primarily as a dependency for library authors and type checkers rather than end-user code, though it does expose a few useful runtime tools. It depends only on numpy and typing-extensions, making it lightweight to include in projects that need histogram interoperability. The active maintenance and support for current Python versions (3.10+) ensures it stays aligned with modern scientific Python practices.

Use it for:

• Type-check histogram objects from different libraries to ensure they conform to a common interface before passing them to plotting functions.
• Adapt NumPy histogram tuples (counts, edges) into standardized PlottableHistogram objects for compatibility with libraries expecting the protocol.
• Document and enforce histogram indexing conventions across a multi-library scientific computing project.
• Support library development by providing reference protocols that new histogram implementations can conform to.
• Enable runtime verification that a histogram object supports the expected methods and attributes without tight coupling to a specific library.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

UHI defines and documents a standard interface for histogram objects across libraries, providing type protocols for runtime checking and tools to adapt NumPy-style histogram tuples into a common format.

Yes, if you are building libraries that work with histograms from multiple sources or need to enforce histogram interface standards. Install as a type-checking or testing dependency in projects that depend on histogram libraries like boost-histogram or hist. Not necessary for end-user code that only uses a single histogram library, but adds minimal friction and provides real value in interoperability scenarios.

Install

uhi on PyPI

pip install uhi

uv add uhi

poetry add uhi

Installing uhi

Before you install

Low install friction with only numpy and typing-extensions as runtime dependencies. Actively maintained with recent releases; primarily designed as a type-checking and testing dependency for other libraries rather than a direct runtime requirement.

License in practice

BSD-3-Clause is permissive and places no significant restrictions on use or redistribution in commercial or open-source contexts.

Quickstart

pip install uhi

import uhi.typing.plotting
from uhi.numpy_plottable import ensure_plottable_histogram

# Check if an object conforms to PlottableHistogram protocol
isinstance(histogram_obj, uhi.typing.plotting.PlottableHistogram)

# Adapt NumPy-style histogram tuple to PlottableHistogram
plottable = ensure_plottable_histogram(counts, edges)

Requires Python 3.10 or later.

Verify before relying

• Whether the runtime-usable components (numpy_plottable adapter, protocol runtime checking) are sufficient for direct use or if this is primarily a transitive dependency.
• Performance characteristics when using isinstance() checks against PlottableHistogram at runtime in tight loops.

Package facts

Evidence: uhi-1.1.1-py3-none-any.whl

Tags

More Scientific/Engineering packages