scihelpers

scihelpers is a small typed Python library for scientific-computing class helpers. It gives you dataclass-like models, enum-like constants, compact slots records, NumPy dtype inference, array validation, and lightweight physical quantities without making every project rebuild the same utilities.

The package is typed (py.typed), uses a src/ layout, and is designed to work well with strict IDE settings.

Features

• Exact NumPy dtype inference for scalars, lists, tuples, nested sequences, and arrays.
• Recursive type aliases for arbitrary-depth nested lists and array-like values.
• Dataclass-style decorators and base classes.
• Enum and IntEnum-style helpers with auto() and unique().
• Slots-based Struct records for compact scientific data containers.
• ArrayModel validation for array fields, dimensions, and matching lengths.
• Quantity values with units, conversions, comparisons, and arithmetic.

Installation

From a local checkout:

python -m pip install -e .

For development tools:

python -m pip install -e .[dev]

Quick Start

from scihelpers import ArrayLike, InferType, Quantity, array_model


class Reading(InferType, compact_repr=True):
    sensor_id: int
    samples: ArrayLike[float]


reading = Reading(256, [[1.5, 2.5], [3.5, 4.5]])
print(reading.sensor_id.dtype)  # uint16
print(reading.samples.dtype)    # float16
print(reading)


distance = Quantity([0, 50, 100], "cm", compact=True)
print(distance.to("m"))         # [0.0, 0.5, 1.0] m

Recursive Array Types

Use these public aliases when annotations should accept arbitrary nesting:

from scihelpers import ArrayLike, NestedList, NestedSequence

values: NestedList[float]
coordinates: NestedSequence[int]
samples: ArrayLike[float]

• NestedList[T] means lists nested to any depth, containing T at the leaves.
• NestedSequence[T] means nested lists or tuples.
• ArrayLike[T] means a scalar T, a nested sequence of T, or a NumPy array.

These aliases are for type checkers and IDEs. Runtime conversion is handled by the infer-type helpers.

Core APIs

Dtype Inference

from scihelpers import to_numpy_value, value_dtype

assert value_dtype([1, 256]).__name__ == "uint16"
array = to_numpy_value([[1, 2], [3, 4]])

Dataclass Helpers

from scihelpers import Dataclass, dataclass, field


@dataclass(order=True)
class Point:
    x: float
    y: float = 0.0


class Reading(Dataclass, frozen=True):
    sensor: str
    value: float

InferType

from scihelpers import InferType


class Sample(InferType, compact_repr=True):
    count: int
    values: ArrayLike[int]

ArrayModel

from scihelpers import array_model


@array_model(require_same_length=True)
class Spectrum:
    wavelength: list[float]
    intensity: list[float]

Struct

from scihelpers import Struct


class Particle(Struct, infer_types=True, frozen=True):
    charge: int
    mass: float

Enum

from scihelpers import Enum, auto, unique


@unique
class State(Enum):
    READY = auto()
    RUNNING = auto()
    DONE = auto()

Quantity

from scihelpers import Quantity

speed = Quantity(10, "m") / Quantity(2, "s")
assert speed.unit == "m/s"

Examples

See examples/ for richer scripts covering dtype inference, custom dataclasses, enums, array models, structs, and quantities.

Run one from the repository root:

python examples\dtype_inference.py

Testing

python -m pytest tests

Status

scihelpers is early and experimental. The public API is intentionally small, but it may still change while the library settles.