Base Dice¶

Core of the dice class.

These methods are the core of the dice class and the minimum needed for the other mixins to extend from. These mostly focus on allowing the dice to be initialized correctly.

class dice_stats._magic.base_dice.BaseDice(chances=None, total_chance=Fraction(1, 1))¶

Base Dice class, defines standard methods for initializing dice objects.

Other magic dice classes inherit from this.

__init__(chances=None, total_chance=Fraction(1, 1))¶

Initialize Dice class.

Parameters

chances (Optional[Dict[Union[Real, Integral], Fraction]]) – Internal Chances dictionary.
total_chance (Union[Fraction, BaseDice, int]) – Total Chance which allows a dice to have a 50% chance, whilst allowing the Internal Chances to total 1.

Return type

None

copy()¶

Create a copy of the current dice.

This allows other methods to easily mutate a copy of a provided dice without mutating the dice a user provides. This helps keep the purity of a lot of the functions in this library.

Returns: A copy of this dice, including its type.

classmethod from_empty(value=0)¶

Create an empty chance.

A Chances Value must be specified and so defaults to 0 as the unwanted value.

Parameters: value (Union[Real, Integral]) – Chances Value of the failure value.
Returns: An empty dice.

classmethod from_full(chances, total_chance=Fraction(1, 1))¶

From full Internal Chances.

This is a helper function to build dice from the Internal Chances. Allowing a different Total Chance.

Parameters

chances (Dict[Union[Real, Integral], Fraction]) – Internal Chances object.
total_chance (Fraction) – Total Chance.

Returns

A new dice with the provided chances.

classmethod from_partial(chances=None, total_chance=Fraction(1, 1))¶

From partial Internal Chances.

This is a helper function to build dice from the Internal Chances, where the chance’s always total 1. By defaulting all undefined Chances Chance to the chance of 0, rather than erroring.

This may become deprecated in the future, as it seems like there is no use for this method.

Parameters

chances (Optional[Dict[Union[Real, Integral], Fraction]]) – Internal Chances object.
total_chance (Fraction) – Total Chance.

Returns

A new dice with the provided chances.

property total_chance¶

Total Chance of the values of this dice.

Return type: Fraction
Returns: The Total Chance of the dice.

Basic¶

Methods all classes should define.

Methods that are at the base of the class, but don’t need to be defined in base_dice.py. These are things like str, repr and bool.

These are magic methods that any class should define to make Pythonic development easier.

class dice_stats._magic.basic.BasicDice(chances=None, total_chance=Fraction(1, 1))¶

Basic magic methods mixin class.

__bool__()¶

Falsy if the only Chances Chance is 0.

Return type: bool

__contains__(item)¶

Is Chances Value a possible Chances Chance.

This doesn’t check if the Chances Value is contained in the Internal Chances. It checks if there is a potability of the dice. This is as some dice will show 0 as a Chances Value with 0% Chances Chance, however as it’s not possible it doesn’t make sense to say it’s a Chances Chance of the dice.

Return type: bool

__repr__()¶

Repr format of Dice.

Return type: str

__str__()¶

Str format of Dice.

Return type: str

Mapping¶

Mapping interface.

Code to make Dice implement an immutable mapping interface. This interface helps to keep code that uses dice Pythonic as they can use standard methods, and it the immutability helps make all the code simpler to use as we don’t need to think about mutability.

class dice_stats._magic.mapping.MappingDice(chances=None, total_chance=Fraction(1, 1))¶

Mapping mixin.

__getitem__(item)¶

Get Chances Chance.

Return type: Fraction

__iter__()¶

Get all Chances Value.

Return type: Iterator[Union[Real, Integral]]

__len__()¶

Count of all Chances Value.

Return type: int

__weakref__¶: list of weak references to the object (if defined)

Numeric¶

Numeric operators.

Add support for using Dice numerically. For the most part all operations should work as expected. But two methods have two different ways they could be reasonably expected to work.

For the examples d6 is defined as Dice.from_dice(6).

Most operations work as if you were applying that function to all values in the dice. This means if you were to use Dice.from_dice(6) + 2 then the values would range from 3 to 8, rather than from 1 to 6. The chance for all would still be 1/6.

You can also add dice to other dice. d6 + d6 would result in a triangle chance with 7 being the most likely result.

However it is unclear what 2 * d6 should result in. This is as 2d6 is a common way to denote rolling two d6s and adding the results together. Which is the same as d6 + d6.

There is then the option of performing the cartesian product of {2} and {1, 2, 3, 4, 5, 6}, which would result in {2, 4, 6, 8, 10, 12}.

Given that both make sense, but we can only define one to be _the_ multiplication operator. We have decided to keep with common convention and have made the multiplication operator work the same way as d6 + d6. If the cartesian product is required then it is available via the non_repeat property. Such as 2 * d6.non_repeat.

We have also changed the power operator to work in the same way. And so d6 ** 2 is the same as d6 * d6.non_repeat.