numbertoolkit 0.1.0

Fast number theory utilities backed by Rust

numbertoolkit

Fast number theory utilities for Python, backed by Rust.

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 notebook demoing the package:

uv run marimo edit demo.py

Benchmarks

Compare against mpmath and a stdlib-decimal Machin baseline:

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 and uv.

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:

# 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 (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.