OneRoll
OneRoll is a Rust dice-language engine exposed to Python through PyO3. It ships with a Python SDK, CLI, and Textual TUI. The v2 package boundary will make UI dependencies optional for SDK-only installations.
The current 1.x engine supports numeric dice expressions, arithmetic,
parentheses, comments, and a compatibility set of modifiers. The 2.0 roadmap
evolves that expression roller into a bounded, typed program language with
ranges, weighted-list dice, validators, variables, option pipelines, and
structured results.
Current scalar literals and totals use checked signed 64-bit arithmetic.
Overflow, division by zero, and invalid exponents raise ValueError with a
stable arithmetic.* code instead of panicking or wrapping.
Numeric dice use the request-scoped oneroll-chacha12-v1 protocol and unbiased
rejection sampling. Rust embedders can supply a canonical RandomSeed through
DiceCalculator::with_seed and inspect the replay descriptor. The frozen
Python Engine(..., seed=...) and CLI replay surface remain tracked v2 work;
the compatibility helpers do not expose a temporary seed signature.
OneRoll is being hardened for production. Features listed in the v2 RFC are targets unless the implementation status explicitly says otherwise.
Install
pip install oneroll
Build an editable package from source:
uv sync --frozen
uv run maturin develop
Python
Use roll() for one compatibility expression:
import oneroll
result = oneroll.roll("4d6kh3 # attribute")
print(result["total"])
print(result["comment"])
Use run() for a non-empty semicolon-separated program:
program = oneroll.run("1d20 + 5; 2d6 # encounter")
print([result["total"] for result in program["results"]])
print(program["comment"])
Every instruction in one program shares the same request budget. Invalid or
exhausted evaluations raise ValueError instead of hanging or panicking.
Parsing, recursion, generated values, collections, output, work, and batches
all have safe defaults and non-disableable hard ceilings.
Create an immutable policy when an embedding needs lower limits:
policy = oneroll.ResourcePolicy().with_limit("generated_values", 2_000)
roller = oneroll.OneRoll(policy)
print(policy.limits())
CLI
python -m oneroll "3d6 + 2"
python -m oneroll "1d20 + 5; 2d6 # encounter"
python -m oneroll --stats "3d6" --times 100
python -m oneroll --show-limits
python -m oneroll --limit generated_values=2000 "20d6"
Current syntax
The parser's authoritative accepted syntax lives in
src/oneroll/grammar.pest and is embedded directly
in the language guide. Observable 1.x semantics
are recorded in the conformance corpus, including
compatibility-sensitive behavior and known defects.
Roadmap and specification
- Language guide
- Resource limits
- Deterministic randomness
- Fuzzing and property gates
- Production roadmap
- RFC-0001: OneRoll Program Language v2
- RFC-0002: Execution Safety, Budgets, and Randomness
- RFC-0003: Typed Program Results, Roll Traces, and Errors
- RFC-0004: Python Engine API and Package Boundary
- GitHub milestones
- GitHub issues
The implementation order is Program → typed values → dice sources → validators → option pipelines → functions and conditionals. CLI commands such
as help and la stay outside the pure core language, and @ remains reserved
until bounded jump semantics are accepted.
Verify
cargo test
cargo test --release property_
uv run --frozen maturin develop
uv run --frozen python -m unittest discover -s tests -v
uv run --frozen sphinx-build -W --keep-going -b html docs/source docs/_build/html
License
AGPL-3.0
1 maintainer
Release files for oneroll 1.3.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| oneroll-1.3.5.tar.gz | 263.8 kB | Details |
Built distributions (wheels)
Total release size: 6.8 MB
Release files / oneroll-1.3.5.tar.gz
| Download URL | oneroll-1.3.5.tar.gz |
|---|---|
| Size | 263.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
55027a21660d0ed400d1d8a1d4b97cc8ef0ec5fbca44739a4a16176e03cc18bc
|
|
BLAKE2b-256 checksum How to use checksums |
d35df5ee3712377504603d02037fc0c43fcd409cd150347f606d23d745a7e007
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logRelease files / oneroll-1.3.5-cp39-abi3-win_amd64.whl
| Download URL | oneroll-1.3.5-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 270.7 kB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
502579d99a3f8e0dffa695ed8675042fd9ec26a7da59fc4cf65ff0a9efa0e1db
|
|
BLAKE2b-256 checksum How to use checksums |
5e0a17783fdf4babecfc3db478b306d88067e55a8cb19433da172d8d5dafd4b6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logRelease files / oneroll-1.3.5-cp39-abi3-win32.whl
| Download URL | oneroll-1.3.5-cp39-abi3-win32.whl |
|---|---|
| Size | 253.0 kB |
| Tags | CPython 3.9 Windows x86-32 abi3 |
|
SHA-256 checksum How to use checksums |
03c454063b44a4b9442eda0f52d27f76da4b65b2e792d7a7a3685928cdc3594c
|
|
BLAKE2b-256 checksum How to use checksums |
06278285d31401542dcac5b6f13d0e85aedcf279d633c10470199f1f01cdb304
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logRelease files / oneroll-1.3.5-cp39-abi3-musllinux_1_2_x86_64.whl
| Download URL | oneroll-1.3.5-cp39-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 623.3 kB |
| Tags | CPython 3.9 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
8e43189b094242fe9f6fb84c157a0fd17c7a028c8349699604bc98d14044ed18
|
|
BLAKE2b-256 checksum How to use checksums |
c00762cb21602d9a622505e2157e659ad1d7d5c7f7a64f88d54b839efa622635
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logRelease files / oneroll-1.3.5-cp39-abi3-musllinux_1_2_i686.whl
| Download URL | oneroll-1.3.5-cp39-abi3-musllinux_1_2_i686.whl |
|---|---|
| Size | 654.5 kB |
| Tags | CPython 3.9 Linux musl 1.2+ x86-32 abi3 |
|
SHA-256 checksum How to use checksums |
728cfd5146c811bee0324403d608806d601339db7828faa15d20fa7277ab29f5
|
|
BLAKE2b-256 checksum How to use checksums |
a688172cc8c6182cdf0fa908ee4d1ba9cf083cec8cb5285bb2f3e65130ebfde6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logRelease files / oneroll-1.3.5-cp39-abi3-musllinux_1_2_armv7l.whl
| Download URL | oneroll-1.3.5-cp39-abi3-musllinux_1_2_armv7l.whl |
|---|---|
| Size | 687.1 kB |
| Tags | CPython 3.9 Linux musl 1.2+ ARMv7l abi3 |
|
SHA-256 checksum How to use checksums |
ed46f812a7b259d4b13d1f2dd99b41943a4193b6818f4a41638c758cff165585
|
|
BLAKE2b-256 checksum How to use checksums |
db30effd170109830149640690efa82f0672fb4426a407d00e399b4d5ab5f1ac
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logRelease files / oneroll-1.3.5-cp39-abi3-musllinux_1_2_aarch64.whl
| Download URL | oneroll-1.3.5-cp39-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 585.2 kB |
| Tags | CPython 3.9 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
1e09c003fcdd7410c03931cb6500fb910d271854ff0b56b68309a10f64392fe4
|
|
BLAKE2b-256 checksum How to use checksums |
ba76f4ab8f0b900d8a6d8051b252267fc3bf6a7b8906a53ed188c159b40b4460
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logRelease files / oneroll-1.3.5-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | oneroll-1.3.5-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 417.7 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
bfaac11abcc1f412271cf3d112c46d64e2761c31dcb5f827551f3e9b62a7bde0
|
|
BLAKE2b-256 checksum How to use checksums |
2a163da5df47f9297ec8a807ff2508c7ccd733f7071d1f7f0afb929a542b5cc4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logRelease files / oneroll-1.3.5-cp39-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl
| Download URL | oneroll-1.3.5-cp39-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl |
|---|---|
| Size | 442.6 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ IBM System/390x abi3 |
|
SHA-256 checksum How to use checksums |
04bbb27fb381bbc177bf4614d90edd9cc778ce16cdd3c014d0f2aa11c0316d23
|
|
BLAKE2b-256 checksum How to use checksums |
466dc9aed3b123f44dca3965b2158a85f720860b4ea6b984446712b393ee4d31
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logRelease files / oneroll-1.3.5-cp39-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl
| Download URL | oneroll-1.3.5-cp39-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl |
|---|---|
| Size | 612.2 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ PowerPC 64-le abi3 |
|
SHA-256 checksum How to use checksums |
c7c0af0064cbe2bc60d6977f2da38728d4e410ecb99c27faafbef66f8ac208ce
|
|
BLAKE2b-256 checksum How to use checksums |
eded11985b5ce3ba66e91c58d9dcccbf773d88f61f18a1ff6e432ae1060cdc01
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logRelease files / oneroll-1.3.5-cp39-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
| Download URL | oneroll-1.3.5-cp39-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl |
|---|---|
| Size | 412.0 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARMv7l abi3 |
|
SHA-256 checksum How to use checksums |
ddb0458ad762a316d494f60365b0378d2e053644c24f1578dc076337fb5fcb44
|
|
BLAKE2b-256 checksum How to use checksums |
f104a81db26b033fc32f99cb19f520bba3144c3fbc8d8352a80c8f377ca3ec60
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logRelease files / oneroll-1.3.5-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | oneroll-1.3.5-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 408.3 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
f421bb46e0322a85d0aee37bafd96dcc7b0b1352879f9db7570fa16928e15435
|
|
BLAKE2b-256 checksum How to use checksums |
69089196a2356311cc8325d262f76612efab37d1a80c43ff55a20891a2037032
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logRelease files / oneroll-1.3.5-cp39-abi3-manylinux_2_5_i686.manylinux1_i686.whl
| Download URL | oneroll-1.3.5-cp39-abi3-manylinux_2_5_i686.manylinux1_i686.whl |
|---|---|
| Size | 444.4 kB |
| Tags | CPython 3.9 Linux glibc 2.5+ x86-32 abi3 |
|
SHA-256 checksum How to use checksums |
63f0c20070a4ed2cbc0e45c116fc5e08e453ab8c49c2c330a47fb0975c98b166
|
|
BLAKE2b-256 checksum How to use checksums |
091d76fe9766d2214a39d1ceca2fdaf8d55f9ea487ab3e18afcf24fce070d7cd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logRelease files / oneroll-1.3.5-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | oneroll-1.3.5-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 371.1 kB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
d9a7b418537246d6771115add1a4c6ac636718b20a738efc9383e38f703123f8
|
|
BLAKE2b-256 checksum How to use checksums |
ad177a2dd0fed8ef31063e03399b9c713afeae5e0e7c773e6f1462699e7c99a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logRelease files / oneroll-1.3.5-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | oneroll-1.3.5-cp39-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 373.8 kB |
| Tags | CPython 3.9 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
95a276423d76449f07bf355e11738faf9a8d22f2a71ee0464490e3b603823813
|
|
BLAKE2b-256 checksum How to use checksums |
6b2f2dd83aa849a8402e048b3d6082e8c608edae13c7956a48a6d240822dde2b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency log
