Metadata-Version: 2.4
Name: rextio-numpy
Version: 0.1.0
Summary: Rextio plugin that lowers eligible NumPy code to native Rust (plugin API 1.1: claim/lower, annotation vocabulary, pinned crate injection).
Author-email: Steve Si-young Song <rextio.co@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/rextio/rextio-numpy
Project-URL: Repository, https://github.com/rextio/rextio-numpy
Project-URL: Issues, https://github.com/rextio/rextio-numpy/issues
Keywords: rextio,numpy,rust,compiler,plugin
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rextio<0.2,>=0.1.1
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.15; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Dynamic: license-file

# rextio-numpy

**Rextio plugin that lowers eligible NumPy code to native Rust.**

The first-party [Rextio](https://github.com/rextio/rextio) plugin for NumPy.
It implements Rextio **plugin protocol v2** (`rextio.plugins.api`): the plugin
self-describes, as machine-readable rule records, which NumPy usage lowers to
Rust (via the `ndarray` crate) and which stays on the Python fallback —
following Rextio's core contract (CPython-equivalent semantics or fall back).

## Status: lowering implemented for the initial surface

The plugin now implements **plugin API 1.1** end to end: the annotation
vocabulary (`rextio_numpy.types.F64Arr1`), the deterministic `claim` pass,
`lower()` emission to Rust via the `ndarray` crate, and pinned crate
injection (rust-numpy `numpy =0.29.0`; ndarray via its re-export). The implemented
lowering surface, certified against CPython NumPy with the core plugin
certification kit (`rextio.plugins.testing`):

- Element-wise `+ - * /` on float64 1-D arrays — array-array, array-scalar,
  and scalar-array forms (`RXTP-NUMPY-001`, verified)
- `numpy.dot(a, b)` on float64 1-D arrays (`RXTP-NUMPY-002`, verified)
- Whole-array `numpy.sum` / `numpy.mean` reductions (`RXTP-NUMPY-003`,
  verified)

Shape/length mismatches raise `ValueError` with NumPy's exact messages.
Documented divergences (per rule `constraint`): dot/sum/mean float summation
order may differ from NumPy's pairwise summation, and the native mean of an
empty array returns nan without NumPy's `RuntimeWarning`.

Full rule surface (all `experimental`, codes `RXTP-NUMPY-NNN`):

| Rule | Outcome | Code |
|---|---|---|
| Element-wise `+ - * /` on 1-D float64 arrays (array-array incl. length-1 broadcasting, array-scalar, scalar-array) | native (verified) | RXTP-NUMPY-001 |
| `numpy.dot(a, b)` on 1-D float64 arrays (module-call form) | native (verified) | RXTP-NUMPY-002 |
| Whole-array `numpy.sum` / `numpy.mean` on 1-D float64 (module-call form) | native (verified) | RXTP-NUMPY-003 |
| Non-float64 dtypes / unsupported operand types | fallback | RXTP-NUMPY-010 |
| Rank > 1 or unknown rank | fallback | RXTP-NUMPY-011 |
| Mutating aliased views | fallback | RXTP-NUMPY-012 |
| Any other NumPy API | fallback | RXTP-NUMPY-019 |

Codes RXTP-NUMPY-011/012/019 are declarative-only: they document fallback
boundaries in the rule records but are never attached to diagnostics —
uncovered sites surface as core's RXT030 instead. Only RXTP-NUMPY-010 is
actively emitted.

NumPy itself is deliberately **not** a dependency of the plugin — only the
user-facing `rextio_numpy.types` vocabulary module imports it, in the user's
project. A `@numba.*`-decorated function is always respected as the user's
opt-in to Numba's semantics and is never lowered by this plugin.

## Usage

```toml
# rextio.toml
[rust]
build_tool = "cargo"

[plugins]
enabled = ["rextio-numpy"]
```

```python
import numpy as np
from rextio_numpy.types import F64Arr1  # plain runtime alias of numpy.ndarray

def dot(a: F64Arr1, b: F64Arr1) -> float:
    return np.dot(a, b)
```

```bash
pip install rextio-numpy   # requires rextio >= 0.1.1 (unreleased yet)
rextio capabilities --format json   # numpy rules appear under "rules"
rextio build .                      # lowered kernels compile via cargo
```

## Development

rextio 0.1.1 is not on PyPI yet, so install core from a checkout first and
this package without dependency resolution:

```bash
uv venv --python 3.11 .venv
uv pip install --python .venv/bin/python -e path/to/rextio
uv pip install --python .venv/bin/python --no-deps -e .
uv pip install --python .venv/bin/python pytest ruff mypy
.venv/bin/python -m pytest
```

## License

MIT
