Name Numerology

A Pythagorean name-numerology engine that deterministically reduces a name to its Expression, Soul Urge, and Personality numbers. Whether Y counts as a vowel is a configurable option.

from fortune_telling_core import Querent, ReadingRequest
from fortune_telling_core.traditions.name_numerology import (
    NAME_NUMEROLOGY_DECK,
    NAME_NUMEROLOGY_SPREAD,
    build_engine,
)

request = ReadingRequest(
    deck_id=NAME_NUMEROLOGY_DECK.id,
    spread_id=NAME_NUMEROLOGY_SPREAD.id,
    querent=Querent(id="sample", display_name="Sample", attributes={"name": "John"}),
)
reading = build_engine().cast(request)

name_numerology

NAME_NUMEROLOGY_DECK module-attribute

NAME_NUMEROLOGY_DECK = Deck(
    id="name_numerology.deck.numbers.v1",
    symbols=tuple(
        (
            Symbol(
                id=_symbol_id(item.value),
                name=str(item.value),
                attributes={
                    "value": str(item.value),
                    "keyword": item.keyword,
                    "master": "true"
                    if item.master
                    else "false",
                },
            )
        )
        for item in NUMBERS
    ),
)

NAME_NUMEROLOGY_SPREAD module-attribute

NAME_NUMEROLOGY_SPREAD = Spread(
    id="name_numerology.spread.core.v1",
    name="Name Numbers",
    positions=(
        Position(
            "expression",
            "Expression",
            "Destiny number from all letters.",
        ),
        Position(
            "soul_urge",
            "Soul Urge",
            "Heart's desire number from the vowels.",
        ),
        Position(
            "personality",
            "Personality",
            "Outer number from the consonants.",
        ),
    ),
)

YMode

Bases: StrEnum

Whether the letter Y counts as a vowel.

Numerologists disagree on Y: some always treat it as a consonant, others as a vowel (and some judge it per name by sound, which is not deterministic). This engine exposes the two deterministic conventions and defaults to treating Y as a consonant.

CONSONANT class-attribute instance-attribute

CONSONANT = 'consonant'

VOWEL class-attribute instance-attribute

VOWEL = 'vowel'

NameNumerologyEngine

NameNumerologyEngine(*, y_mode: YMode = YMode.CONSONANT)

Bases: AbstractEngine

Pythagorean name numerology engine.

The engine deterministically reduces a name to its Expression, Soul Urge, and Personality numbers, preserving the master numbers 11, 22, and 33.

Parameters:

Name	Type	Description	Default
y_mode	YMode	Default treatment of the letter Y when the request does not specify y_mode.	CONSONANT

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

def __init__(self, *, y_mode: YMode = YMode.CONSONANT) -> None:
    self.y_mode = y_mode

id class-attribute instance-attribute

id = 'name_numerology.engine'

version class-attribute instance-attribute

version = '0.1.0'

y_mode instance-attribute

y_mode = y_mode

deck

deck(request: ReadingRequest) -> Deck

Return the name numerology deck.

Parameters:

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

Returns:

Type	Description
Deck	The bundled deck.

Raises:

Type	Description
ValidationError	If the requested deck is unsupported.

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

def deck(self, request: ReadingRequest) -> Deck:
    """Return the name numerology deck.

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

    Returns:
        The bundled deck.

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

    if request.deck_id != NAME_NUMEROLOGY_DECK.id:
        raise ValidationError(f"unsupported name numerology deck: {request.deck_id}")
    return NAME_NUMEROLOGY_DECK

spread

spread(request: ReadingRequest) -> Spread

Return the name numerology spread.

Parameters:

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

Returns:

Type	Description
Spread	The bundled spread.

Raises:

Type	Description
ValidationError	If the requested spread is unsupported.

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

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

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

    Returns:
        The bundled spread.

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

    if request.spread_id != NAME_NUMEROLOGY_SPREAD.id:
        raise ValidationError(f"unsupported name numerology spread: {request.spread_id}")
    return NAME_NUMEROLOGY_SPREAD

draw

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

Compute the core name numbers as a deterministic draw.

Parameters:

Name	Type	Description	Default
request	ReadingRequest	Reading request with name and optional y_mode 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 Expression, Soul Urge, and Personality selections.

Raises:

Type	Description
ValidationError	If the name or options are invalid.

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

def draw(self, request: ReadingRequest, rng: Rng) -> Draw:
    """Compute the core name numbers as a deterministic draw.

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

    Returns:
        A draw with the Expression, Soul Urge, and Personality selections.

    Raises:
        ValidationError: If the name or options are invalid.
    """

    del rng
    name_input = parse_name_input(request, self.y_mode)
    return draw_from_chart(compute_chart(name_input.name, name_input.y_mode))

cast

cast(request: ReadingRequest) -> Reading

Compute a name numerology reading without a caller RNG.

Parameters:

Name	Type	Description	Default
request	ReadingRequest	Reading request containing the name and optional configuration.	required

Returns:

Type	Description
Reading	A reading with the three core-number placements and summary.

Raises:

Type	Description
ValidationError	If the name or options are invalid.

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

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

    Args:
        request: Reading request containing the name and optional
            configuration.

    Returns:
        A reading with the three core-number placements and summary.

    Raises:
        ValidationError: If the name or options are invalid.
    """

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

build_engine

build_engine(
    *, y_mode: YMode = YMode.CONSONANT
) -> NameNumerologyEngine

Create a name numerology engine.

Parameters:

Name	Type	Description	Default
y_mode	YMode	Default treatment of the letter Y.	CONSONANT

Returns:

Type	Description
NameNumerologyEngine	A new NameNumerologyEngine instance.

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

def build_engine(*, y_mode: YMode = YMode.CONSONANT) -> NameNumerologyEngine:
    """Create a name numerology engine.

    Args:
        y_mode: Default treatment of the letter Y.

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

    return NameNumerologyEngine(y_mode=y_mode)