Metadata-Version: 2.4
Name: bearshape
Version: 0.0.1
Summary: Elegant runtime shape and dtype checking for NumPy, JAX, PyTorch, and CuPy arrays — powered by beartype.
Keywords: type-checking,shape,dtype,numpy,jax,pytorch,cupy,beartype
Author: acecchini
Author-email: acecchini <ale.cecchini.valette@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: beartype>=0.20,<0.23
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/acecchini/bearshape
Project-URL: Repository, https://github.com/acecchini/bearshape
Project-URL: Issues, https://github.com/acecchini/bearshape/issues
Description-Content-Type: text/markdown

# Bearshape

[![Python 3.10-3.14](docs/assets/images/python_versions_badge.svg)](https://www.python.org/)
![Coverage 91%](https://img.shields.io/badge/coverage-91%25-34D058?style=flat-square&logo=codecov&logoColor=F01F7A&labelColor=1F2937)
[![Docs](https://img.shields.io/badge/docs-live-526CFE?style=flat-square&logo=materialformkdocs&logoColor=white&labelColor=1F2937)](https://acecchini.github.io/bearshape/)

Runtime shape and dtype checking for NumPy, JAX, PyTorch, CuPy, and
tree-structured containers, powered by
[beartype](https://github.com/beartype/beartype).

```python
from beartype import beartype
from bearshape import N, C
from bearshape.numpy import F32


@beartype
def normalize(x: F32[N, C]) -> F32[N, C]:
  return x / x.sum(axis=1, keepdims=True)
```

Bearshape turns annotations such as `F32[N, C]`, `F32Like[~B, C]`,
`F32[Value("size")]`, and `Tree[F32[N], T]` into runtime-validated contracts.
Named dimensions are shared within a function call, so mismatched shapes fail at
the boundary instead of later in array code.

## Install

```bash
pip install bearshape
```

Bearshape keeps the root import lightweight. Install the array backend packages
you use explicitly:

```bash
pip install bearshape numpy
pip install bearshape numpy torch
pip install bearshape numpy jax
pip install bearshape numpy cupy
pip install bearshape numpy optree
```

## What It Checks

- strict array type, dtype, and shape contracts
- backend-aware `Like[...]` conversion checks
- scalar-like values and constrained runtime `Value(...)` dimensions
- tree leaf and structure annotations through JAX or OpTree
- annotation syntax exercised by pyright, mypy, and ty fixtures

## Public Surface

Import dimensions, `Value`, `Scalar`, `DtypeSpec`, `check`, and `check_context`
from `bearshape`.

Import backend aliases from backend modules:

```python
from bearshape.numpy import F32, F32Like
from bearshape.jax import Tree
from bearshape.torch import I64
```

The root package does not import NumPy or any backend. Backend modules require
their own runtime dependencies.

## Development

```bash
uv sync
uv run prek run -a
uv run pytest -n auto tests/
uv run pytest -n auto tests/test_typecheck.py
uv run pyright src tests/typing
uv run mypy src tests/typing
uv run ty check src tests/typing
```

CuPy runtime tests require a CUDA-capable environment and are deferred on
CPU-only machines.

See the documentation site for the full user guide and API reference.
