yadr

The core of the yadr package, which contains the public API.

Public API

The following are the functions that make up the public API of yadr.

Rolling Dice

yadr.roll is the main interface to yadr, and in most cases it’s all you need.

yadr.roll(yadn: str, yadn_out: bool = False, dice_map: dict[str, dict[int, int | str]] | None = None) → None | int | bool | str | tuple[int, ...] | tuple[str, dict[int, int | str]] | CompoundResult

Execute a string of YADN to roll dice.

Parameters:

• yadn – A string of YADN that defines the die roll to execute.

• yadn_out – (Optional.) Whether the output should be in native Python objects or YADN notation. The default is native Python objects.

• dice_map – (Optional.) A dictionary of maps for transforming the value rolled. See Dice Maps for details.

Returns:

The result depends on the details of the die roll.

Return type:

None, Result, or CompoundResult

Usage:

>>> import yadr
>>>
>>> yadr.roll('3d6')                        
16

The specific result will depend on the YADN being executed. In the example above, it will be an integer in the range of three to eighteen that is created by generating three random integers in the range of one to six.

Managing Dice Maps

If you’re playing a game that uses symbol-based dice rather than ones with numbers, you may need to use a dice map to translate the dice rolls into those symbols. You can handle that in YADN, but the following functions can be useful, too.

yadr.add_dice_map(loc: str) → dict[str, dict[int, int | str]]

Load the dice-maps from a given file.

Parameters:

loc – The location of the file of dice mappings to load.

Returns:

None.

Return type:

NoneType

Usage:

>>> from yadr import add_dice_map
>>>
>>> path = 'tests/data/__test_dice_map.txt'
>>> add_dice_map(path)              
{'spam': {1: 'eggs', 2: 'bacon', 3: 'eggs', 4: 'tomato'}, 'fudge':
{1: '-', 2: '', 3: '+'}}

yadr.list_dice_maps() → str

Get the list of the default dice maps.

Returns:

A str object.

Return type:

str

Usage:

>>> from yadr import list_dice_maps
>>>
>>> list_dice_maps()                
'sweote boost...

Utility Functions

The following functions are used within the API, but they are not intended for public use. They are only documented here for support purposes.

yadr.yadr.get_default_maps() → dict[str, dict[int, int | str]]

Get the default dice maps.

Returns:

The default dice maps as a dict of dict objects.

Return type:

dict

Usage:

>>> from yadr.yadr import get_default_maps
>>>
>>> get_default_maps()              
{'sweote boost': {1: '',...

yadr.yadr.read_file(loc: str | Path) → str

Read test from a file.

Parameters:

loc – The file system location of the file.

Returns:

A :class:str object.

Return type:

str

yadr.yadr.parse_map(yadn: str) → dict[str, dict[int, int | str]]

Parse the contents of a dice mapping file.