Class Reference

Looking for information on d20.Expression or d20.ast.Node? Check out Expression Tree for information on the Expression returned by a roll, or Abstract Syntax Tree for the AST returned by a parse.

Dice

class d20.Roller(context: RollContext | None = None)

The main class responsible for parsing dice into an AST and evaluating that AST.

context: d20.RollContext

The class used to track roll limits.

parse(expr: str, allow_comments: bool = False) → Expression

Parses a dice expression into an AST.

Parameters:

• expr (str) – The dice to roll.

• allow_comments (bool) – Whether to parse for comments after the main roll expression (potential slowdown)

Return type:

ast.Expression

roll(expr: str | ASTNode, stringifier: Stringifier | None = None, allow_comments: bool = False, advantage: AdvType = AdvType.NONE) → RollResult

Rolls the dice.

Parameters:

• expr (str or ast.Node) – The dice to roll.

• stringifier (d20.Stringifier) – The stringifier to stringify the result. Defaults to MarkdownStringifier.

• allow_comments (bool) – Whether to parse for comments after the main roll expression (potential slowdown)

• advantage (AdvType) – If the roll should be made at advantage. Only applies if the leftmost node is 1d20.

Return type:

RollResult

class d20.RollResult(the_ast: ASTNode, the_roll: Expression, stringifier: Stringifier)

Holds information about the result of a roll. This should generally not be constructed manually.

ast: d20.ast.Node

The abstract syntax tree of the dice expression that was rolled.

expr: d20.Expression

The Expression representation of the result of the roll.

total: int

The integer result of the roll (rounded towards 0).

result: str

The string result of the roll. Equivalent to stringifier.stringify(self.expr).

comment: str or None

If allow_comments was True and a comment was found, the comment. Otherwise, None.

property crit: CritType

If the leftmost node was Xd20kh1, returns CritType.CRIT if the roll was a 20 and CritType.FAIL if the roll was a 1. Returns CritType.NONE otherwise.

Return type:

CritType

class d20.RollContext(max_rolls=1000)

A class to track information about rolls to ensure all rolls halt eventually.

To use this class, pass an instance to the constructor of d20.Roller.

count_roll(n=1)

Called each time a die is about to be rolled.

Parameters:

n (int) – The number of rolls about to be made.

Raises:

d20.TooManyRolls – if the roller should stop rolling dice because too many have been rolled.

reset()

Called at the start of each new roll.

class d20.AdvType(value)

Integer enumeration representing at what advantage a roll should be made at.

NONE: int

Equivalent to 0. Represents no advantage.

ADV: int

Equivalent to 1. Represents advantage.

DIS: int

Equivalent to -1. Represents disadvantage.

class d20.CritType(value)

Integer enumeration representing the crit type of a roll.

NONE: int

Equivalent to 0. Represents no crit.

CRIT: int

Equivalent to 1. Represents a critical hit (a natural 20 on a d20).

FAIL: int

Equivalent to 2. Represents a critical fail (a natural 1 on a d20).

Stringifiers

class d20.Stringifier

ABC for string builder from dice result. Children should implement all _str_* methods to transform an Expression into a str.

stringify(the_roll: ExpressionNode) → str

Transforms a rolled expression into a string recursively, bottom-up.

Parameters:

the_roll (d20.Expression) – The expression to stringify.

Return type:

str

_stringify(node: ExpressionNode) → str

Called on each node that needs to be stringified.

Parameters:

node (d20.Number) – The node to stringify.

Return type:

str

_str_expression(node: Expression) → str

Parameters:

node (d20.Expression) – The node to stringify.

Return type:

str

_str_literal(node: Literal) → str

Parameters:

node (d20.Literal) – The node to stringify.

Return type:

str

_str_unop(node: UnOp) → str

Parameters:

node (d20.UnOp) – The node to stringify.

Return type:

str

_str_binop(node: BinOp) → str

Parameters:

node (d20.BinOp) – The node to stringify.

Return type:

str

_str_parenthetical(node: Parenthetical) → str

Parameters:

node (d20.Parenthetical) – The node to stringify.

Return type:

str

_str_set(node: Set) → str

Parameters:

node (d20.Set) – The node to stringify.

Return type:

str

_str_dice(node: Dice) → str

Parameters:

node (d20.Dice) – The node to stringify.

Return type:

str

_str_die(node: Die) → str

Parameters:

node (d20.Die) – The node to stringify.

Return type:

str

class d20.SimpleStringifier

Example stringifier.

class d20.MarkdownStringifier

Transforms roll expressions into Markdown.

Errors

class d20.RollError(msg)

Generic exception happened in the roll. Base exception for all library exceptions.

class d20.RollSyntaxError(line, col, got, expected)

Syntax error happened while parsing roll.

class d20.RollValueError(msg)

A bad value was passed to an operator.

class d20.TooManyRolls(msg)

Too many dice rolled (in an individual dice or in rerolls).