Metadata-Version: 2.4
Name: overfloat
Version: 0.1.2
Summary: Python bindings for the Overfloat native floating-point runtime
Author: Overfloat Contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/overfloat/overfloat
Project-URL: Repository, https://github.com/overfloat/overfloat
Project-URL: Issues, https://github.com/overfloat/overfloat/issues
Keywords: floating-point,ieee-754,native,ctypes,arbitrary-precision
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# overfloat

Overfloat is an IEEE 754-oriented arbitrary-precision floating-point runtime with Python bindings. The Python package installs like a normal Python dependency while loading a bundled native library through `ctypes`.

Use it when you want custom floating-point formats without manually wiring up a native shared library.

Highlights:

- install with `pip install overfloat`
- native library bundled in the wheel
- custom exponent and mantissa widths
- convenient IEEE-style presets for 16, 32, 64, and 128 total bits
- decimal parsing, exact formatting, arithmetic, comparisons, classifications, and bit-pattern round trips

## Install

Install from PyPI:

```powershell
pip install overfloat
```

If `pip` is not on `PATH`, use `python -m pip install overfloat` instead.

The PyPI wheels bundle the native Overfloat shared library for the target platform.

Use the wheel files attached to GitHub Releases only when you need manual downloads, offline installation, or release troubleshooting. The release workflow builds wheels for Python 3.9, 3.10, 3.11, 3.12, and 3.13.

Typical wheel names:

- Windows: `overfloat-<version>-cp<python>-cp<python>-win_amd64.whl`
- Linux: `overfloat-<version>-cp<python>-cp<python>-manylinux_..._x86_64.whl`
- macOS: `overfloat-<version>-cp<python>-cp<python>-macosx_11_0_arm64.whl`

For example, Python 3.9 uses `cp39`, Python 3.10 uses `cp310`, Python 3.11 uses `cp311`, Python 3.12 uses `cp312`, and Python 3.13 uses `cp313`.

## Usage

The default path is intentionally simple: import the library, create a format, then create numbers from strings or Python numeric values.

```python
from overfloat import OverfloatLibrary

lib = OverfloatLibrary()
spec = lib.create_spec_from_total_bits(32)

a = spec("1.5")
b = spec("2.25")

print(a + b)
print(a * b)
print(spec("1") / spec("10"))
```

`OverfloatLibrary()` loads the bundled native library by default. You can also pass an explicit shared library path.

The Python package version is exposed as `overfloat.__version__`.

## Advanced Usage

```python
import overfloat
from overfloat import OverfloatLibrary

lib = OverfloatLibrary()
spec = lib.create_spec_from_total_bits(4096)
manual_spec = lib.create_spec(43, 4048)

a = spec("1.5")
b = spec("2.25")
manual_value = manual_spec("1.5")

print(lib.version)
print(overfloat.__version__)
print(spec.exponent_bits)
print(spec.mantissa_bits)
print(a + b)
print(a * b)
print(spec("1") / spec("10"))
print(manual_spec.exponent_bits)
print(manual_spec.mantissa_bits)
print(manual_value)
print(a.to_bits_hex())
print(spec.from_bits_hex(a.to_bits_hex()))
print(a.compare(b))
print(a.compare_total(b))
print(lib.exception_flags)
```

`create_spec_from_total_bits(total_bits)` is the convenient preset form.

`create_spec(exponent_bits, mantissa_bits)` is the manual form when the exponent width and mantissa width need to be set directly.

Built-in preset formats:

- `16` -> exponent `5`, mantissa `10`
- `32` -> exponent `8`, mantissa `23`
- `64` -> exponent `11`, mantissa `52`
- `128` -> exponent `15`, mantissa `112`

These preset values match the IEEE 754 standard formats. For IEEE 754-2008 interchange-style formats with `k >= 128` and `k` a multiple of `32`, `create_spec_from_total_bits(k)` follows the standard width derivation.

For explicit lifetime management:

```python
from overfloat import OverfloatLibrary

lib = OverfloatLibrary()

with lib.create_spec_from_total_bits(4096) as spec:
    with spec("1.5") as value:
        print(value)
```

## Manual Builds

The prebuilt wheels are the recommended installation path. The source distribution can also build a platform native library during installation, but that path requires the .NET 8 SDK and a platform toolchain supported by .NET Native AOT.

If you are building this repository manually, build or copy the platform native library into `overfloat/` before creating a wheel or loading the package with `OverfloatLibrary()`.

Windows example:

```powershell
dotnet publish .\Overfloat.csproj -c Release -r win-x64
Copy-Item .\bin\Release\net8.0\win-x64\publish\Overfloat.dll .\python\overfloat\overfloat.dll -Force
Set-Location .\python
python -m build --wheel --outdir dist .
```

## License

Apache-2.0
