Maya Tzolk'in

A Maya Tzolk'in (260-day sacred round) engine that deterministically derives a querent's Tzolk'in day — a trecena number (1-13) paired with one of twenty day signs — from their birth date. The cycle uses the GMT (584283) correlation, anchored at 21 December 2012 = 4 Ajaw.

from fortune_telling_core import Querent, ReadingRequest
from fortune_telling_core.traditions.tzolkin import TZOLKIN_DECK, TZOLKIN_SPREAD, build_engine

request = ReadingRequest(
    deck_id=TZOLKIN_DECK.id,
    spread_id=TZOLKIN_SPREAD.id,
    querent=Querent(
        id="sample",
        display_name="Sample",
        attributes={"birth_datetime": "2012-12-21T00:00:00+00:00"},
    ),
)
reading = build_engine().cast(request)

tzolkin

TZOLKIN_DECK module-attribute

TZOLKIN_DECK = Deck(
    id="tzolkin.deck.daysigns.v1",
    symbols=tuple(
        (
            Symbol(
                id=sign.symbol_id,
                name=sign.name,
                attributes={
                    "slug": sign.slug,
                    "cycle_index": str(sign.index),
                    "keyword": sign.keyword,
                    "direction": sign.direction,
                },
            )
        )
        for sign in DAYSIGNS
    ),
)

TZOLKIN_SPREAD module-attribute

TZOLKIN_SPREAD = Spread(
    id="tzolkin.spread.birth.v1",
    name="Tzolk'in",
    positions=(
        Position(
            "day_sign",
            "Day Sign",
            "Tzolk'in day sign with its trecena number.",
        ),
    ),
)

TzolkinEngine

Bases: AbstractEngine

Maya Tzolk'in (260-day sacred round) engine.

The engine deterministically derives a querent's Tzolk'in day — a trecena number (1-13) paired with one of twenty day signs — from their birth date, using the GMT (584283) correlation anchored at 21 December 2012 = 4 Ajaw.

id class-attribute instance-attribute

id = 'tzolkin.engine'

version class-attribute instance-attribute

version = '0.1.0'

deck

deck(request: ReadingRequest) -> Deck

Return the Tzolk'in day-sign deck.

Parameters:

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

Returns:

Type	Description
Deck	The bundled Tzolk'in deck.

Raises:

Type	Description
ValidationError	If the requested deck is unsupported.

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

def deck(self, request: ReadingRequest) -> Deck:
    """Return the Tzolk'in day-sign deck.

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

    Returns:
        The bundled Tzolk'in deck.

    Raises:
        ValidationError: If the requested deck is unsupported.
    """

    if request.deck_id != TZOLKIN_DECK.id:
        raise ValidationError(f"unsupported Tzolk'in deck: {request.deck_id}")
    return TZOLKIN_DECK

spread

spread(request: ReadingRequest) -> Spread

Return the Tzolk'in spread.

Parameters:

Name	Type	Description	Default
request	ReadingRequest	Reading request whose spread_id must match TZOLKIN_SPREAD.id.	required

Returns:

Type	Description
Spread	The bundled Tzolk'in spread.

Raises:

Type	Description
ValidationError	If the requested spread is unsupported.

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

def spread(self, request: ReadingRequest) -> Spread:
    """Return the Tzolk'in spread.

    Args:
        request: Reading request whose ``spread_id`` must match
            ``TZOLKIN_SPREAD.id``.

    Returns:
        The bundled Tzolk'in spread.

    Raises:
        ValidationError: If the requested spread is unsupported.
    """

    if request.spread_id != TZOLKIN_SPREAD.id:
        raise ValidationError(f"unsupported Tzolk'in spread: {request.spread_id}")
    return TZOLKIN_SPREAD

draw

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

Compute the Tzolk'in day as a deterministic draw.

Parameters:

Name	Type	Description	Default
request	ReadingRequest	Reading request with birth_datetime in options or querent attributes.	required
rng	Rng	Ignored. The argument is present for Engine compatibility.	required

Returns:

Type	Description
Draw	A draw with the single day-sign selection.

Raises:

Type	Description
ValidationError	If required birth data is invalid.

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

def draw(self, request: ReadingRequest, rng: Rng) -> Draw:
    """Compute the Tzolk'in day as a deterministic draw.

    Args:
        request: Reading request with ``birth_datetime`` in options or
            querent attributes.
        rng: Ignored. The argument is present for ``Engine`` compatibility.

    Returns:
        A draw with the single day-sign selection.

    Raises:
        ValidationError: If required birth data is invalid.
    """

    del rng
    birth = parse_birth_data(request)
    return draw_from_day(tzolkin_for(birth.birth_datetime.date()))

cast

cast(request: ReadingRequest) -> Reading

Compute a Tzolk'in reading without a caller RNG.

Parameters:

Name	Type	Description	Default
request	ReadingRequest	Reading request containing birth data.	required

Returns:

Type	Description
Reading	A reading with the day-sign placement and Tzolk'in summary.

Raises:

Type	Description
ValidationError	If required birth data is invalid.

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

def cast(self, request: ReadingRequest) -> Reading:
    """Compute a Tzolk'in reading without a caller RNG.

    Args:
        request: Reading request containing birth data.

    Returns:
        A reading with the day-sign placement and Tzolk'in summary.

    Raises:
        ValidationError: If required birth data is invalid.
    """

    draw = self.draw(request, _NULL_RNG)
    return self._interpret(request, draw, rng=None)

build_engine

build_engine() -> TzolkinEngine

Create a Tzolk'in engine.

Returns:

Type	Description
TzolkinEngine	A new TzolkinEngine instance.

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

def build_engine() -> TzolkinEngine:
    """Create a Tzolk'in engine.

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

    return TzolkinEngine()