Maya Haab'

A Maya Haab' (365-day vague year) engine that deterministically derives a querent's Haab' date — a day position within a named month — from their birth date. The month deck holds the eighteen winal plus the five-day Wayeb'. The cycle uses the GMT (584283) correlation, anchored at 21 December 2012 = 3 K'ank'in, and partners the Tzolk'in in the Calendar Round.

from fortune_telling_core import Querent, ReadingRequest
from fortune_telling_core.traditions.haab import HAAB_DECK, HAAB_SPREAD, build_engine

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

haab

HAAB_DECK module-attribute

HAAB_DECK = Deck(
    id="haab.deck.months.v1",
    symbols=tuple(
        (
            Symbol(
                id=month.symbol_id,
                name=month.name,
                attributes={
                    "slug": month.slug,
                    "cycle_index": str(month.index),
                    "length": str(month.length),
                },
            )
        )
        for month in MONTHS
    ),
)

HAAB_SPREAD module-attribute

HAAB_SPREAD = Spread(
    id="haab.spread.birth.v1",
    name="Haab'",
    positions=(
        Position(
            "haab",
            "Haab'",
            "Haab' month with the day position within it.",
        ),
    ),
)

HaabEngine

Bases: AbstractEngine

Maya Haab' (365-day vague year) engine.

The engine deterministically derives a querent's Haab' date — a day position within one of eighteen winal or the five-day Wayeb' — from their birth date, using the GMT (584283) correlation anchored at 21 December 2012 = 3 K'ank'in.

id class-attribute instance-attribute

id = 'haab.engine'

version class-attribute instance-attribute

version = '0.1.0'

deck

deck(request: ReadingRequest) -> Deck

Return the Haab' month deck.

Parameters:

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

Returns:

Type	Description
Deck	The bundled Haab' deck.

Raises:

Type	Description
ValidationError	If the requested deck is unsupported.

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

def deck(self, request: ReadingRequest) -> Deck:
    """Return the Haab' month deck.

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

    Returns:
        The bundled Haab' deck.

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

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

spread

spread(request: ReadingRequest) -> Spread

Return the Haab' spread.

Parameters:

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

Returns:

Type	Description
Spread	The bundled Haab' spread.

Raises:

Type	Description
ValidationError	If the requested spread is unsupported.

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

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

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

    Returns:
        The bundled Haab' spread.

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

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

draw

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

Compute the Haab' date 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 Haab' selection.

Raises:

Type	Description
ValidationError	If required birth data is invalid.

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

def draw(self, request: ReadingRequest, rng: Rng) -> Draw:
    """Compute the Haab' date 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 Haab' selection.

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

    del rng
    birth = parse_birth_data(request)
    return draw_from_date(haab_for(birth.birth_datetime.date()))

cast

cast(request: ReadingRequest) -> Reading

Compute a Haab' 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 Haab' placement and summary.

Raises:

Type	Description
ValidationError	If required birth data is invalid.

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

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

    Args:
        request: Reading request containing birth data.

    Returns:
        A reading with the Haab' placement and 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() -> HaabEngine

Create a Haab' engine.

Returns:

Type	Description
HaabEngine	A new HaabEngine instance.

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

def build_engine() -> HaabEngine:
    """Create a Haab' engine.

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

    return HaabEngine()