Metadata-Version: 2.4
Name: scihelpers
Version: 0.1.0
Summary: Class helpers and NumPy dtype conversion utilities for scientific computing.
Author: scihelpers contributors
License-Expression: MIT
Keywords: scientific-computing,numpy,dataclass,enum,dtype,typing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Provides-Extra: dev
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# 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:

```powershell
python -m pip install -e .
```

For development tools:

```powershell
python -m pip install -e .[dev]
```

## Quick Start

```python
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:

```python
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

```python
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

```python
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

```python
from scihelpers import InferType


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

### ArrayModel

```python
from scihelpers import array_model


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

### Struct

```python
from scihelpers import Struct


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

### Enum

```python
from scihelpers import Enum, auto, unique


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

### Quantity

```python
from scihelpers import Quantity

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

## Examples

See [`examples/`](examples/) for richer scripts covering dtype inference, custom dataclasses, enums, array models, structs, and quantities.

Run one from the repository root:

```powershell
python examples\dtype_inference.py
```

## Testing

```powershell
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.
