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

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

oneroll-1.3.5.tar.gz (263.8 kB view details)

Uploaded Jul 30, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

oneroll-1.3.5-cp39-abi3-win_amd64.whl (270.7 kB view details)

Uploaded Jul 30, 2026 CPython 3.9+Windows x86-64

oneroll-1.3.5-cp39-abi3-win32.whl (253.0 kB view details)

Uploaded Jul 30, 2026 CPython 3.9+Windows x86

oneroll-1.3.5-cp39-abi3-musllinux_1_2_x86_64.whl (623.3 kB view details)

Uploaded Jul 30, 2026 CPython 3.9+musllinux: musl 1.2+ x86-64

oneroll-1.3.5-cp39-abi3-musllinux_1_2_i686.whl (654.5 kB view details)

Uploaded Jul 30, 2026 CPython 3.9+musllinux: musl 1.2+ i686

oneroll-1.3.5-cp39-abi3-musllinux_1_2_armv7l.whl (687.1 kB view details)

Uploaded Jul 30, 2026 CPython 3.9+musllinux: musl 1.2+ ARMv7l

oneroll-1.3.5-cp39-abi3-musllinux_1_2_aarch64.whl (585.2 kB view details)

Uploaded Jul 30, 2026 CPython 3.9+musllinux: musl 1.2+ ARM64

oneroll-1.3.5-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (417.7 kB view details)

Uploaded Jul 30, 2026 CPython 3.9+manylinux: glibc 2.17+ x86-64

oneroll-1.3.5-cp39-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl (442.6 kB view details)

Uploaded Jul 30, 2026 CPython 3.9+manylinux: glibc 2.17+ s390x

oneroll-1.3.5-cp39-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl (612.2 kB view details)

Uploaded Jul 30, 2026 CPython 3.9+manylinux: glibc 2.17+ ppc64le

oneroll-1.3.5-cp39-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (412.0 kB view details)

Uploaded Jul 30, 2026 CPython 3.9+manylinux: glibc 2.17+ ARMv7l

oneroll-1.3.5-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (408.3 kB view details)

Uploaded Jul 30, 2026 CPython 3.9+manylinux: glibc 2.17+ ARM64

oneroll-1.3.5-cp39-abi3-manylinux_2_5_i686.manylinux1_i686.whl (444.4 kB view details)

Uploaded Jul 30, 2026 CPython 3.9+manylinux: glibc 2.5+ i686

oneroll-1.3.5-cp39-abi3-macosx_11_0_arm64.whl (371.1 kB view details)

Uploaded Jul 30, 2026 CPython 3.9+macOS 11.0+ ARM64

oneroll-1.3.5-cp39-abi3-macosx_10_12_x86_64.whl (373.8 kB view details)

Uploaded Jul 30, 2026 CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file oneroll-1.3.5.tar.gz.

File metadata

Download URL: oneroll-1.3.5.tar.gz
Upload date: Jul 30, 2026
Size: 263.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for oneroll-1.3.5.tar.gz
Algorithm	Hash digest
SHA256	`55027a21660d0ed400d1d8a1d4b97cc8ef0ec5fbca44739a4a16176e03cc18bc`
MD5	`587732efed2b8ed540a31e0c476fe35d`
BLAKE2b-256	`d35df5ee3712377504603d02037fc0c43fcd409cd150347f606d23d745a7e007`

Algorithm	Hash digest
SHA256	`502579d99a3f8e0dffa695ed8675042fd9ec26a7da59fc4cf65ff0a9efa0e1db`
MD5	`91afea684fe8dfd813d561429764bf6b`
BLAKE2b-256	`5e0a17783fdf4babecfc3db478b306d88067e55a8cb19433da172d8d5dafd4b6`

Algorithm	Hash digest
SHA256	`03c454063b44a4b9442eda0f52d27f76da4b65b2e792d7a7a3685928cdc3594c`
MD5	`2fa954bee4012465fe502787631974e4`
BLAKE2b-256	`06278285d31401542dcac5b6f13d0e85aedcf279d633c10470199f1f01cdb304`

Algorithm	Hash digest
SHA256	`8e43189b094242fe9f6fb84c157a0fd17c7a028c8349699604bc98d14044ed18`
MD5	`2061644ef4426d8de9f44807b5a06151`
BLAKE2b-256	`c00762cb21602d9a622505e2157e659ad1d7d5c7f7a64f88d54b839efa622635`

Algorithm	Hash digest
SHA256	`728cfd5146c811bee0324403d608806d601339db7828faa15d20fa7277ab29f5`
MD5	`dda89554887820032a18f8daff8e8e28`
BLAKE2b-256	`a688172cc8c6182cdf0fa908ee4d1ba9cf083cec8cb5285bb2f3e65130ebfde6`

Algorithm	Hash digest
SHA256	`ed46f812a7b259d4b13d1f2dd99b41943a4193b6818f4a41638c758cff165585`
MD5	`c5af1b8b6544fad6cb1f60e9c16e768e`
BLAKE2b-256	`db30effd170109830149640690efa82f0672fb4426a407d00e399b4d5ab5f1ac`

Algorithm	Hash digest
SHA256	`1e09c003fcdd7410c03931cb6500fb910d271854ff0b56b68309a10f64392fe4`
MD5	`f7e0a74314bb3c9ac662bb8b97a79677`
BLAKE2b-256	`ba76f4ab8f0b900d8a6d8051b252267fc3bf6a7b8906a53ed188c159b40b4460`

Algorithm	Hash digest
SHA256	`bfaac11abcc1f412271cf3d112c46d64e2761c31dcb5f827551f3e9b62a7bde0`
MD5	`91685b8b46c51a0663727738b178ef1f`
BLAKE2b-256	`2a163da5df47f9297ec8a807ff2508c7ccd733f7071d1f7f0afb929a542b5cc4`

Algorithm	Hash digest
SHA256	`04bbb27fb381bbc177bf4614d90edd9cc778ce16cdd3c014d0f2aa11c0316d23`
MD5	`27bb00483a3bf96e6f7c48905d078cdc`
BLAKE2b-256	`466dc9aed3b123f44dca3965b2158a85f720860b4ea6b984446712b393ee4d31`

Algorithm	Hash digest
SHA256	`c7c0af0064cbe2bc60d6977f2da38728d4e410ecb99c27faafbef66f8ac208ce`
MD5	`eb1c0298c0a0bacde20f2493a2b4158e`
BLAKE2b-256	`eded11985b5ce3ba66e91c58d9dcccbf773d88f61f18a1ff6e432ae1060cdc01`

Algorithm	Hash digest
SHA256	`ddb0458ad762a316d494f60365b0378d2e053644c24f1578dc076337fb5fcb44`
MD5	`8a0f3af238276b3d811ead0131dfcb5a`
BLAKE2b-256	`f104a81db26b033fc32f99cb19f520bba3144c3fbc8d8352a80c8f377ca3ec60`

Algorithm	Hash digest
SHA256	`f421bb46e0322a85d0aee37bafd96dcc7b0b1352879f9db7570fa16928e15435`
MD5	`31e32f1e3f36fcb02832d9dd8ec7a688`
BLAKE2b-256	`69089196a2356311cc8325d262f76612efab37d1a80c43ff55a20891a2037032`

Algorithm	Hash digest
SHA256	`63f0c20070a4ed2cbc0e45c116fc5e08e453ab8c49c2c330a47fb0975c98b166`
MD5	`50feb7562d38c5fb0e3aecb2da04146b`
BLAKE2b-256	`091d76fe9766d2214a39d1ceca2fdaf8d55f9ea487ab3e18afcf24fce070d7cd`

Algorithm	Hash digest
SHA256	`d9a7b418537246d6771115add1a4c6ac636718b20a738efc9383e38f703123f8`
MD5	`1955367b498474a5b83419965ecadd6b`
BLAKE2b-256	`ad177a2dd0fed8ef31063e03399b9c713afeae5e0e7c773e6f1462699e7c99a8`

Algorithm	Hash digest
SHA256	`95a276423d76449f07bf355e11738faf9a8d22f2a71ee0464490e3b603823813`
MD5	`73111d79894fda59387bb20fe3f0bfd4`
BLAKE2b-256	`6b2f2dd83aa849a8402e048b3d6082e8c608edae13c7956a48a6d240822dde2b`

oneroll 1.3.5

OneRoll

Install

Python

CLI

Current syntax

Roadmap and specification

Verify

License

Project links

Key dates

Owner

1 maintainer

Credits

GitHub Statistics

License

Requires

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata