DiceCLI

A package of functions for rolling dice implented as a CLI.
The module contains functions that replicate rolling polyhedral dice with any number of faces and rolling them in different ways; as an array, at advantage; as a critical hit; at disadvantage and rolling an array of 6 ability scores.
This is acheived with the parse_die_string function, which takes a string and returns a dictionary of all the elements of a die string (number of dice, die type, symbol & modifier) used by other functions to roll dice.
The cli function packages all of the above into an installable command line interface called 'dice', implementing the various types of rolls through the --kind option.
To install the command line interface, download the package, navigate to the root folder and issue the following command:
pip install --editable .
You may wish to create a virtual environment before doing this, ensuring the package does not experience dependency conflicts.
Also included is a dockerfile that will allow you to install the app in a containerised linux terminal if you so wish.

cli(diestring, kind) -> None

The entry point for the dice command line tool.
The dice command returns the total for a roll of a DIESTRING of the format XdY?Z, where:

• X is the number of dice to be rolled
• dY is the kind of die to roll, Y being the number of faces
• ? is an optional operator which applies a modifier to the roll total
• Z is an optional modifier applied to the roll total

If DIESTRING is 'scores', an array of 6 (4d6 - the lowest die) is returned.

--kind can be used to roll the DIESTRING with the following options:

• advan: roll twice, ordered high to low
• disad: roll twice, ordered low to high
• array: roll list of x dice
• crit: roll with double the dice
• stand: standard roll of dice (default option)

parse_die_string(string: str) -> Dict[str, Union[str, int]]:

Returns a dict of the constituents of a die roll from a given string.
Args:

• string (str): A string representing a die roll

Returns:

• parsed_roll: A dictionary of the roll string's elements.

roll_advantage(string: str) -> list[int]

Return two calls to roll_string sorted highest to lowest.
Args:

• string (str): A string of a roll of a number of dice with modifiers

Attributes:

• roll_list (list): A list of rolls sorted from highest [0] to lowest [1]

Returns:

• roll_list: A list of the roll result.

roll_array(string: str) -> list[int]

Return an array of a number of die rolls with modifiers.
Args:

• string (str): A string of die with modifiers to be rolled a number of times

Attributes:

• parsed_string (dict): A dictionary of the roll elements in the string
• num_dice (int): Int of the number of dice to be rolled, default 1
• die (str): String of type of die to be rolled
• symbol (str): String of operator to be appled, default +
• modifier (int): An int to be applied to roll with operator, default 0
• rolls (list): List of ints of all rolls with modifier applied to each

Returns:

• rolls: An array of ints of die rolls

roll_ability_scores() -> list[int]

Return a list of 6 4d6 minus the lowest for each group.
Attributes:

• ability_die(func): Returns the total of 4d6 minus the lowest die
• abilities (list): An array of ints of all the scores rolled

Returns:

• abilities: An array of 6 calls to ability_die sorted highest to lowest

roll_crit(string: str) -> int

Return an int of a roll with doubled dice and modifiers applied.
Args:

• string (str): A string of a roll of dice with modifiers

Attributes:

parsed_string (dict): A dictionary of the roll elements in the string

num_dice (int): Int of the number of dice to be rolled, default 1

die (str): String of type of die to be rolled

symbol (str): String of operator to be appled, default +

modifier (int): An int to be applied to roll with operator, default 0

Returns:

• roll: A int returned from a call to the roll_mult function.

roll_d(num: int) -> int

Return a random number between 1 and num.
Args:

• num (int): An int for the number of faces on the die

Returns:

• roll (int): Int of the the number rolled.

roll_disadvantage(string: str) -> list[int]

Return call to roll_advantage sorted lowest to highest.
Args:

• string (str): A string of a roll of a number of dice with modifiers

Attributes:

• roll_list (list): A list of rolls sorted from lowest [0] to highest [1]

Returns:

• roll_list: A list of the roll result.

roll_mult(num: int, die: str) -> int

Return a die or dice rolled a number of times.
Args:

• num (int): The number of dice to roll
• die (string): A string representing a die

Attributes:

• roll_total (int): An int for the total of all dice rolled
• faces (int): An int of the number of faces on the die

Returns:

• roll_total: The combined total of all dice rolls.