Yahtzee: Public API Reference

Yahtzee

class yahtzee.yahtzee.Game(players: int = 1, dice: Optional[List[yahtzee.dice.Die]] = None, rules: Optional[List[yahtzee.scoring.rules.ScoringRule]] = None, bonuses: Optional[List[yahtzee.scoring.rules.BonusRule]] = None, yahtzee_bonus: Optional[yahtzee.scoring.rules.YahtzeeBonusRule] = None)

Bases: object

Representation of the full game.

Players

class yahtzee.players.Player(scoresheet: yahtzee.scoring.scoresheet.Scoresheet, dice: Optional[List[yahtzee.dice.Die]] = None, num_dice: int = 5, dice_sides: int = 6)

Bases: object

Representation of the player.

Parameters

scoresheet (Scoresheet) – A scoresheet of rules and bonuses for the player to score.
dice (list of Die, optional) – A set of dice for the player to roll. If omitted, a set will be generated based on num_dice and dice_sides.
num_dice (int, default 5) – Number of dice to generate for the player. Only used if dice is omitted.
dice_sides (int, default 6) – Number of sides to use for the generated dice. Only used if dice is omitted.

scoresheet

The player’s scoresheet, which houses rules and bonuses to be scored.

Type: Scoresheet

dice

A set of dice to be rolled by the player, and used for scoring rules and bonuses.

Type: list of Die

roll_dice(dice: List[int]) → None

Rolls the selected dice.

Parameters: dice (list of int) – Which dice the player should roll, expressed as the integers shown to the player in the CLI output.

Dice

class yahtzee.dice.Die(sides: int = 6, starting_face: Optional[int] = None)

Bases: object

Representation of a n-sided die.

Parameters

sides (int) – Number of sides the die should have. This will set faces as [1, …, n].
starting_face (int, optional) – Face value of the initial showing face of the die. Defaults to a random values from faces.

sides

Number of sides on the die.

Type: int

faces

Face values on the die.

Type: list of int

showing_face

The showing face of the die. The value that is used when the die is scored.

Type: int

Raises: IllegalDieValueError – If starting_face is not in faces.

roll() → None: Rolls the die, updating the showing face.

Rules

class yahtzee.scoring.rules.BonusRule(name: str, section: yahtzee.scoring.rules.Section, bonus_value: int, counter: int = 0, req_rules: Optional[List[yahtzee.scoring.rules.ScoringRule]] = None)

Bases: abc.ABC

Generic rule for scoring a bonus.

Parameters

name (str) – Name to identify the rule.
section (Section) – Section of the scoresheet which the rule belongs to.
bonus_value (int) – Value used to score the bonus. Depending on the specific type of bonus, this is either a constant score, or is multipled with a counter to get the total bonus score.
counter (int) – Tally used in scoring the bonus. Depending on the specific type of bonus, this is either compared against a threshold value, or is multiplied with the bonus_value to get the total bonus score.
req_rules (list of ScoringRule, optional) – Rules which influence the counter.

name

Name of the rule.

Type: str

section

Scoresheet section which the rule belongs to.

Type: Section

rule_score

Current scored value for the rule. Returns None until the rule is scored.

Type: int

bonus_value

Value used to score the bonus.

Type: int

counter

Tally used in scoring the bonus.

Type: int

req_rules

Rules which influence the counter.

Type: list of ScoringRule

increment(amt: int = 1) → None

Method to increment the internal counter.

Parameters: amt (int, default 1) – Amount by which to increment counter.

score() → None

Method to score a given bonus, and update the associated score value.

Raises: RuleAlreadyScoredError – If the rule has already been scored.

class yahtzee.scoring.rules.ChanceScoringRule(name: str, section: yahtzee.scoring.rules.Section = Section.LOWER)

Bases: yahtzee.scoring.rules.VariablePatternScoringRule

Rules which take any 5 dice.

Parameters

name (str) – Name to identify the rule.
section (Section, default LOWER) – Section of the scoresheet which the rule belongs to.

name

Name of the rule.

Type: str

section

Scoresheet section which the rule belongs to.

Type: Section

rule_score

Current scored value for the rule. Returns None until the rule is scored.

Type: int

validate(dice: List[Optional[yahtzee.dice.Die]]) → bool

Method to check that the desired pattern is present in the given dice. Always validates, since Chance can score for any dice.

Parameters: dice (list of Die) – A set of dice to check.
Returns: valid_dice – Whether the dice are valid for the given rule or not. Since a Chance is just scoring any set of dice, this will always return True.
Return type: bool

class yahtzee.scoring.rules.ConstantPatternScoringRule(name: str, section: yahtzee.scoring.rules.Section, score_value: int)

Bases: yahtzee.scoring.rules.ScoringRule

Generic scoring rule, which looks for a particular pattern, and has a constant score value.

Parameters

name (str) – Name to identify the rule.
section (Section) – Section of the scoresheet which the rule belongs to.
score_value (int) – The value of the rule if scored with a valid set of dice.

name

Name of the rule.

Type: str

section

Scoresheet section which the rule belongs to.

Type: Section

rule_score

Current scored value for the rule. Returns None until the rule is scored.

Type: int

score_value

The value of the rule if scored with a valid set of dice.

Type: int

class yahtzee.scoring.rules.CountBonusRule(name: str, section: yahtzee.scoring.rules.Section = Section.LOWER, bonus_value: int = 100, counter: int = 0, req_rules: Optional[List[yahtzee.scoring.rules.ScoringRule]] = None)

Bases: yahtzee.scoring.rules.BonusRule

Rule for a bonus which gives a point value per a count of something.

Parameters

name (str) – Name to identify the rule.
section (Section, default LOWER) – Section of the scoresheet which the rule belongs to.
bonus_value (int, default BONUS_LOWER_SCORE) – Value used to score the bonus. Depending on the specific type of bonus, this is either a constant score, or is multipled with a counter to get the total bonus score.
counter (int) – Tally used in scoring the bonus. Depending on the specific type of bonus, this is either compared against a threshold value, or is multiplied with the bonus_value to get the total bonus score.
req_rules (list of ScoringRule, optional) – Rules which influence the counter.

name

Name of the rule.

Type: str

section

Scoresheet section which the rule belongs to.

Type: Section

rule_score

Current scored value for the rule. Returns None until the rule is scored.

Type: int

bonus_value

Value used to score the bonus.

Type: int

counter

Tally used in scoring the bonus.

Type: int

req_rules

Rules which influence the counter.

Type: list of ScoringRule

class yahtzee.scoring.rules.FullHouseScoringRule(name: str, section: yahtzee.scoring.rules.Section = Section.LOWER, large_n: int = 3, small_n: int = 2, score_value: int = 25)

Bases: yahtzee.scoring.rules.ConstantPatternScoringRule

Rules which look for a full house (m-of-a-kind and n-of-a-kind, m > n).

Parameters

name (str) – Name to identify the rule.
section (Section, default LOWER) – Section of the scoresheet which the rule belongs to.
score_value (int, default SCORE_FULL_HOUSE) – The value of the rule if scored with a valid set of dice.
large_n (int, default 3) – N for the larger n-of-a-kind required for the full house.
small_n (int, default 2) – N for the smaller n-of-a-kind required for the full house.

name

Name of the rule.

Type: str

section

Scoresheet section which the rule belongs to.

Type: Section

rule_score

Current scored value for the rule. Returns None until the rule is scored.

Type: int

score_value

The value of the rule if scored with a valid set of dice.

Type: int

large_n

N for the larger n-of-a-kind required for the full house.

Type: int

small_n

N for the smaller n-of-a-kind required for the full house.

Type: int

validate(dice: List[Optional[yahtzee.dice.Die]]) → bool

Method to check that the desired pattern is present in the given dice. Validates if a full house (m-of-a-kind and n-of-a-kind, m > n) is present.

Parameters: dice (list of Die) – A set of dice to check.
Returns: valid_dice – Whether the dice are valid for the given rule or not. Returns True if an two n-of-a-kinds are present, of sizes large_n and small_n.
Return type: bool

class yahtzee.scoring.rules.LargeStraightScoringRule(name: str, section: yahtzee.scoring.rules.Section = Section.LOWER, score_value: int = 40)

Bases: yahtzee.scoring.rules.ConstantPatternScoringRule

Rules which look for a large straight (5 dice sequence).

Parameters

name (str) – Name to identify the rule.
section (Section, default LOWER) – Section of the scoresheet which the rule belongs to.
score_value (int, default SCORE_LARGE_STRAIGHT) – The value of the rule if scored with a valid set of dice.

name

Name of the rule.

Type: str

section

Scoresheet section which the rule belongs to.

Type: Section

rule_score

Current scored value for the rule. Returns None until the rule is scored.

Type: int

score_value

The value of the rule if scored with a valid set of dice.

Type: int

validate(dice: List[Optional[yahtzee.dice.Die]]) → bool

Method to check that the desired pattern is present in the given dice. Validates if a large straight (5 consecutive values in 5 dice) is present.

Parameters: dice (list of Die) – A set of dice to check.
Returns: valid_dice – Whether the dice are valid for the given rule or not. Returns True if all dice are sequential and unique.
Return type: bool

class yahtzee.scoring.rules.MultiplesScoringRule(name: str, face_value: int, section: yahtzee.scoring.rules.Section = Section.UPPER)

Bases: yahtzee.scoring.rules.VariablePatternScoringRule

Rules which look for multiple dice with a specific face value.

Parameters

name (str) – Name to identify the rule.
section (Section, default UPPER) – Section of the scoresheet which the rule belongs to.
face_value (int) – Face value needed on a die to be counted in this rule’s score.

name

Name of the rule.

Type: str

section

Scoresheet section which the rule belongs to.

Type: Section

rule_score

Current scored value for the rule. Returns None until the rule is scored.

Type: int

face_value

Face value needed on a die to be counted in this rule’s score.

Type: int

validate(dice: List[Optional[yahtzee.dice.Die]]) → bool

Method to check that the desired pattern is present in the given dice. Always validates, since Multiples can score for any dice.

Parameters: dice (list of Die) – A set of dice to check.
Returns: valid_dice – Whether the dice are valid for the given rule or not. Since a Multiple will naturally score 0 with no matching dice, this will always return True.
Return type: bool

class yahtzee.scoring.rules.NofKindScoringRule(name: str, n: int, section: yahtzee.scoring.rules.Section = Section.LOWER)

Bases: yahtzee.scoring.rules.VariablePatternScoringRule

Rules which look for n-of-a-kind of a face value, without explicitly specifying the desired face value.

Parameters

name (str) – Name to identify the rule.
section (Section, default LOWER) – Section of the scoresheet which the rule belongs to.
n (int) – Number of matching dice needed for this rule - the “n” in “n-of-a-kind”.

name

Name of the rule.

Type: str

section

Scoresheet section which the rule belongs to.

Type: Section

rule_score

Current scored value for the rule. Returns None until the rule is scored.

Type: int

n

Number of matching dice needed for this rule - the “n” in “n-of-a-kind”.

Type: int

validate(dice: List[Optional[yahtzee.dice.Die]]) → bool

Method to check that the desired pattern is present in the given dice. Validates if an n-of-a-kind is present, or if any m-of-a-kind is present (m > n).

Parameters: dice (list of Die) – A set of dice to check.
Returns: valid_dice – Whether the dice are valid for the given rule or not. Since m-of-a-kinds (m > n) are still valid for a given n, returns True if any m-of-a-kind is present, m >= n.
Return type: bool

class yahtzee.scoring.rules.ScoringRule(name: str, section: yahtzee.scoring.rules.Section)

Bases: abc.ABC

Generic scoring rule.

Parameters

name (str) – Name to identify the rule.
section (Section) – Section of the scoresheet which the rule belongs to.

name

Name of the rule.

Type: str

section

Scoresheet section which the rule belongs to.

Type: Section

rule_score

Current scored value for the rule. Returns None until the rule is scored.

Type: int

score(dice: List[Optional[yahtzee.dice.Die]]) → None

Method to score a given set of dice.

Parameters: dice (list of Die) – A set of dice to score.

abstract validate(dice: List[Optional[yahtzee.dice.Die]]) → bool

Method to check that a desired pattern or other trait is present in the given dice.

Parameters: dice (list of Die) – A set of dice to check.
Returns: valid_dice – Whether the dice are valid for the given rule or not.
Return type: bool

class yahtzee.scoring.rules.Section(value)

Bases: enum.Enum

Values for the sections of the scoresheet, used to organize different rules and bonuses.

LOWER: str = 'lower'

UPPER: str = 'upper'

class yahtzee.scoring.rules.SmallStraightScoringRule(name: str, section: yahtzee.scoring.rules.Section = Section.LOWER, score_value: int = 30)

Bases: yahtzee.scoring.rules.ConstantPatternScoringRule

Rules which look for a small straight (4 dice sequence).

Parameters

name (str) – Name to identify the rule.
section (Section, default LOWER) – Section of the scoresheet which the rule belongs to.
score_value (int, default SCORE_SMALL_STRAIGHT) – The value of the rule if scored with a valid set of dice.

name

Name of the rule.

Type: str

section

Scoresheet section which the rule belongs to.

Type: Section

rule_score

Current scored value for the rule. Returns None until the rule is scored.

Type: int

score_value

The value of the rule if scored with a valid set of dice.

Type: int

validate(dice: List[Optional[yahtzee.dice.Die]]) → bool

Method to check that the desired pattern is present in the given dice. Validates if a small straight (4 consecutive values in 5 dice) is present.

Parameters: dice (list of Die) – A set of dice to check.
Returns: valid_dice – Whether the dice are valid for the given rule or not. Returns True if all-but-one of the dice are sequential and unique.
Return type: bool

class yahtzee.scoring.rules.ThresholdBonusRule(name: str, section: yahtzee.scoring.rules.Section = Section.UPPER, threshold: int = 63, bonus_value: int = 35, counter: int = 0, req_rules: Optional[List[yahtzee.scoring.rules.ScoringRule]] = None)

Bases: yahtzee.scoring.rules.BonusRule

Rule for a bonus of which gives points for exceeding a threshold.

Parameters

name (str) – Name to identify the rule.
section (Section, default UPPER) – Section of the scoresheet which the rule belongs to.
bonus_value (int, default BONUS_UPPER_SCORE) – Value used to score the bonus. Depending on the specific type of bonus, this is either a constant score, or is multipled with a counter to get the total bonus score.
counter (int) – Tally used in scoring the bonus. Depending on the specific type of bonus, this is either compared against a threshold value, or is multiplied with the bonus_value to get the total bonus score.
req_rules (list of ScoringRule, optional) – Rules which influence the counter.
threshold (int, default BONUS_UPPER_THRESHOLD) – Threshold to determine if bonus is awarded.

name

Name of the rule.

Type: str

section

Scoresheet section which the rule belongs to.

Type: Section

rule_score

Current scored value for the rule. Returns None until the rule is scored.

Type: int

bonus_value

Value used to score the bonus.

Type: int

counter

Tally used in scoring the bonus.

Type: int

req_rules

Rules which influence the counter.

Type: list of ScoringRule

threshold

Threshold to determine if bonus is awarded.

Type: int

class yahtzee.scoring.rules.VariablePatternScoringRule(name: str, section: yahtzee.scoring.rules.Section)

Bases: yahtzee.scoring.rules.ScoringRule

Generic scoring rule, which looks for a particular pattern, and has a variable score value.

Parameters

name (str) – Name to identify the rule.
section (Section) – Section of the scoresheet which the rule belongs to.

name

Name of the rule.

Type: str

section

Scoresheet section which the rule belongs to.

Type: Section

rule_score

Current scored value for the rule. Returns None until the rule is scored.

Type: int

class yahtzee.scoring.rules.YahtzeeBonusRule(name: str, yahtzee_rule: yahtzee.scoring.rules.YahtzeeScoringRule, bonus_value: int = 100, section: yahtzee.scoring.rules.Section = Section.LOWER, counter: int = 0)

Bases: yahtzee.scoring.rules.CountBonusRule

Counting bonus rule, specifically for additional Yahtzees rolled after a YahtzeeScoringRule has been scored.

Parameters

name (str) – Name to identify the rule.
section (Section, default LOWER) – Section of the scoresheet which the rule belongs to.
bonus_value (int, default BONUS_YAHTZEE_SCORE) – Value used to score the bonus. Depending on the specific type of bonus, this is either a constant score, or is multipled with a counter to get the total bonus score.
counter (int) – Tally used in scoring the bonus. Depending on the specific type of bonus, this is either compared against a threshold value, or is multiplied with the bonus_value to get the total bonus score.
req_rules (list of ScoringRule, optional) – Rules which influence the counter.
yahtzee_rule (YahtzeeScoringRule) – The Yahtzee rule associated with the bonus. Used to check if a Yahtzee has already been scored, which impacts how the bonus is scored.

name

Name of the rule.

Type: str

section

Scoresheet section which the rule belongs to.

Type: Section

rule_score

Current scored value for the rule. Returns None until the rule is scored.

Type: int

bonus_value

Value used to score the bonus.

Type: int

counter

Tally used in scoring the bonus.

Type: int

req_rules

Rules which influence the counter.

Type: list of ScoringRule

yahtzee_rule

The Yahtzee rule associated with the bonus.

Type: YahtzeeScoringRule

class yahtzee.scoring.rules.YahtzeeScoringRule(name: str, section: yahtzee.scoring.rules.Section = Section.LOWER, score_value: int = 50)

Bases: yahtzee.scoring.rules.ConstantPatternScoringRule

Rules which look for a Yahtzee (5-of-a-kind).

Parameters

name (str) – Name to identify the rule.
section (Section, default LOWER) – Section of the scoresheet which the rule belongs to.
score_value (int, default SCORE_YAHTZEE) – The value of the rule if scored with a valid set of dice.

name

Name of the rule.

Type: str

section

Scoresheet section which the rule belongs to.

Type: Section

rule_score

Current scored value for the rule. Returns None until the rule is scored.

Type: int

score_value

The value of the rule if scored with a valid set of dice.

Type: int

validate(dice: List[Optional[yahtzee.dice.Die]]) → bool

Method to check that the desired pattern is present in the given dice. Validates if a Yahtzee (5-of-a-kind) is present.

Parameters: dice (list of Die) – A set of dice to check.
Returns: valid_dice – Whether the dice are valid for the given rule or not. Returns True if all dice are the same.
Return type: bool

Scoresheet

class yahtzee.scoring.scoresheet.Scoresheet(rules: List[yahtzee.scoring.rules.ScoringRule], bonuses: List[yahtzee.scoring.rules.BonusRule], yahtzee_bonus: yahtzee.scoring.rules.YahtzeeBonusRule)

Bases: object

Representation of a scoring sheet.

Parameters

rules (list of ScoringRule) – Rules to include on the sheet.
bonuses (list of BonusRule) – Bonuses to include on the sheet
yahtzee_bonus (YahtzeeBonusRule) – Bonus rule for additional Yahtzees to include on the sheet.

rules

Rules to include on the sheet.

Type: list of ScoringRule

bonuses

Bonuses to include on the sheet

Type: list of BonusRule

yahtzee_bonus

Bonus rule for additional Yahtzees to include on the sheet.

Type: YahtzeeBonusRule

rules_map

Mapping of display number to rule, to help with user selections in the CLI.

Type: dict of int, ScoringRule

output() → str

Gives the full scoresheet.

Returns: scoresheet – The full scoresheet, in a well-formatted tabular format.
Return type: str

update_score(index: int, dice: List[Optional[yahtzee.dice.Die]]) → None

Updates the score for a rule, chosen by user input, based on the given dice. Also updates any associated bonus rules.

Parameters

index (int) – Index of rule to update, from the user input via CLI.
dice (list of Die) – Set of dice to score.

update_yahtzee_bonus(amt: int = 1) → None

Increments the counter of the yahtzee bonus rule.

Parameters: amt (int, default 1) – Amount of additional Yahtzees to add to the yahtzee_bonus.

Validators

yahtzee.scoring.validators.find_duplicates(values: List) → List

Finds any duplicate values in a list.

Parameters: values (list) – Values to check.
Returns: duplicates – List of duplicates, if any.
Return type: list

yahtzee.scoring.validators.find_matching_dice(dice: List[Optional[yahtzee.dice.Die]], face_value: int) → List[Optional[yahtzee.dice.Die]]

Helper to find dice with the expected face value.

Parameters

dice (list of Die) – Set of dice to check.
face_value (int) – Value to check for in dice.

Returns

matching_dice – List of dice whose showing_face matched face_value, if any.

Return type

list of Die

yahtzee.scoring.validators.validate_full_house(dice: List[Optional[yahtzee.dice.Die]], large_n: int, small_n: int) → bool

Helper to check for a full house (2 n-of-a-kind, large_n > small_n).

Parameters

dice (list of Die) – Set of dice to check.
large_n (int) – What size n-of-a-kind to check for, as the larger n-of-a-kind.
small_n (int) – What size n-of-a-kind to check for, as the smaller n-of-a-kind.

Returns

is_full_house – Whether a full house is present in dice.

Return type

bool

Raises

RuleInputValueError – If small_n is greater than (or equal to) large_n.

yahtzee.scoring.validators.validate_large_straight(dice: List[Optional[yahtzee.dice.Die]]) → bool

Helper to check for a large straight (5 length sequence from pool of 5, in order, no missing values).

Parameters: dice (list of Die) – Set of dice to check.
Returns: is_large_straight – Whether dice form a large straight. All dice must be in the straight, with no duplicates.
Return type: bool

yahtzee.scoring.validators.validate_nofkind(dice: List[Optional[yahtzee.dice.Die]], n: int) → bool

Helper to check for n-of-a-kind for a given n.

Parameters

dice (list of Die) – Set of dice to check.
n (int) – What size n-of-a-kind to check for.

Returns

is_nofkind – Whether an n-of-a-kind (size n) is present in dice.

Return type

bool

yahtzee.scoring.validators.validate_small_straight(dice: List[Optional[yahtzee.dice.Die]]) → bool

Helper to check for a small straight (4 length sequence from pool of 5, in order, no missing values).

Parameters: dice (list of Die) – Set of dice to check.
Returns: is_small_straight – Whether any combination of n-1 of values in dice form a small straight. All dice in the subset must be in the straight, with no duplicates. The last die (not in the valid subset) may have any value.
Return type: bool

yahtzee.scoring.validators.validate_straight(values: List[int]) → bool

Helper to check for a straight (any length sequence, in order, no missing middle values).

Parameters: values (list of int) – Values to check.
Returns: is_straight – Whether values form a straight. All values must be in the straight, with no duplicates.
Return type: bool

Errors

exception yahtzee.errors.DuplicateRuleNamesError

Bases: ValueError

Raised when duplicate rule names are submitted in the same scoresheet.

exception yahtzee.errors.IllegalDieValueError

Bases: ValueError

Raised when an illegal face value is set for a die.

exception yahtzee.errors.RuleAlreadyScoredError

Bases: ValueError

Raised when attempting to score a previously-scored rule.

exception yahtzee.errors.RuleInputValueError

Bases: ValueError

Raised when rule parameters are supplied improperly.