Tarot

A Rider-Waite-Smith tarot engine with a 78-card deck, single-card and three-card spreads, and optional reversals.

from fortune_telling_core import RandomRng, ReadingRequest
from fortune_telling_core.traditions.tarot import RWS_DECK, THREE_CARD, build_engine

engine = build_engine()
request = ReadingRequest(
    deck_id=RWS_DECK.id,
    spread_id=THREE_CARD.id,
    options={"allow_reversals": "true"},
)

reading = engine.read(request, rng=RandomRng(seed=20260612))

tarot

RWS_DECK module-attribute

RWS_DECK = Deck(
    id="tarot.rws.v1",
    symbols=_major_symbols() + _minor_symbols(),
)

SINGLE_CARD module-attribute

SINGLE_CARD = Spread(
    id="tarot.spread.single.v1",
    name="Single Card",
    positions=(
        Position(
            id="focus",
            name="Focus",
            description="The central message for the reading.",
        ),
    ),
)

THREE_CARD module-attribute

THREE_CARD = Spread(
    id="tarot.spread.three-card.v1",
    name="Past, Present, Future",
    positions=(
        Position(
            id="past",
            name="Past",
            description="The relevant background.",
        ),
        Position(
            id="present",
            name="Present",
            description="The current influence.",
        ),
        Position(
            id="future",
            name="Future",
            description="The likely direction.",
        ),
    ),
)

TarotEngine

Bases: AbstractEngine

Reference Rider-Waite-Smith tarot engine.

The engine supports the bundled Rider-Waite-Smith deck, single-card and three-card spreads, and optional reversals through the request option allow_reversals=true.

id class-attribute instance-attribute

id = 'tarot.rws.engine'

version class-attribute instance-attribute

version = '0.1.0'

deck

deck(request: ReadingRequest) -> Deck

Return the Rider-Waite-Smith deck for a request.

Parameters:

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

Returns:

Type	Description
Deck	The bundled Rider-Waite-Smith deck.

Raises:

Type	Description
ValidationError	If the request names an unsupported deck.

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

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

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

    Returns:
        The bundled Rider-Waite-Smith deck.

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

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

spread

spread(request: ReadingRequest) -> Spread

Return the tarot spread requested by id.

Parameters:

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

Returns:

Type	Description
Spread	SINGLE_CARD or THREE_CARD.

Raises:

Type	Description
ValidationError	If the spread is not supported.

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

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

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

    Returns:
        ``SINGLE_CARD`` or ``THREE_CARD``.

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

    if request.spread_id == SINGLE_CARD.id:
        return SINGLE_CARD
    if request.spread_id == THREE_CARD.id:
        return THREE_CARD
    raise ValidationError(f"unsupported tarot spread: {request.spread_id}")

draw

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

Draw cards for the requested tarot spread.

Parameters:

Name	Type	Description	Default
request	ReadingRequest	Reading request. Set options={"allow_reversals": "true"} to include orientation modifiers.	required
rng	Rng	Random source used to shuffle the deck and choose reversals.	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/tarot/engine.py

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

    Args:
        request: Reading request. Set ``options={"allow_reversals":
            "true"}`` to include orientation modifiers.
        rng: Random source used to shuffle the deck and choose reversals.

    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))
    allow_reversals = (
        request.options.get("allow_reversals") == "true" if request.options else False
    )

    selections: list[Selection] = []
    for position, symbol_index in zip(spread.positions, order[: spread.size], strict=True):
        modifiers: dict[str, str] = {}
        if allow_reversals:
            modifiers["orientation"] = "reversed" if rng.random() < 0.5 else "upright"
        selections.append(
            Selection(
                position_id=position.id,
                symbol_id=deck.symbols[symbol_index].id,
                modifiers=modifiers,
            )
        )

    return Draw(deck_id=deck.id, spread_id=spread.id, selections=tuple(selections))

build_engine

build_engine() -> TarotEngine

Create a Rider-Waite-Smith tarot engine.

Returns:

Type	Description
TarotEngine	A new TarotEngine instance.

Example

from fortune_telling_core.traditions.tarot import build_engine

engine = build_engine()

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

def build_engine() -> TarotEngine:
    """Create a Rider-Waite-Smith tarot engine.

    Returns:
        A new ``TarotEngine`` instance.

    Example:
        ```python
        from fortune_telling_core.traditions.tarot import build_engine

        engine = build_engine()
        ```
    """

    return TarotEngine()