Skip to main content

Dice notation tools

Project description

This notation is widely used on tabletop games, such as wargames or RPGs, and was created on the late 70s for Dungeons & Dragons, as a way to allow generating random values in specific distributions.

With the pass of years it has evolved, and while it never underwent a formal standarization process a core set of rules is kept among all the variations, mostly representing dice in a format such as ‘1d6’, and the use of algebra operations like addition and subtraction.

This project aims to give support to the dice notation, allowing parsing and operating with it on any Python application.

Dice Notation Tools for Python Pypi package page Dice Notation Tools for Python latest documentation Dice Notation Tools for Python development documentation

Features

  • ANTLR-based parser generates objects from dice notation (BNF grammar included)

  • Easy-to-use model, just call the ‘roll’ method

  • Classes to support plain dice

Documentation

Documentation sources are included with the project, and used to generate the documentation sites:

  • The latest docs are always generated for the latest release, kept in the ‘master’ branch

  • The development docs are generated from the latest code in the ‘develop’ branch

The source files for the docs, a small Sphinx project, are kept in the ‘docs folder.

These can be built if needed:

python setup.py build_docs

Prerequisites

The project has been tested in the following versions of the interpreter:

  • Python 3.6

  • Python 3.7

  • Python 3.8

All other dependencies are indicated on the requirements.txt file.

These can be installed with:

pip install --upgrade -r requirements.txt

Building the grammar

First of all install ANTLR as told here.

Afterwards, follow these indications.

The command to generate the parser will be:

antlr4 -Dlanguage=Python2 DiceNotation.g4 DiceNotationLexer.g4

Installing

The project is offered as a Pypi package, and using pip is the preferred way to install it. For this use the following command;

pip install dice-notation

If needed, manual installation is possible:

python setup.py install

Usage

The application has been coded in Python, and does not require any particular framework.

To use it just import the parser:

from dice_notation.parser import DiceParser

And then use it to parse a dice notation expression:

parser = DiceParser()
dice = parser.parse('1d6+2')

The result can be accessed just by calling the ‘value’ method as many times as needed, which will generate a new random value each time it is called:

print(dice.roll())
print(dice.roll())

Testing

The tests included with the project can be run with:

python setup.py test

This will delegate the execution to tox.

It is possible to run just one of the test profiles, in this case the py36 profile:

python setup.py test -p "py38"

Collaborate

Any kind of help with the project will be well received, and there are two main ways to give such help:

  • Reporting errors and asking for extensions through the issues management

  • or forking the repository and extending the project

Issues management

Issues are managed at the GitHub project issues tracker, where any Github user may report bugs or ask for new features.

Getting the code

If you wish to fork or modify the code, visit the GitHub project page, where the latest versions are always kept. Check the ‘master’ branch for the latest release, and the ‘develop’ for the current, and stable, development version.

License

The project has been released under the MIT License.

Project details


Download files

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

Source Distribution

dice-notation-1.2.1.tar.gz (44.6 kB view details)

Uploaded Source

Built Distribution

dice_notation-1.2.1-py2.py3-none-any.whl (20.7 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file dice-notation-1.2.1.tar.gz.

File metadata

  • Download URL: dice-notation-1.2.1.tar.gz
  • Upload date:
  • Size: 44.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/32.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.8 tqdm/4.63.0 importlib-metadata/4.11.2 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.9.10

File hashes

Hashes for dice-notation-1.2.1.tar.gz
Algorithm Hash digest
SHA256 845c3f534ac5b5f2aca4700e168becdad197595b60544b5d598e89dc097c07db
MD5 c7aed5fbf0fa746bea49f17adf858eb3
BLAKE2b-256 8e50feaf20c747fa1dcd439b57308d9f2afecf19c913f485ce4a2619907444b9

See more details on using hashes here.

File details

Details for the file dice_notation-1.2.1-py2.py3-none-any.whl.

File metadata

  • Download URL: dice_notation-1.2.1-py2.py3-none-any.whl
  • Upload date:
  • Size: 20.7 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/32.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.8 tqdm/4.63.0 importlib-metadata/4.11.2 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.9.10

File hashes

Hashes for dice_notation-1.2.1-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 82a3d9d00087e97b19b5ef32952dfcd58462696de7e73e8cf96f1d6141e1a35a
MD5 658e6f4f8a3e6b8d32397181d465523b
BLAKE2b-256 b058eeb5397948cb4cea08d7594f20f50645977274990656f71a91b487885bbf

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page