API Reference

dominion_setup Package

dominion-setup is a Python library and CLI tool to set up a game of Dominion, the classic deck-building game.

class dominion_setup.CardDatabase(cards)

Bases: object

All loaded card data, indexed for fast lookup.

get_cards_by_set_edition(set_, edition)

Return all kingdom cards belonging to the given set and edition.

get_cards_by_type(card_type)

Return all kingdom cards that include the given type.

get_cards_by_cost(card_cost)

Return all kingdom cards of the given cost.

class dominion_setup.CardSet(*values)

Bases: StrEnum

Card sets – the base game along with all expansions and promotional cards.

class dominion_setup.Game(basic_piles, kingdom_piles, non_supply_piles=<factory>, landscapes=<factory>, ally=None, prophecy=None, druid_boons=<factory>, materials=<factory>, setup_instructions=<factory>)

Bases: object

Complete output representing a ready-to-play Dominion setup.

property basic_cards: list[Card]

The Cards in basic_piles, dropping marks.

property kingdom_cards: list[Card]

The Cards in kingdom_piles, dropping marks.

property non_supply_cards: list[Card]

The Cards in non_supply_piles, dropping marks.

class dominion_setup.KingdomSortOrder(*values)

Bases: StrEnum

Sort order for kingdom piles in the game output.

class dominion_setup.Pile(card, marks=())

Bases: object

A pile of a single card, optionally decorated with marks (Bane, Obelisk, Trait, …).

class dominion_setup.PileMark(kind, trait=None)

Bases: object

An annotation attached to a Pile.

class dominion_setup.PileMarkKind(*values)

Bases: StrEnum

Kinds of annotations that can decorate a Pile.

dominion_setup.generate_game(db, *, sets_editions=None, sort_order=KingdomSortOrder.COST, use_colony=None, use_shelters=None, max_landscapes=2)

Generate a complete, rules-accurate Dominion game setup.

Parameters:

  • db (CardDatabase) – The loaded card database.

  • sets_editions (set[tuple[CardSet, CardSetEdition]] | None) – Which sets and editions to draw kingdom cards from. Defaults to all sets and editions in the database.

  • sort_order (KingdomSortOrder) – How to sort the kingdom piles in the output. Defaults to KingdomSortOrder.COST.

  • use_colony (bool | None) – Force Platinum/Colony on or off. None uses the standard random determination based on Prosperity cards.

  • use_shelters (bool | None) – Force Shelters on or off. None uses the standard random determination based on Dark Ages cards.

  • max_landscapes (int) – Maximum number of landscapes to include. Defaults to 2.

Returns:

A Game object with selected Kingdom piles and basic supply.

Return type:

Game

dominion_setup.load_card_database(data_dir=None)

Load all card data from JSON files and return a populated CardDatabase.

Parameters:

data_dir (Path | None) – Optional path to the data directory. Defaults to the package’s bundled data directory.

Returns:

A CardDatabase containing all base cards and kingdom cards.

Return type:

CardDatabase

dominion_setup.cli Module

Main CLI for dominion-setup.

class dominion_setup.cli.RichDefaultGroup(*args, **kwargs)

Bases: DefaultGroup, RichGroup

DefaultGroup with Rich-formatted help output.

dominion_setup.generator Module

Generate a complete Dominion game setup.

dominion_setup.generator.generate_game(db, *, sets_editions=None, sort_order=KingdomSortOrder.COST, use_colony=None, use_shelters=None, max_landscapes=2)

Generate a complete, rules-accurate Dominion game setup.

Parameters:

  • db (CardDatabase) – The loaded card database.

  • sets_editions (set[tuple[CardSet, CardSetEdition]] | None) – Which sets and editions to draw kingdom cards from. Defaults to all sets and editions in the database.

  • sort_order (KingdomSortOrder) – How to sort the kingdom piles in the output. Defaults to KingdomSortOrder.COST.

  • use_colony (bool | None) – Force Platinum/Colony on or off. None uses the standard random determination based on Prosperity cards.

  • use_shelters (bool | None) – Force Shelters on or off. None uses the standard random determination based on Dark Ages cards.

  • max_landscapes (int) – Maximum number of landscapes to include. Defaults to 2.

Returns:

A Game object with selected Kingdom piles and basic supply.

Return type:

Game

dominion_setup.loader Module

Load card data from JSON files into a CardDatabase.

dominion_setup.loader.load_card_database(data_dir=None)

Load all card data from JSON files and return a populated CardDatabase.

Parameters:

data_dir (Path | None) – Optional path to the data directory. Defaults to the package’s bundled data directory.

Returns:

A CardDatabase containing all base cards and kingdom cards.

Return type:

CardDatabase

dominion_setup.models Module

Domain models for Dominion game setup.

class dominion_setup.models.CardType(*values)

Bases: StrEnum

Card types in the game.

class dominion_setup.models.CardPurpose(*values)

Bases: StrEnum

Card purposes in the game.

class dominion_setup.models.CardCost(coins=0, potion=False, debt=0, extra=None)

Bases: object

Card cost, supporting coins and Potion.

classmethod from_dict(data)

Create a Cost from a JSON-derived dictionary.

class dominion_setup.models.CardSet(*values)

Bases: StrEnum

Card sets – the base game along with all expansions and promotional cards.

class dominion_setup.models.CardSetEdition(*values)

Bases: IntEnum

Card set editions.

class dominion_setup.models.Card(name, types, purpose, cost, set, editions, quantity, image, instructions)

Bases: object

A single card definition loaded from JSON.

classmethod from_dict(data)

Create a Card from a JSON-derived dictionary.

class dominion_setup.models.Material(*values)

Bases: StrEnum

Materials other than cards or “card-shaped things”.

class dominion_setup.models.PileMarkKind(*values)

Bases: StrEnum

Kinds of annotations that can decorate a Pile.

class dominion_setup.models.PileMark(kind, trait=None)

Bases: object

An annotation attached to a Pile.

class dominion_setup.models.Pile(card, marks=())

Bases: object

A pile of a single card, optionally decorated with marks (Bane, Obelisk, Trait, …).

class dominion_setup.models.Game(basic_piles, kingdom_piles, non_supply_piles=<factory>, landscapes=<factory>, ally=None, prophecy=None, druid_boons=<factory>, materials=<factory>, setup_instructions=<factory>)

Bases: object

Complete output representing a ready-to-play Dominion setup.

property basic_cards: list[Card]

The Cards in basic_piles, dropping marks.

property kingdom_cards: list[Card]

The Cards in kingdom_piles, dropping marks.

property non_supply_cards: list[Card]

The Cards in non_supply_piles, dropping marks.

class dominion_setup.models.CardDatabase(cards)

Bases: object

All loaded card data, indexed for fast lookup.

get_cards_by_set_edition(set_, edition)

Return all kingdom cards belonging to the given set and edition.

get_cards_by_type(card_type)

Return all kingdom cards that include the given type.

get_cards_by_cost(card_cost)

Return all kingdom cards of the given cost.

class dominion_setup.models.KingdomSortOrder(*values)

Bases: StrEnum

Sort order for kingdom piles in the game output.

dominion_setup.utils Module

Utility functions for Dominion game setup.

class dominion_setup.utils.SupportsBool(*args, **kwargs)

Bases: Protocol

An ABC with one abstract method __bool__.

class dominion_setup.utils.SupportsDunderLT(*args, **kwargs)

Bases: Protocol[_T_contra]

An ABC with one abstract method __lt__.

class dominion_setup.utils.SupportsDunderGT(*args, **kwargs)

Bases: Protocol[_T_contra]

An ABC with one abstract method __gt__.

dominion_setup.utils.card_sort_key(sort_order)

Return a sort-key function for the given kingdom sort order.

dominion_setup.utils.parse_raw_set_edition(raw_set_edition)

Parse a raw Set-Edition string (e.g., “base_2e”) into a (CardSet, CardSetEdition) 2-tuple.

Handles multi-word expansion names like cornucopia_guilds_2e by stripping the known edition suffix first.