Metadata-Version: 2.4
Name: numbertoolkit
Version: 0.1.0
License-File: LICENSE
Summary: Fast number theory utilities backed by Rust
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# numbertoolkit

Fast number theory utilities for Python, backed by Rust.

```python
import numbertoolkit

numbertoolkit.pi_digits(10)
# '3.141592653'
```

## Functions

### `pi_digits(n: int) -> str`

Returns the first `n` significant digits of pi as a string, e.g.
`pi_digits(5) == "3.1415"`. Digits are truncated, not rounded.

Implemented with the Chudnovsky series using binary splitting and exact
integer arithmetic (no floating point), so it stays fast well into the
millions of digits.

## Demo

An interactive [marimo](https://marimo.io) notebook demoing the package:

```sh
uv run marimo edit demo.py
```

## Benchmarks

Compare against mpmath and a stdlib-`decimal` Machin baseline:

```sh
uv run --group bench benchmarks/bench_pi.py
```

On an Apple Silicon laptop:

| digits | numbertoolkit | mpmath | speedup vs mpmath |
|---:|---:|---:|---:|
| 10,000 | 0.0008s | 0.0052s | 6x |
| 100,000 | 0.0154s | 0.1926s | 13x |
| 1,000,000 | 0.2526s | 9.0297s | 36x |

## Development

Requires [Rust](https://rustup.rs) and [uv](https://docs.astral.sh/uv/).

```sh
make install                   # uv sync: build the extension and set up .venv
make test                      # cargo test + pytest
make bench                     # run the benchmark suite
uvx maturin develop --uv -r    # fast rebuild loop (release mode)
```

Note: `maturin develop` without `-r` produces a debug build that is 10–50x
slower — always use release mode when timing anything.

## Releasing

Tests run automatically on GitHub (`.github/workflows/ci.yml`); publishing to
PyPI is done manually. Thanks to abi3, each wheel covers Python 3.10+ on its
platform, and cross-compiling doesn't need a target Python interpreter.

`make wheels` builds the full release set (macOS wheel, both Linux wheels via
zig, sdist) and `make pypi` runs the tests, builds, and uploads. The
underlying commands:

```sh
# wheel for this machine + source distribution (lands in target/wheels/)
uvx maturin build --release
uvx maturin sdist

# optional: manylinux wheels cross-compiled from macOS via zig
rustup target add x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu
uvx --with ziglang maturin build --release --zig --target x86_64-unknown-linux-gnu
uvx --with ziglang maturin build --release --zig --target aarch64-unknown-linux-gnu

# upload everything (needs a PyPI API token, e.g. via UV_PUBLISH_TOKEN)
uv publish target/wheels/*
```

Bump the version in `pyproject.toml` before building. Platforms without an
uploaded wheel (e.g. Windows) fall back to the sdist, which requires a Rust
toolchain to install.

## License

This project is MIT licensed. It statically links
[malachite](https://crates.io/crates/malachite) (LGPL-3.0-only) for
big-integer arithmetic; malachite's source is available on crates.io. If you
embed this library in a closed-source distribution, the LGPL relinking
requirements apply to the bundled malachite code.

