Dominoes

A domino-divination engine with the 28-tile double-six deck plus single-tile and three-tile spreads. Casting is RNG-driven: pass an Rng to read.

from fortune_telling_core import RandomRng, ReadingRequest
from fortune_telling_core.traditions.dominoes import DOMINOES_DECK, THREE_TILES, build_engine

request = ReadingRequest(deck_id=DOMINOES_DECK.id, spread_id=THREE_TILES.id)
reading = build_engine().read(request, rng=RandomRng(seed=42))

dominoes

DOMINOES_DECK module-attribute

DOMINOES_DECK = Deck(
    id="dominoes.deck.double-six.v1",
    symbols=tuple(
        (
            Symbol(
                id=tile.symbol_id,
                name=tile.name,
                attributes={
                    "high": str(tile.high),
                    "low": str(tile.low),
                    "pips": str(tile.pips),
                    "double": "true"
                    if tile.double
                    else "false",
                },
            )
        )
        for tile in TILES
    ),
)

SINGLE_TILE module-attribute

SINGLE_TILE = Spread(
    id="dominoes.spread.single.v1",
    name="Single Tile",
    positions=(
        Position(
            "tile",
            "Tile",
            "The drawn tile answering the question.",
        ),
    ),
)

THREE_TILES module-attribute

THREE_TILES = Spread(
    id="dominoes.spread.three.v1",
    name="Three Tiles",
    positions=(
        Position(
            "past", "Past", "The relevant background."
        ),
        Position(
            "present", "Present", "The current influence."
        ),
        Position(
            "future", "Future", "The likely direction."
        ),
    ),
)

DominoesEngine

Bases: AbstractEngine

Domino divination engine.

The engine shuffles the 28-tile double-six set and draws into a single-tile or three-tile spread. Tiles carry no orientation.

id class-attribute instance-attribute

id = 'dominoes.engine'

version class-attribute instance-attribute

version = '0.1.0'

deck

deck(request: ReadingRequest) -> Deck

Return the domino deck for a request.

Parameters:

Name	Type	Description	Default
request	ReadingRequest	Reading request whose deck_id must match DOMINOES_DECK.id.	required

Returns:

Type	Description
Deck	The bundled domino deck.

Raises:

Type	Description
ValidationError	If the request names an unsupported deck.

Source code in src/fortune_telling_core/traditions/dominoes/engine.py

def deck(self, request: ReadingRequest) -> Deck:
    """Return the domino deck for a request.

    Args:
        request: Reading request whose ``deck_id`` must match
            ``DOMINOES_DECK.id``.

    Returns:
        The bundled domino deck.

    Raises:
        ValidationError: If the request names an unsupported deck.
    """

    if request.deck_id != DOMINOES_DECK.id:
        raise ValidationError(f"unsupported domino deck: {request.deck_id}")
    return DOMINOES_DECK

spread

spread(request: ReadingRequest) -> Spread

Return the domino spread requested by id.

Parameters:

Name	Type	Description	Default
request	ReadingRequest	Reading request whose spread_id selects a bundled spread.	required

Returns:

Type	Description
Spread	SINGLE_TILE or THREE_TILES.

Raises:

Type	Description
ValidationError	If the spread is not supported.

Source code in src/fortune_telling_core/traditions/dominoes/engine.py

def spread(self, request: ReadingRequest) -> Spread:
    """Return the domino spread requested by id.

    Args:
        request: Reading request whose ``spread_id`` selects a bundled
            spread.

    Returns:
        ``SINGLE_TILE`` or ``THREE_TILES``.

    Raises:
        ValidationError: If the spread is not supported.
    """

    spread = _SPREADS.get(request.spread_id)
    if spread is None:
        raise ValidationError(f"unsupported domino spread: {request.spread_id}")
    return spread

draw

draw(request: ReadingRequest, rng: Rng) -> Draw

Draw tiles for the requested spread.

Parameters:

Name	Type	Description	Default
request	ReadingRequest	Reading request.	required
rng	Rng	Random source used to shuffle the set.	required

Returns:

Type	Description
Draw	A draw containing one selection per spread position.

Raises:

Type	Description
ValidationError	If the requested deck or spread is unsupported.
ExhaustedRngError	If the supplied RNG cannot provide enough values.

Source code in src/fortune_telling_core/traditions/dominoes/engine.py

def draw(self, request: ReadingRequest, rng: Rng) -> Draw:
    """Draw tiles for the requested spread.

    Args:
        request: Reading request.
        rng: Random source used to shuffle the set.

    Returns:
        A draw containing one selection per spread position.

    Raises:
        ValidationError: If the requested deck or spread is unsupported.
        ExhaustedRngError: If the supplied RNG cannot provide enough values.
    """

    deck = self.deck(request)
    spread = self.spread(request)
    order = rng.shuffle(len(deck.symbols))
    selections = tuple(
        Selection(position_id=position.id, symbol_id=deck.symbols[symbol_index].id)
        for position, symbol_index in zip(spread.positions, order[: spread.size], strict=True)
    )
    return Draw(deck_id=deck.id, spread_id=spread.id, selections=selections)

build_engine

build_engine() -> DominoesEngine

Create a domino divination engine.

Returns:

Type	Description
DominoesEngine	A new DominoesEngine instance.

Source code in src/fortune_telling_core/traditions/dominoes/engine.py

def build_engine() -> DominoesEngine:
    """Create a domino divination engine.

    Returns:
        A new ``DominoesEngine`` instance.
    """

    return DominoesEngine()