Metadata-Version: 2.4
Name: bovnar
Version: 0.9.1
Summary: Python bindings for the Bovnar (BVNR) typed, unit-aware serialisation format
Keywords: bovnar,bvnr,serialisation,units,ctypes
Author: Janos Sonntag
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: C
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 :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering
Project-URL: Source, https://github.com/sothis/bovnar
Project-URL: Documentation, https://github.com/sothis/bovnar/tree/main/doc
Project-URL: Issues, https://github.com/sothis/bovnar/issues
Requires-Python: >=3.10
Provides-Extra: numpy
Requires-Dist: numpy>=1.24; extra == "numpy"
Provides-Extra: pint
Requires-Dist: pint>=0.22; extra == "pint"
Provides-Extra: all
Requires-Dist: numpy>=1.24; extra == "all"
Requires-Dist: pint>=0.22; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: numpy>=1.24; extra == "dev"
Requires-Dist: pint>=0.22; extra == "dev"
Description-Content-Type: text/markdown

# bovnar

Python bindings for **Bovnar (BVNR)** — a typed, unit-aware serialisation format
with a C99 reference implementation.

In scientific and industrial systems the expensive failures are rarely bad
syntax — they are *unit confusion*: a value written in pounds-force and read as
newtons, feet read as metres. The number parses fine; the dimension is wrong.
Bovnar closes that gap: every value carries its own type family, bit-width,
numeric base, and **physical unit**, inline in the byte stream, validated by the
parser.

```bovnar
.velocity     = <float:64,m/s> 9.81;
.max_packet   = <uint:64,Mi~B> 16;
.price        = <float_dec:64,USD> 19.99;
.matrix       = [1, 2, 3]/[4, 5, 6];
```

The wheel bundles the compiled `libbvnr_shared` library, so there is nothing to
build and no system dependency to install — the bindings load it in-process via
`ctypes`.

## Install

```bash
pip install bovnar
```

Optional integrations:

```bash
pip install "bovnar[numpy]"   # numpy array bridge
pip install "bovnar[pint]"    # pint unit-registry bridge
pip install "bovnar[all]"     # both
```

## Usage

High-level dict API:

```python
import bovnar

doc = bovnar.dumps({
    "host": "api.example.com",
    "port": 443,
    "ratio": 3.5,
    "matrix": [[1, 2, 3], [4, 5, 6]],
})
print(doc.decode())

back = bovnar.loads(doc)
assert back["matrix"] == [[1, 2, 3], [4, 5, 6]]
```

Pass `typed=True` to `loads()` to preserve the exact type annotation and unit of
each value as a `Quantity`:

```python
data = bovnar.loads(b".velocity = <float:64,m/s> 9.81;\n", typed=True)
q = data["velocity"]
print(q.raw, bovnar.unit_to_str(q.unit))   # 9.81 m/s
```

Units and conversions are backed by the C library:

```python
m, mps = bovnar.parse_unit("m"), bovnar.parse_unit("m/s")
print(bovnar.units_compatible(m, mps))      # False
```

A streaming SAX-style `Reader`/`Writer` and a random-access `DomDoc` API are also
available — see the project documentation.

## Links

- Source & docs: https://github.com/sothis/bovnar
- Format documentation: https://github.com/sothis/bovnar/tree/main/doc

## License

MIT — see [LICENSE](https://github.com/sothis/bovnar/blob/main/LICENSE).
