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=None)[source]

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, allow_comments=False)[source]

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, stringifier=None, allow_comments=False, advantage=<AdvType.NONE: 0>)[source]

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, the_roll, stringifier)[source]

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

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)[source]

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)[source]

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()[source]

Called at the start of each new roll.

class d20.AdvType[source]

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[source]

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[source]

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

stringify(the_roll)[source]

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

Parameters

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

Return type

str

_stringify(node)[source]

Called on each node that needs to be stringified.

Parameters

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

Return type

str

_str_expression(node)[source]
Parameters

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

Return type

str

_str_literal(node)[source]
Parameters

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

Return type

str

_str_unop(node)[source]
Parameters

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

Return type

str

_str_binop(node)[source]
Parameters

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

Return type

str

_str_parenthetical(node)[source]
Parameters

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

Return type

str

_str_set(node)[source]
Parameters

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

Return type

str

_str_dice(node)[source]
Parameters

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

Return type

str

_str_die(node)[source]
Parameters

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

Return type

str

class d20.SimpleStringifier[source]

Example stringifier.

class d20.MarkdownStringifier[source]

Transforms roll expressions into Markdown.

Errors

class d20.RollError(msg)[source]

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

class d20.RollSyntaxError(line, col, got, expected)[source]

Syntax error happened while parsing roll.

class d20.RollValueError(msg)[source]

A bad value was passed to an operator.

class d20.TooManyRolls(msg)[source]

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