goyimnose/tarot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

df

Browse Source
This commit is contained in:
nose
2025-12-05 03:41:16 -08:00
parent 79d4f1a09e
commit e3747555bf
22 changed files with 3669 additions and 388 deletions
Download Patch File Download Diff File Expand all files Collapse all files

325
cli_renderers.py Normal file
View File

@@ -0,0 +1,325 @@
"""Shared renderers for typer-test output tables.
This module centralizes Rich table rendering so typer-test.py stays lean. It includes
specialized handling for planets plus generic list/dict/object renderers.
"""
from __future__ import annotations
from typing import Any, Dict, List, Optional, Sequence
from rich.console import Console
from rich.panel import Panel
from rich.table import Table
from tarot import Card
from utils.attributes import Color, Planet
class Renderer:
"""Render arbitrary Tarot objects using Rich tables."""
def __init__(self, console: Console) -> None:
self.console = console
self.planet_renderer = PlanetRenderer(self)
# Public helpers -----------------------------------------------------
def render_value(self, value: Any) -> None:
if isinstance(value, Planet):
self.planet_renderer.render(value)
return
if isinstance(value, Card):
self._render_card(value)
return
if isinstance(value, list) and value and isinstance(value[0], Card):
self.print_cards_table(value)
return
if hasattr(value, "upright") and hasattr(value, "reversed"):
self.print_kv_table(
"Meaning", {"upright": value.upright, "reversed": value.reversed}
)
return
if isinstance(value, dict):
self._render_dict(value)
return
if isinstance(value, list):
self._render_list(value)
return
if hasattr(value, "__dict__"):
self._render_object(value)
return
self.console.print(value)
def print_kv_table(self, title: str, data: Dict[str, Any]) -> None:
table = Table(title=title, show_header=False)
table.add_column("Field", style="bold")
table.add_column("Value")
for key, value in data.items():
table.add_row(self._humanize_key(str(key)), "" if value is None else str(value))
self.console.print(table)
def print_rows_table(self, title: str, columns: List[str], rows: List[List[Any]]) -> None:
table = Table(title=title, show_header=True, show_lines=True)
for col in columns:
table.add_column(col)
for row in rows:
str_row = ["" if v is None else str(v) for v in row]
table.add_row(*str_row)
self.console.print(table)
def print_cards_table(self, cards: List[Card]) -> None:
table = Table(title="Cards", show_lines=True)
table.add_column("#", justify="right")
table.add_column("Name")
table.add_column("Arcana")
table.add_column("Suit")
table.add_column("Pip/Court")
for card in cards:
suit = getattr(getattr(card, "suit", None), "name", "")
pip = str(getattr(card, "pip", "")) if getattr(card, "pip", None) else ""
court = getattr(card, "court_rank", "")
pip_display = court or pip
table.add_row(
str(getattr(card, "number", "")),
getattr(card, "name", ""),
getattr(card, "arcana", ""),
suit,
pip_display,
)
self.console.print(table)
# Internal renderers -------------------------------------------------
def _render_card(self, card: Card) -> None:
suit = getattr(card, "suit", None)
lines: List[str] = [f"Arcana: {card.arcana}"]
if suit is not None and getattr(suit, "name", None):
lines.append(f"Suit: {suit.name}")
if getattr(card, "pip", 0):
lines.append(f"Pip: {card.pip}")
if getattr(card, "court_rank", ""):
lines.append(f"Court Rank: {card.court_rank}")
meaning = getattr(card, "meaning", None)
if meaning is not None:
if getattr(meaning, "upright", None):
lines.append(f"Upright: {meaning.upright}")
if getattr(meaning, "reversed", None):
lines.append(f"Reversed: {meaning.reversed}")
keywords = getattr(card, "keywords", None)
if keywords:
lines.append(f"Keywords: {', '.join(keywords)}")
reversed_keywords = getattr(card, "reversed_keywords", None)
if reversed_keywords:
lines.append(f"Reversed Keywords: {', '.join(reversed_keywords)}")
guidance = getattr(card, "guidance", None)
if guidance:
lines.append(f"Guidance: {guidance}")
self.console.print(
Panel("\n".join(lines), title=f"{card.number}: {card.name}", expand=False)
)
def _render_object(self, obj: Any) -> None:
attrs = {k: v for k, v in vars(obj).items() if not k.startswith("_")}
display = {k: self._format_value(v) for k, v in attrs.items()}
title = getattr(obj, "name", None) or obj.__class__.__name__
self.print_kv_table(str(title), display)
def _render_dict(self, data: Dict[Any, Any], title: str = "Result") -> None:
if not data:
self.console.print(f"{title}: {{}}")
return
values = list(data.values())
if all(self._is_scalar(v) for v in values):
self.print_kv_table(title, data)
return
if all(isinstance(v, list) for v in values) and values and values[0]:
first_item = values[0][0]
if hasattr(first_item, "__dict__"):
self._render_dict_of_list_objects(data, title)
return
if all(hasattr(v, "__dict__") for v in values):
rows = []
sample_attrs = self._simple_attrs(values[0])
columns = ["Key"] + [self._humanize_key(k) for k in sample_attrs.keys()]
for key, obj in data.items():
attrs = self._simple_attrs(obj)
rows.append([key] + [attrs.get(k, "") for k in sample_attrs.keys()])
self.print_rows_table(title, columns, rows)
return
self.print_kv_table(title, {k: self._short_value(v) for k, v in data.items()})
def _render_list(self, items: List[Any], title: str = "Result") -> None:
if not items:
self.console.print(f"{title}: []")
return
first = items[0]
if isinstance(first, Card):
self.print_cards_table(items)
return
if hasattr(first, "__dict__"):
sample_attrs = self._simple_attrs(first)
columns = [self._humanize_key(k) for k in sample_attrs.keys()]
rows = []
for obj in items:
attrs = self._simple_attrs(obj)
rows.append([attrs.get(k, "") for k in sample_attrs.keys()])
self.print_rows_table(title, columns, rows)
return
if isinstance(first, dict):
keys = list(first.keys())
columns = [self._humanize_key(k) for k in keys]
rows = []
for obj in items:
rows.append([obj.get(k, "") for k in keys])
self.print_rows_table(title, columns, rows)
return
self.print_kv_table(title, {i: self._short_value(v) for i, v in enumerate(items)})
def _render_dict_of_list_objects(self, data: Dict[Any, List[Any]], title: str) -> None:
first_key = next(iter(data))
first_list = data[first_key]
if not first_list:
self.print_kv_table(title, {k: "[]" for k in data.keys()})
return
sample_attrs = self._simple_attrs(first_list[0])
columns = ["Key"] + [self._humanize_key(k) for k in sample_attrs.keys()]
rows: List[List[Any]] = []
for key, lst in data.items():
for obj in lst:
attrs = self._simple_attrs(obj)
rows.append([key] + [attrs.get(k, "") for k in sample_attrs.keys()])
self.print_rows_table(title, columns, rows)
# Value helpers ------------------------------------------------------
@staticmethod
def _simple_attrs(obj: Any) -> Dict[str, Any]:
return {k: v for k, v in vars(obj).items() if not k.startswith("_")}
@staticmethod
def _is_scalar(val: Any) -> bool:
return isinstance(val, (str, int, float, bool)) or val is None
def _format_value(self, val: Any, depth: int = 0) -> str:
if isinstance(val, list):
if not val:
return "[]"
lines = []
for item in val:
lines.append(" " * depth + "- " + self._format_value(item, depth + 1).lstrip())
return "\n".join(lines)
if isinstance(val, dict):
lines = []
for k, v in val.items():
lines.append(
" " * depth
+ f"{self._humanize_key(str(k))}: "
+ self._format_value(v, depth + 1)
)
return "\n".join(lines)
if hasattr(val, "__dict__"):
inner = {k: v for k, v in vars(val).items() if not k.startswith("_")}
if not inner:
return str(val)
parts = [
f"{self._humanize_key(str(k))}={self._short_value(v)}" for k, v in inner.items()
]
name = getattr(val, "name", val.__class__.__name__)
return f"{name}: " + "; ".join(parts)
return str(val)
def _short_value(self, val: Any) -> str:
if isinstance(val, Card):
return f"Card {getattr(val, 'number', '?')}: {getattr(val, 'name', '')}"
if isinstance(val, list):
if not val:
return "[]"
preview = ", ".join(self._short_value(v) for v in val[:4])
suffix = "..." if len(val) > 4 else ""
return f"[{preview}{suffix}]"
if isinstance(val, dict):
return f"dict({len(val)})"
return str(val)
@staticmethod
def _humanize_key(key: str) -> str:
return key.replace("_", " ")
class PlanetRenderer:
"""Type-specific table rendering for planets."""
def __init__(self, renderer: Renderer) -> None:
self.renderer = renderer
@property
def console(self) -> Console:
return self.renderer.console
def render(self, planet: Planet) -> None:
base_fields = {
"Symbol": planet.symbol,
"Element": planet.element,
"Ruling Zodiac": self._join_list(planet.ruling_zodiac),
"Associated Letters": self._join_list(planet.associated_letters),
"Keywords": self._join_list(planet.keywords),
"Description": planet.description,
}
self.renderer.print_kv_table(f"Planet: {planet.name}", self._compact(base_fields))
if planet.associated_numbers:
rows = []
for number in planet.associated_numbers:
color_label = self._color_label(number.color)
rows.append(
[
getattr(number, "value", ""),
getattr(number, "sephera", ""),
getattr(number, "element", ""),
getattr(number, "compliment", ""),
color_label,
]
)
self.renderer.print_rows_table(
"Associated Numbers",
["Value", "Sephera", "Element", "Compliment", "Color"],
rows,
)
if planet.color:
color = planet.color
color_fields = {
"Name": color.name,
"Hex": color.hex_value,
"Element": color.element,
"Scale": color.scale,
"Meaning": color.meaning,
"Tarot Associations": self._join_list(getattr(color, "tarot_associations", [])),
"Description": color.description,
}
self.renderer.print_kv_table("Planetary Color", self._compact(color_fields))
@staticmethod
def _join_list(items: Sequence[Any]) -> str:
return ", ".join(str(item) for item in items) if items else ""
@staticmethod
def _compact(data: Dict[str, Any]) -> Dict[str, Any]:
return {k: v for k, v in data.items() if v not in (None, "", [], {})}
@staticmethod
def _color_label(color: Optional[Color]) -> str:
if isinstance(color, Color):
hex_part = f" ({color.hex_value})" if getattr(color, "hex_value", "") else ""
return f"{color.name}{hex_part}"
return ""

27
debug_paths.py Normal file
View File

@@ -0,0 +1,27 @@
from tarot.tarot_api import Tarot
print("Initializing Tarot...")
# Force initialization
Tarot._ensure_initialized()
Tarot.tree._ensure_initialized()
print("Checking Paths...")
paths = Tarot.tree.path()
print(f"Found {len(paths)} paths")
found_aleph = False
for p in paths.values():
print(f"Path {p.number}: {p.hebrew_letter} -> {p.tarot_trump}")
if p.hebrew_letter == "Aleph":
found_aleph = True
if not found_aleph:
print("Aleph path not found!")
else:
print("Aleph path found.")
print("Checking Cards...")
cards = Tarot.deck.card.filter()
print(f"Found {len(cards)} cards")
fool = Tarot.deck.card.filter(name="Fool")
print(f"Fool card: {fool}")

56
mytest.py
View File

@@ -3,54 +3,12 @@ from temporal import ThalemaClock
from datetime import datetime
from utils import Personality, MBTIType
# Tarot core functionality
card = Tarot.deck.card(3)
print(f"Card: {card}")
# Spreads - now under Tarot.deck.card.spread()
print("\n" + Tarot.deck.card.spread("Celtic Cross"))
# Temporal functionality (separate module)
clock = ThalemaClock(datetime.now())
print(f"\nClock: {clock}")
print(Tarot.deck.card.filter(suit="Cups"))
# Top-level namespaces with pretty printing
print("\n" + "=" * 60)
print("Letter Namespace:")
print(letter)
print("\n" + "=" * 60)
print("Number Namespace:")
print(number)
print("\nDigital root of 343:", number.digital_root(343))
print("\n" + "=" * 60)
print("Kaballah - Tree of Life:")
print(kaballah.Tree)
print("\n" + "=" * 60)
print("Kaballah - Cube of Space:")
print(kaballah.Cube.wall.display_filter(side="Below"))
# Filtering examples
print("\n" + "=" * 60)
print(Tarot.deck.card.filter(type='court'))
# MBTI Personality types mapped to Tarot court cards (1-to-1 direct mapping)
print("\n" + "=" * 60)
print("MBTI Personality Types & Tarot Court Cards")
print("=" * 60)
# Create personalities for all 16 MBTI types
mbti_types = ['ENFP', 'ISTJ', 'INTJ', 'INFJ', 'ENTJ', 'ESFJ', 'ESTP', 'ISFJ',
'ENTP', 'ISFP', 'INTP', 'INFP', 'ESTJ', 'ESFP', 'ISTP', 'INTJ']
for mbti in mbti_types:
personality = Personality.from_mbti(mbti, Tarot.deck)
print(f"\n{personality}")
#prints court cards
print(Tarot.deck.card.filter(suit="cups,wands"))
from tarot.ui import display_cards,display_cube
from tarot.deck import Deck
# Get some cards
deck = Deck()
cards = Tarot.deck.card.filter(suit="cups",type="ace")
print(cards)
# Display using default deck

5
pyproject.toml
View File

@@ -28,6 +28,11 @@ classifiers = [
dependencies = [
"tomli>=1.2.0;python_version<'3.11'",
"tomli_w>=1.0.0",
"Pillow>=9.0.0",
"typer>=0.12.5",
"rich>=10.11.0",
"shellingham>=1.3.0",
"prompt-toolkit>=3.0.47",
]
[project.optional-dependencies]

6
src/tarot/card/card.py
View File

@@ -292,7 +292,7 @@ class CardAccessor:
"""Return a nice representation of the deck accessor."""
return self.__str__()
def spread(self, spread_name: str) -> str:
def spread(self, spread_name: str):
"""
Draw a Tarot card reading for a spread.
@@ -304,7 +304,7 @@ class CardAccessor:
Examples: 'Celtic Cross', 'golden dawn', 'three_card', 'tree of life'
Returns:
Formatted string with spread positions, drawn cards, and interpretations
SpreadReading object containing the spread and drawn cards
Raises:
ValueError: If spread name not found
@@ -328,4 +328,4 @@ class CardAccessor:
# Create and return reading
reading = SpreadReading(spread, drawn_cards)
return str(reading)
return reading

792
src/tarot/card/details.py
View File

@@ -6,6 +6,8 @@ Registry is keyed by card position (1-78), independent of deck-specific names.
Deck order: Cups (1-14), Pentacles (15-28), Swords (29-42),
Major Arcana (43-64), Wands (65-78)
Minor suit sequencing (per suit): Ace, 2-10, Prince, Knight, Princess, Queen.
Usage:
from tarot.card.details import CardDetailsRegistry
@@ -21,6 +23,8 @@ Usage:
from typing import TYPE_CHECKING, Any, Dict, Optional
from tarot.constants import build_position_map
if TYPE_CHECKING:
from tarot.deck import Card
@@ -88,48 +92,7 @@ class CardDetailsRegistry:
Returns:
Dictionary mapping position to registry key
"""
position_map = {}
# Positions 1-14: Cups (Ace, Ten, 2-9, Knight, Prince, Princess, Queen)
cups_names = ["Ace of Cups", "Ten of Cups", "Two of Cups", "Three of Cups",
"Four of Cups", "Five of Cups", "Six of Cups", "Seven of Cups",
"Eight of Cups", "Nine of Cups", "Knight of Cups", "Prince of Cups",
"Princess of Cups", "Queen of Cups"]
for pos, name in enumerate(cups_names, start=1):
position_map[pos] = name
# Positions 15-28: Pentacles (same structure)
pentacles_names = ["Ace of Pentacles", "Ten of Pentacles", "Two of Pentacles", "Three of Pentacles",
"Four of Pentacles", "Five of Pentacles", "Six of Pentacles", "Seven of Pentacles",
"Eight of Pentacles", "Nine of Pentacles", "Knight of Pentacles", "Prince of Pentacles",
"Princess of Pentacles", "Queen of Pentacles"]
for pos, name in enumerate(pentacles_names, start=15):
position_map[pos] = name
# Positions 29-42: Swords (same structure)
swords_names = ["Ace of Swords", "Ten of Swords", "Two of Swords", "Three of Swords",
"Four of Swords", "Five of Swords", "Six of Swords", "Seven of Swords",
"Eight of Swords", "Nine of Swords", "Knight of Swords", "Prince of Swords",
"Princess of Swords", "Queen of Swords"]
for pos, name in enumerate(swords_names, start=29):
position_map[pos] = name
# Positions 43-64: Major Arcana (mapped to Roman numerals)
major_arcana_keys = ["o", "I", "II", "III", "IV", "V", "VI", "VII", "VIII", "IX",
"X", "XI", "XII", "XIII", "XIV", "XV", "XVI", "XVII", "XVIII", "XIX",
"XX", "XXI"]
for pos, key in enumerate(major_arcana_keys, start=43):
position_map[pos] = key
# Positions 65-78: Wands (same structure)
wands_names = ["Ace of Wands", "Ten of Wands", "Two of Wands", "Three of Wands",
"Four of Wands", "Five of Wands", "Six of Wands", "Seven of Wands",
"Eight of Wands", "Nine of Wands", "Knight of Wands", "Prince of Wands",
"Princess of Wands", "Queen of Wands"]
for pos, name in enumerate(wands_names, start=65):
position_map[pos] = name
return position_map
return build_position_map()
def get_by_position(self, position: int) -> Optional[Dict[str, Any]]:
"""
@@ -155,154 +118,220 @@ class CardDetailsRegistry:
return {
# Major Arcana (0-21) - Interpretive data only
"o": {
"explanation": "The Fool represents new beginnings, innocence, and spontaneity. This card signifies a fresh start or embarking on a new journey with optimism and faith.",
"explanation": {
"summary": "The Fool represents new beginnings, innocence, and spontaneity. This card signifies a fresh start or embarking on a new journey with optimism and faith.",
"waite": "The Fool, Mate, or Unwise Man. Court de Gebelin places it at the head of the whole series as the zero or negative which is presupposed by numeration, and as this is a simpler so also it is a better arrangement. It has been abandoned because in later times the cards have been attributed to the letters of the Hebrew alphabet, and there has been apparently some difficulty about allocating the zero symbol satisfactorily in a sequence of letters all of which signify numbers. In the present reference of the card to the letter Shin, which corresponds to 200, the difficulty or the unreason remains. The truth is that the real arrangement of the cards has never transpired. The Fool carries a wallet; he is looking over his shoulder and does not know that he is on the brink of a precipice; but a dog or other animal--some call it a tiger--is attacking him from behind, and he is hurried to his destruction unawares."
},
"interpretation": "Beginning of the Great Work, innocence; a fool for love; divine madness. Reason is transcended. Take the leap. Gain or loss through foolish actions.",
"keywords": ["new beginnings", "innocence", "faith", "spontaneity", "potential"],
"reversed_keywords": ["recklessness", "naivety", "poor judgment", "folly"],
"guidance": "Trust in the unfolding of your path. Embrace new opportunities with awareness and openness.",
},
"I": {
"explanation": "The Magician embodies manifestation, resourcefulness, and personal power. This card shows mastery of skills and the ability to turn ideas into reality.",
"explanation": {
"summary": "The Magician embodies manifestation, resourcefulness, and personal power. This card shows mastery of skills and the ability to turn ideas into reality.",
"waite": "The Magus, Magician, or juggler, the caster of the dice and mountebank, in the world of vulgar trickery. This is the colportage interpretation, and it has the same correspondence with the real symbolical meaning that the use of the Tarot in fortune-telling has with its mystic construction according to the secret science of symbolism. I should add that many independent students of the subject, following their own lights, have produced individual sequences of meaning in respect of the Trumps Major, and their lights are sometimes suggestive, but they are not the true lights."
},
"interpretation": "Communication; Conscious Will; the process of continuous creation; ambiguity; deceptionl Things may not be as they appear. Concentration, meditation; mind used to direct the Will. Manipulation; crafty maneuverings.",
"keywords": ["manifestation", "resourcefulness", "power", "inspired action", "concentration"],
"reversed_keywords": ["manipulation", "poor planning", "untapped talents", "lack of direction"],
"guidance": "Focus your energy and intention on what you want to manifest. You have the tools and talents you need.",
},
"II": {
"explanation": "The High Priestess represents intuition, sacred knowledge, and the subconscious mind. She embodies mystery and inner wisdom.",
"explanation": {
"summary": "The High Priestess represents intuition, sacred knowledge, and the subconscious mind. She embodies mystery and inner wisdom.",
"waite": "The High Priestess, the Pope Joan, or Female Pontiff; early expositors have sought to term this card the Mother, or Pope's Wife, which is opposed to the symbolism. It is sometimes held to represent the Divine Law and the Gnosis, in which case the Priestess corresponds to the idea of the Shekinah. She is the Secret Tradition and the higher sense of the instituted Mysteries."
},
"interpretation": "Symbol of highest initiation; link between the archetypal and Formative Worlds. An initiatrixl Wooing by enchantment. possibility. The Idea behind the Form. Fluctuationl Time may not be right for a decision concerning mundane matters.",
"keywords": ["intuition", "sacred knowledge", "divine feminine", "the subconscious", "mystery"],
"reversed_keywords": ["hidden information", "silence", "disconnection from intuition", "superficiality"],
"guidance": "Listen to your inner voice. The answers you seek lie within. Trust the wisdom of your intuition.",
},
"III": {
"explanation": "The Empress symbolizes abundance, fertility, and nurturing energy. She represents creativity, sensuality, and the power of manifestation through nurturing.",
"explanation": {
"summary": "The Empress symbolizes abundance, fertility, and nurturing energy. She represents creativity, sensuality, and the power of manifestation through nurturing.",
"waite": "The Empress, who is sometimes represented with full face, while her correspondence, the Emperor, is in profile. As there has been some tendency to ascribe a symbolical significance to this distinction, it seems desirable to say that it carries no inner meaning. The Empress has been connected with the ideas of universal fecundity and in a general sense with activity."
},
"interpretation": "The Holy Grail. love unites the Will. Love; beauty; friendship; success; passive balance. The feminine point of view. The door is open. Disregard the details and concentrate on the big picture.",
"keywords": ["abundance", "fertility", "femininity", "beauty", "nature", "creativity"],
"reversed_keywords": ["dependency", "creative block", "neediness", "underdevelopment"],
"guidance": "Nurture yourself and others. Allow yourself to enjoy the fruits of your labor and appreciate beauty.",
},
"IV": {
"explanation": "The Emperor represents authority, leadership, and established power. He embodies structure, discipline, and protection through strength and control.",
"explanation": {
"summary": "The Emperor represents authority, leadership, and established power. He embodies structure, discipline, and protection through strength and control.",
"waite": "The Emperor, by imputation the spouse of the former. He is occasionally represented as wearing, in addition to his personal insignia, the stars or ribbons of some order of chivalry. I mention this to shew that the cards are a medley of old and new emblems."
},
"interpretation": "Creative wisdom radiating upon the organized man and woman. Domination after conquest; quarrelsomeness; paternal love; ambition. Thought ruled by creative, masculine, fiery energy. Stubbornness; war; authority; energy in its most temporal form. Swift immpermaent action over confidence.",
"keywords": ["authority", "leadership", "power", "structure", "protection", "discipline"],
"reversed_keywords": ["weakness", "ineffectual leadership", "lack of discipline", "tyranny"],
"guidance": "Step into your power with confidence. Establish clear boundaries and structure. Lead by example.",
},
"V": {
"explanation": "The Hierophant represents tradition, conventional wisdom, and spiritual authority. This card embodies education, ceremony, and moral values.",
"explanation": {
"summary": "The Hierophant represents tradition, conventional wisdom, and spiritual authority. This card embodies education, ceremony, and moral values.",
"waite": "The High Priest or Hierophant, called also Spiritual Father, and more commonly and obviously the Pope. It seems even to have been named the Abbot, and then its correspondence, the High Priestess, was the Abbess or Mother of the Convent. Both are arbitrary names. The insignia of the figures are papal, and in such case the High Priestess is and can be only the Church, to whom Pope and priests are married by the spiritual rite of ordination."
},
"interpretation": "The Holy Guardian Angel. The uniting of t hat which is above with that which is below. Love is indicated, but the nature of that love is not yet to be revealed. Inspiration; teaching; organization; discipline; strength; endurance; toil; help from superiors.",
"keywords": ["tradition", "spirituality", "wisdom", "ritual", "morality", "ethics"],
"reversed_keywords": ["rebellion", "unconventionality", "questioning authority", "dogmatism"],
"guidance": "Seek guidance from established wisdom. Respect traditions while finding your own spiritual path.",
},
"VI": {
"explanation": "The Lovers represents relationships, values alignment, and the union of opposites. It signifies choice, intimacy, and deep connection.",
"explanation": {
"summary": "The Lovers represents relationships, values alignment, and the union of opposites. It signifies choice, intimacy, and deep connection.",
"waite": "The Lovers or Marriage. This symbol has undergone many variations, as might be expected from its subject. In the eighteenth century form, by which it first became known to the world of archæological research, it is really a card of married life, shewing father and mother, with their child placed between them; and the pagan Cupid above, in the act of flying his shaft, is, of course, a misapplied emblem."
},
"interpretation": "Intuition. Be open to your own inner voice. A well-intended, arranged marriage. An artificial union. The need to make a choice with awareness of consequences union; analysis followed by synthesis; indecision; instability; superficiality.",
"keywords": ["relationships", "love", "union", "values", "choice", "alignment"],
"reversed_keywords": ["disharmony", "misalignment", "conflict", "communication breakdown"],
"guidance": "Choose with your heart aligned with your values. Deep connection requires vulnerability and honesty.",
},
"VII": {
"explanation": "The Chariot embodies willpower, determination, and control through focused intention. It represents triumph through discipline and forward momentum.",
"explanation": {
"summary": "The Chariot embodies willpower, determination, and control through focused intention. It represents triumph through discipline and forward momentum.",
"waite": "The Chariot. This is represented in some extant codices as being drawn by two sphinxes, and the device is in consonance with the symbolism, but it must not be supposed that such was its original form; the variation was invented to support a particular historical hypothesis. In the eighteenth century white horses were yoked to the car. As regards its usual name, the lesser stands for the greater; it is really the King in his triumph."
},
"interpretation": "Light in the darkness. The burden you carry may be the Holy Grail. Faithfulness; hope; obedience; a protective relationship; firm, even violent adherance to dogma or tradition. Glory; riches; englightened civilization; victory; triumph; chain of command.",
"keywords": ["determination", "willpower", "control", "momentum", "victory", "focus"],
"reversed_keywords": ["lack of control", "haste", "resistance", "moving backward"],
"guidance": "Take the reins of your life. Move forward with determination and clear direction. You have the power.",
},
"VIII": {
"explanation": "Strength represents inner power, courage, and compassion. It shows mastery through gentleness and the ability to face challenges with calm confidence.",
"explanation": {
"summary": "Strength represents inner power, courage, and compassion. It shows mastery through gentleness and the ability to face challenges with calm confidence.",
"waite": "Fortitude. This is one of the cardinal virtues, of which I shall speak later. The female figure is usually represented as closing the mouth of a lion. In the earlier form which is printed by Court de Gebelin, she is obviously opening it. The first alternative is better symbolically, but either is an instance of strength in its conventional understanding, and conveys the idea of mastery."
},
"interpretation": "Equilibrium; karmic law; the dance of life; all possibilities. The woman satisfied. Balance; weigh each thought against its opposite. Lawsuits; treaties. Pause and look before you leap.",
"keywords": ["strength", "courage", "patience", "compassion", "control", "confidence"],
"reversed_keywords": ["weakness", "self-doubt", "lack of composure", "poor control"],
"guidance": "True strength comes from within. Face challenges with courage and compassion for yourself and others.",
},
"IX": {
"explanation": "The Hermit represents introspection, spiritual seeking, and inner guidance. This card embodies solitude, wisdom gained through reflection, and self-discovery.",
"explanation": {
"summary": "The Hermit represents introspection, spiritual seeking, and inner guidance. This card embodies solitude, wisdom gained through reflection, and self-discovery.",
"waite": "The Hermit, as he is termed in common parlance, stands next on the list; he is also the Capuchin, and in more philosophical language the Sage. He is said to be in search of that Truth which is located far off in the sequence, and of justice which has preceded him on the way. But this is a card of attainment, as we shall see later, rather than a card of quest."
},
"interpretation": "Divine seed of all things. By silence comes inspiration and wisdom. Wandering alone; temporary solitude; creative contemplation; a virgin. Retirement from involvement in current events.",
"keywords": ["introspection", "spiritual seeking", "inner light", "wisdom", "solitude", "truth"],
"reversed_keywords": ["loneliness", "isolation", "lost", "paranoia", "disconnection"],
"guidance": "Take time for introspection and self-discovery. Your inner light guides your path. Seek solitude for wisdom.",
},
"X": {
"explanation": "The Wheel of Fortune represents cycles, destiny, and the turning points of life. It embodies luck, karma, and the natural ebb and flow of existence.",
"explanation": {
"summary": "The Wheel of Fortune represents cycles, destiny, and the turning points of life. It embodies luck, karma, and the natural ebb and flow of existence.",
"waite": "The Wheel of Fortune. There is a current Manual of Cartomancy which has obtained a considerable vogue in England, and amidst a great scattermeal of curious things to no purpose has intersected a few serious subjects. In its last and largest edition it treats in one section of the Tarot; which--if I interpret the author rightly--it regards from beginning to end as the Wheel of Fortune."
},
"interpretation": "Continual change. In the midst of revolving phenomena, reaach joyously the motionless center. Carefree love; wanton pleasure; amusement; fun; change of fortune, usually good.",
"keywords": ["fate", "destiny", "cycles", "fortune", "karma", "turning point"],
"reversed_keywords": ["bad luck", "resistance to change", "broken cycles", "misfortune"],
"guidance": "Trust in the cycles of life. What goes up must come down. Embrace change as part of your journey.",
},
"XI": {
"explanation": "Justice represents fairness, truth, and balance. It embodies accountability, clear judgment, and the consequences of actions both past and present.",
"explanation": {
"summary": "Justice represents fairness, truth, and balance. It embodies accountability, clear judgment, and the consequences of actions both past and present.",
"waite": "Justice. That the Tarot, though it is of all reasonable antiquity, is not of time immemorial, is shewn by this card, which could have been presented in a much more archaic manner. Those, however, who have gifts of discernment in matters of this kind will not need to be told that age is in no sense of the essence of the consideration."
},
"interpretation": "Understanding; the Will of New Aeon; passion; sense smitten with ecstasy. let love devour all. Energy independent of reason. Strength; courage; utilization of magical power.",
"keywords": ["justice", "fairness", "truth", "cause and effect", "balance", "accountability"],
"reversed_keywords": ["injustice", "bias", "lack of accountability", "dishonesty"],
"guidance": "Seek the truth and act with fairness. Take responsibility for your actions. Balance is key.",
},
"XII": {
"explanation": "The Hanged Man represents suspension, letting go, and seeing things from a new perspective. It embodies surrender, pause, and gaining wisdom through sacrifice.",
"explanation": {
"summary": "The Hanged Man represents suspension, letting go, and seeing things from a new perspective. It embodies surrender, pause, and gaining wisdom through sacrifice.",
"waite": "The Hanged Man. This is the symbol which is supposed to represent Prudence, and Éliphas Lévi says, in his most shallow and plausible manner, that it is the adept bound by his engagements. The figure of a man is suspended head-downwards from a gibbet, to which he is attached by a rope about one of his ankles."
},
"interpretation": "Redemption, sacrifice, annihilation in the beloved; martyrdom; loss; torment; suspension; death; suffering.",
"keywords": ["suspension", "restriction", "letting go", "new perspective", "surrender", "pause"],
"reversed_keywords": ["resistance", "stalling", "unwillingness to change", "impatience"],
"guidance": "Pause and reflect. What are you holding onto? Surrender control and trust the process.",
},
"XIII": {
"explanation": "Death represents transformation, endings, and new beginnings. This card embodies major life transitions, the release of the old, and inevitable change.",
"explanation": {
"summary": "Death represents transformation, endings, and new beginnings. This card embodies major life transitions, the release of the old, and inevitable change.",
"waite": "Death. The method of presentation is almost invariable, and embodies a bourgeois form of symbolism. The scene is the field of life, and amidst ordinary rank vegetation there are living arms and heads protruding from the ground. One of the heads is crowned, and a skeleton with a great scythe is in the act of mowing it."
},
"interpretation": "End of cycle; transformation; raw sexuality. Sex is death. Stress becomes intolerable. Any change is welcome. Time; age; unexpected change; death.",
"keywords": ["transformation", "transition", "endings", "beginnings", "change", "acceptance"],
"reversed_keywords": ["resistance to change", "stagnation", "missed opportunity", "delay"],
"guidance": "Release what no longer serves you. Transformation is inevitable. Trust in the cycle of death and rebirth.",
},
"XIV": {
"explanation": "Temperance represents balance, moderation, and harmony. It embodies blending of opposites, inner peace through balance, and finding your rhythm.",
"explanation": {
"summary": "Temperance represents balance, moderation, and harmony. It embodies blending of opposites, inner peace through balance, and finding your rhythm.",
"waite": "Temperance. The winged figure of a female--who, in opposition to all doctrine concerning the hierarchy of angels, is usually allocated to this order of ministering spirits--is pouring liquid from one pitcher to another. In his last work on the Tarot, Dr. Papus abandons the traditional form and depicts a woman wearing an Egyptian head-dress."
},
"interpretation": "Transmutation through union of opposites. A perfect marriage exalts and transforms each partner. The scientific method. Success follows complex maneuvers.",
"keywords": ["balance", "moderation", "harmony", "patience", "timing", "peace"],
"reversed_keywords": ["imbalance", "excess", "conflict", "intemperance", "discord"],
"guidance": "Seek balance in all things. Blend opposing forces. Find your rhythm through moderation and patience.",
},
"XV": {
"explanation": "The Devil represents bondage, materialism, and shadow aspects of self. It embodies addictions, illusions, and the consequences of giving away personal power.",
"explanation": {
"summary": "The Devil represents bondage, materialism, and shadow aspects of self. It embodies addictions, illusions, and the consequences of giving away personal power.",
"waite": "The Devil. In the eighteenth century this card seems to have been rather a symbol of merely animal impudicity. Except for a fantastic head-dress, the chief figure is entirely naked; it has bat-like wings, and the hands and feet are represented by the claws of a bird."
},
"interpretation": "Thou hast no right but to do thy will. Obession; temptation; ecstasy found in every phenomenon; creative action, yet sublimely careless of result; unscrupulous ambition; strength.",
"keywords": ["bondage", "materialism", "playfulness", "shadow self", "sexuality", "excess"],
"reversed_keywords": ["freedom", "detachment", "reclaiming power", "breaking free"],
"guidance": "Examine what binds you. Acknowledge your shadow. You hold the key to your own freedom.",
},
"XVI": {
"explanation": "The Tower represents sudden disruption, revelation, and breakthrough through crisis. It embodies sudden change, truth revealed, and necessary destruction.",
"explanation": {
"summary": "The Tower represents sudden disruption, revelation, and breakthrough through crisis. It embodies sudden change, truth revealed, and necessary destruction.",
"waite": "The Tower struck by Lightning. Its alternative titles are: Castle of Plutus, God's House and the Tower of Babel. In the last case, the figures falling therefrom are held to be Nimrod and his minister. It is assuredly a card of confusion, and the design corresponds, broadly speaking, to any of the designations except Maison Dieu."
},
"interpretation": "Escape from the prison of organized life; renunciation of love; quarreling. Plans are destroyed. War; danger; sudden death.",
"keywords": ["sudden change", "upheaval", "revelation", "breakdown", "breakthrough", "chaos"],
"reversed_keywords": ["resistance to change", "averted crisis", "delay", "stagnation"],
"guidance": "Crisis brings clarity. Though change is sudden and jarring, it clears away the false and brings truth.",
},
"XVII": {
"explanation": "The Star represents hope, guidance, and inspiration. It embodies clarity of purpose, spiritual insight, and the light that guides your path forward.",
"explanation": {
"summary": "The Star represents hope, guidance, and inspiration. It embodies clarity of purpose, spiritual insight, and the light that guides your path forward.",
"waite": "The Star, Dog-Star, or Sirius, also called fantastically the Star of the Magi. Grouped about it are seven minor luminaries, and beneath it is a naked female figure, with her left knee upon the earth and her right foot upon the water. She is in the act of pouring fluids from two vessels."
},
"interpretation": "Clairvoyance; visions; drams; hope; love; yearning; realization of inexhaustible possibilities; dreaminess; unexpected help; renewal.",
"keywords": ["hope", "faith", "inspiration", "vision", "guidance", "spirituality"],
"reversed_keywords": ["hopelessness", "despair", "lack of direction", "lost", "obscured"],
"guidance": "Let your inner light shine. Trust in your vision. Hope and guidance light your path forward.",
},
"XVIII": {
"explanation": "The Moon represents illusion, intuition, and the subconscious mind. It embodies mystery, dreams, and navigating by inner knowing rather than sight.",
"explanation": {
"summary": "The Moon represents illusion, intuition, and the subconscious mind. It embodies mystery, dreams, and navigating by inner knowing rather than sight.",
"waite": "The Moon. Some eighteenth-century cards shew the luminary on its waning side; in the debased edition of Etteilla, it is the moon at night in her plenitude, set in a heaven of stars; of recent years the moon is shewn on the side of her increase. In nearly all presentations she is shining brightly and shedding the moisture of fertilizing dew in great drops."
},
"interpretation": "The Dark night of the soul; deception; falsehood; illusion; madness; the threshold of significant change.",
"keywords": ["illusion", "intuition", "uncertainty", "subconscious", "dreams", "mystery"],
"reversed_keywords": ["clarity", "truth revealed", "release from illusion", "awakening"],
"guidance": "Trust your intuition to navigate mystery. What appears illusory contains deeper truths worth exploring.",
},
"XIX": {
"explanation": "The Sun represents joy, clarity, and vitality. It embodies success, positive energy, and the radiance of authentic self-expression.",
"explanation": {
"summary": "The Sun represents joy, clarity, and vitality. It embodies success, positive energy, and the radiance of authentic self-expression.",
"waite": "The Sun. The luminary is distinguished in older cards by chief rays that are waved and salient alternately and by secondary salient rays. It appears to shed its influence on earth not only by light and heat, but--like the moon--by drops of dew."
},
"interpretation": "Lord of the New Aeon. Spiritual emancipation. Pleasure; shamelessness; vanity; frankness. Freedom brings sanity. Glory; riches; enlightened civilization.",
"keywords": ["success", "joy", "clarity", "vitality", "warmth", "authenticity"],
"reversed_keywords": ["temporary darkness", "lost vitality", "setback", "sadness"],
"guidance": "Celebrate your success. Let your authentic self shine. Joy and clarity light your way.",
},
"XX": {
"explanation": "Judgement represents awakening, calling, and significant decisions. It embodies reckoning, rebirth, and responding to a higher calling.",
"explanation": {
"summary": "Judgement represents awakening, calling, and significant decisions. It embodies reckoning, rebirth, and responding to a higher calling.",
"waite": "The Last judgment. I have spoken of this symbol already, the form of which is essentially invariable, even in the Etteilla set. An angel sounds his trumpet per sepulchra regionum, and the dead arise. It matters little that Etteilla omits the angel, or that Dr. Papus substitutes a ridiculous figure."
},
"interpretation": "Let every act be an act of Worship; let every act be an act of Love. Final decision; judgement. Learn from the past. Prepare for the future.",
"keywords": ["awakening", "calling", "judgment", "rebirth", "evaluation", "absolution"],
"reversed_keywords": ["doubt", "self-doubt", "harsh judgment", "reluctance to change"],
"guidance": "Answer your higher calling. Evaluate with compassion. A significant awakening or decision awaits.",
},
"XXI": {
"explanation": "The World represents completion, wholeness, and fulfillment. It embodies the end of a cycle, achievement of goals, and a sense of unity.",
"explanation": {
"summary": "The World represents completion, wholeness, and fulfillment. It embodies the end of a cycle, achievement of goals, and a sense of unity.",
"waite": "The World, the Universe, or Time. The four living creatures of the Apocalypse and Ezekiel's vision, attributed to the evangelists in Christian symbolism, are grouped about an elliptic garland, as if it were a chain of flowers intended to symbolize all sensible things; within this garland there is the figure of a woman, whom the wind has girt about the loins with a light scarf, and this is all her vesture."
},
"interpretation": "Completion of the Greatk Work; patience; perseverance; stubbornness; serious meditation. Work accomplished.",
"keywords": ["completion", "fulfillment", "wholeness", "travel", "unity", "achievement"],
"reversed_keywords": ["incomplete", "blocked", "separation", "seeking closure"],
@@ -311,164 +340,567 @@ class CardDetailsRegistry:
# Minor Arcana - Swords
"Ace of Swords": {
"explanation": "The Ace of Swords represents clarity, breakthrough, and new ideas. It embodies truth emerging, mental clarity, and the power of honest communication.",
"interpretation": "New idea or perspective, clarity and truth, breakthrough thinking, mental clarity",
"keywords": ["breakthrough", "clarity", "truth", "new ideas", "communication"],
"reversed_keywords": ["confusion", "unclear communication", "hidden truth", "mental fog"],
"guidance": "A breakthrough arrives. Speak your truth with clarity. Mental clarity reveals new possibilities.",
"explanation": {
"summary": "A hand issues from a cloud, grasping as word, the point of which is encircled by a crown.",
"waite": "A hand issues from a cloud, grasping as word, the point of which is encircled by a crown. Divinatory Meanings: Triumph, the excessive degree in everything, conquest, triumph of force. It is a card of great force, in love as well as in hatred. The crown may carry a much higher significance than comes usually within the sphere of fortune-telling. Reversed: The same, but the results are disastrous; another account says--conception, childbirth, augmentation, multiplicity."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Two of Swords": {
"explanation": "The Two of Swords represents stalemate, difficult choices, and mental struggle. It embodies indecision, conflicting information, and the need for perspective.",
"interpretation": "Stalemate and indecision, difficult choices ahead, conflicting perspectives, mental struggle",
"keywords": ["stalemate", "indecision", "confusion", "difficult choice", "standoff"],
"reversed_keywords": ["clarity emerging", "decision made", "moving forward", "resolution"],
"guidance": "Step back from the conflict. You need more information or perspective before deciding.",
"explanation": {
"summary": "A hoodwinked female figure balances two swords upon her shoulders.",
"waite": "A hoodwinked female figure balances two swords upon her shoulders. Divinatory Meanings: Conformity and the equipoise which it suggests, courage, friendship, concord in a state of arms; another reading gives tenderness, affection, intimacy. The suggestion of harmony and other favourable readings must be considered in a qualified manner, as Swords generally are not symbolical of beneficent forces in human affairs. Reversed: Imposture, falsehood, duplicity, disloyalty."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Three of Swords": {
"explanation": "The Three of Swords represents heartbreak, difficult truths, and mental anguish. It embodies challenging communication, painful revelations, and clarity that hurts.",
"interpretation": "Difficult truths and heartbreak, communication challenges, mental anguish, clarity through pain",
"keywords": ["heartbreak", "sorrow", "difficult truth", "mental anguish", "separation"],
"reversed_keywords": ["healing", "moving forward", "forgiveness", "reconciliation"],
"guidance": "Difficult truths are emerging. Allow yourself to feel the pain. Healing follows acknowledgment.",
"explanation": {
"summary": "Three swords piercing a heart; cloud and rain behind.",
"waite": "Three swords piercing a heart; cloud and rain behind. Divinatory Meanings: Removal, absence, delay, division, rupture, dispersion, and all that the design signifies naturally, being too simple and obvious to call for specific enumeration. Reversed: Mental alienation, error, loss, distraction, disorder, confusion."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Four of Swords": {
"explanation": "The Four of Swords represents rest, recovery, and mental respite. It embodies the need for pause, recuperation, and gathering strength.",
"interpretation": "Rest and recovery, pause and contemplation, gathering strength, needed respite",
"keywords": ["rest", "pause", "recovery", "contemplation", "respite"],
"reversed_keywords": ["restlessness", "stress", "unwillingness to rest", "agitation"],
"guidance": "Take time to rest and recover. Your mind and spirit need respite. Gather your strength.",
"explanation": {
"summary": "The effigy of a knight in the attitude of prayer, at full length upon his tomb.",
"waite": "The effigy of a knight in the attitude of prayer, at full length upon his tomb. Divinatory Meanings: Vigilance, retreat, solitude, hermit's repose, exile, tomb and coffin. It is these last that have suggested the design. Reversed: Wise administration, circumspection, economy, avarice, precaution, testament."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Five of Swords": {
"explanation": "The Five of Swords represents conflict, victory at a cost, and difficult truths after battle. It embodies competition with consequences and the emptiness of winning wrongly.",
"interpretation": "Conflict and competition, pyrrhic victory, harsh truths, aftermath of conflict",
"keywords": ["conflict", "defeat", "victory at cost", "awkwardness", "tension"],
"reversed_keywords": ["reconciliation", "resolution", "forgiveness", "peace"],
"guidance": "Sometimes victory costs more than it's worth. Seek reconciliation over conquest.",
"explanation": {
"summary": "A disdainful man looks after two retreating and dejected figures.",
"waite": "A disdainful man looks after two retreating and dejected figures. Their swords lie upon the ground. He carries two others on his left shoulder, and a third sword is in his right hand, point to earth. He is the master in possession of the field. Divinatory Meanings: Degradation, destruction, revocation, infamy, dishonour, loss, with the variants and analogues of these. Reversed: The same; burial and obsequies."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Six of Swords": {
"explanation": "The Six of Swords represents moving forward, healing journey, and leaving troubles behind. It embodies transition, mental resolution, and the path to better days.",
"interpretation": "Moving forward and transition, leaving trouble behind, journey and travel, mental resolution",
"keywords": ["transition", "healing journey", "moving forward", "travel", "freedom"],
"reversed_keywords": ["stuck", "resistance to change", "delays", "unresolved issues"],
"guidance": "A journey of healing begins. Move forward. Leave the past behind. Better days await.",
"explanation": {
"summary": "A ferryman carrying passengers in his punt to the further shore.",
"waite": "A ferryman carrying passengers in his punt to the further shore. The course is smooth, and seeing that the freight is light, it may be noted that the work is not beyond his strength. Divinatory Meanings: journey by water, route, way, envoy, commissionary, expedient. Reversed: Declaration, confession, publicity; one account says that it is a proposal of love."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Seven of Swords": {
"explanation": "The Seven of Swords represents deception, cunning, and strategic retreat. It embodies hidden agendas, betrayal, and escape from difficult situations.",
"interpretation": "Deception and cunning, hidden agendas, strategic retreat, betrayal or self-deception",
"keywords": ["deception", "cunning", "betrayal", "hidden agenda", "strategy"],
"reversed_keywords": ["coming clean", "honesty", "truth revealed", "facing consequences"],
"guidance": "Look for hidden truths. Deception may be at play. Where are you deceiving yourself?",
"explanation": {
"summary": "A man in the act of carrying away five swords rapidly; the two others of the card remain stuck in the ground.",
"waite": "A man in the act of carrying away five swords rapidly; the two others of the card remain stuck in the ground. A camp is close at hand. Divinatory Meanings: Design, attempt, wish, hope, confidence; also quarrelling, a plan that may fail, annoyance. The design is uncertain in its import, because the significations are widely at variance with each other. Reversed: Good advice, counsel, instruction, slander, babbling."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Eight of Swords": {
"explanation": "The Eight of Swords represents restriction, bondage, and self-imposed limitations. It embodies feeling trapped, mental imprisonment, and powerlessness.",
"interpretation": "Restriction and bondage, self-imposed limitations, feeling trapped, helplessness",
"keywords": ["bondage", "restriction", "trapped", "helplessness", "powerlessness"],
"reversed_keywords": ["freedom", "release", "empowerment", "breaking free"],
"guidance": "You have more power than you believe. The restrictions may be self-imposed. Free yourself.",
"explanation": {
"summary": "A woman, bound and hoodwinked, with the swords of the card about her.",
"waite": "A woman, bound and hoodwinked, with the swords of the card about her. Yet it is rather a card of temporary durance than of irretrievable bondage. Divinatory Meanings: Bad news, violent chagrin, crisis, censure, power in trammels, conflict, calumny; also sickness. Reversed: Disquiet, difficulty, opposition, accident, treachery; what is unforeseen; fatality."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Nine of Swords": {
"explanation": "The Nine of Swords represents anxiety, nightmares, and mental torment. It embodies overthinking, worry, and the burden of negative thoughts.",
"interpretation": "Anxiety and worry, nightmares and turmoil, overthinking, mental burden",
"keywords": ["anxiety", "worry", "nightmares", "overthinking", "despair"],
"reversed_keywords": ["relief", "healing", "moving past", "mental clarity"],
"guidance": "Your mind is your greatest torment. Seek support. This darkness passes. Morning follows night.",
"explanation": {
"summary": "One seated on her couch in lamentation, with the swords over her.",
"waite": "One seated on her couch in lamentation, with the swords over her. She is as one who knows no sorrow which is like unto hers. It is a card of utter desolation. Divinatory Meanings: Death, failure, miscarriage, delay, deception, disappointment, despair. Reversed: Imprisonment, suspicion, doubt, reasonable fear, shame."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Ten of Swords": {
"explanation": "The Ten of Swords represents complete mental/emotional defeat, rock bottom, and the end of suffering. It embodies the culmination of difficulty and the promise of renewal.",
"interpretation": "Defeat and rock bottom, end of suffering, difficult conclusion, release from burden",
"keywords": ["defeat", "rock bottom", "ending", "relief", "betrayal"],
"reversed_keywords": ["recovery", "beginning again", "healing", "hope"],
"guidance": "The worst has passed. You've hit bottom. From here, only recovery is possible.",
"explanation": {
"summary": "A prostrate figure, pierced by all the swords belonging to the card.",
"waite": "A prostrate figure, pierced by all the swords belonging to the card. Divinatory Meanings: Whatsoever is intimated by the design; also pain, affliction, tears, sadness, desolation. It is not especially a card of violent death. Reversed: Advantage, profit, success, favour, but none of these are permanent; also power and authority."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Page of Swords": {
"explanation": "The Page of Swords represents curious inquiry, new ideas, and youthful intellectual energy. It embodies investigation, learning, and the drive to understand.",
"interpretation": "Curiosity and new learning, investigation and inquiry, youthful energy, intellectual development",
"keywords": ["curiosity", "inquiry", "new learning", "messages", "vigilance"],
"reversed_keywords": ["cynicism", "misinformation", "scattered thinking", "mischief"],
"guidance": "Curiosity leads to discovery. Ask questions and investigate. Knowledge empowers.",
"explanation": {
"summary": "A lithe, active figure holds a sword upright in both hands, while in the act of swift walking.",
"waite": "A lithe, active figure holds a sword upright in both hands, while in the act of swift walking. He is passing over rugged land, and about his way the clouds are collocated wildly. He is alert and lithe, looking this way and that, as if an expected enemy might appear at any moment. Divinatory Meanings: Authority, overseeing, secret service, vigilance, spying, examination, and the qualities thereto belonging. Reversed: More evil side of these qualities; what is unforeseen, unprepared state; sickness is also intimated."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Knight of Swords": {
"explanation": "The Knight of Swords represents swift action, directness, and intellectual courage. It embodies confrontation, truth-seeking, and the willingness to challenge.",
"interpretation": "Direct communication and action, intellectual courage, challenging situations, swift movement",
"keywords": ["action", "impulsiveness", "courage", "conflict", "truth"],
"reversed_keywords": ["scatter-brained", "dishonest", "confusion", "retreat"],
"guidance": "Speak your truth directly. Act with courage. Swift action brings results.",
"explanation": {
"summary": "He is riding in full course, as if scattering his enemies.",
"waite": "He is riding in full course, as if scattering his enemies. In the design he is really a prototypical hero of romantic chivalry. He might almost be Galahad, whose sword is swift and sure because he is clean of heart. Divinatory Meanings: Skill, bravery, capacity, defence, address, enmity, wrath, war, destruction, opposition, resistance, ruin. There is therefore a sense in which the card signifies death, but it carries this meaning only in its proximity to other cards of fatality. Reversed: Imprudence, incapacity, extravagance."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Queen of Swords": {
"explanation": "The Queen of Swords represents intellectual power, clarity, and independent thinking. It embodies wisdom gained through experience and clear perception.",
"interpretation": "Intellectual power and clarity, independence and perception, wisdom and experience, communication",
"keywords": ["clarity", "intelligence", "independence", "truth", "perception"],
"reversed_keywords": ["bitter", "manipulative", "cold", "cruel"],
"guidance": "Trust your keen intellect. Speak your truth with grace. Clarity empowers.",
"explanation": {
"summary": "Her right hand raises the weapon vertically and the hilt rests on an arm of her royal chair the left hand is extended, the arm raised her countenance is severe but chastened; it suggests familiarity with sorrow.",
"waite": "Her right hand raises the weapon vertically and the hilt rests on an arm of her royal chair the left hand is extended, the arm raised her countenance is severe but chastened; it suggests familiarity with sorrow. It does not represent mercy, and, her sword notwithstanding, she is scarcely a symbol of power. Divinatory Meanings: Widowhood, female sadness and embarrassment, absence, sterility, mourning, privation, separation. Reversed: Malice, bigotry, artifice, prudery, bale, deceit."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"King of Swords": {
"explanation": "The King of Swords represents mental mastery, authority through intellect, and the power of truth. It embodies leadership, clear judgment, and strategic thinking.",
"interpretation": "Mental mastery and intellect, authority and leadership, justice and fairness, clear judgment",
"keywords": ["authority", "intellect", "truth", "leadership", "justice"],
"reversed_keywords": ["tyrant", "manipulation", "abuse of power", "cruelty"],
"guidance": "Lead with intellect and integrity. Your clarity creates order. Speak truth with authority.",
"explanation": {
"summary": "Whatsoever arises out of the idea of judgment and all its connexions-power, command, authority, militant intelligence, law, offices of the crown, and so forth.",
"waite": "Whatsoever arises out of the idea of judgment and all its connexions-power, command, authority, militant intelligence, law, offices of the crown, and so forth."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Princess of Swords": {
"explanation": "The Princess of Swords represents intellectual potential, youthful curiosity, and emerging clarity. It embodies the development of mental acuity and the pursuit of knowledge.",
"interpretation": "Intellectual development and potential, emerging clarity, youthful inquiry, pursuit of truth",
"keywords": ["clarity emerging", "intellectual potential", "investigation", "truth-seeking", "perception"],
"reversed_keywords": ["confusion", "scattered thoughts", "deception", "lack of focus"],
"guidance": "Your ability to perceive truth is developing. Stay curious and focused. Clarity is emerging.",
},
# Minor Arcana - Cups
"Ace of Cups": {
"explanation": "The Ace of Cups represents new emotional beginning, love, and spiritual awakening. It embodies the opening of the heart and new emotional connections.",
"interpretation": "New emotional beginning, love and compassion, spiritual awakening, emotional clarity",
"keywords": ["love", "new emotion", "compassion", "beginning", "spirituality"],
"reversed_keywords": ["blocked emotion", "closed heart", "emotional confusion"],
"guidance": "Your heart opens to new possibilities. Emotional connections deepen. Love flows.",
"explanation": {
"summary": "The waters are beneath, and thereon are water-lilies; the hand issues from the cloud, holding in its palm the cup, from which four streams are pouring; a dove, bearing in its bill a cross-marked Host, descends to place the Wafer in the Cup; the dew of water is falling on all sides.",
"waite": "The waters are beneath, and thereon are water-lilies; the hand issues from the cloud, holding in its palm the cup, from which four streams are pouring; a dove, bearing in its bill a cross-marked Host, descends to place the Wafer in the Cup; the dew of water is falling on all sides. It is an intimation of that which may lie behind the Lesser Arcana. Divinatory Meanings: House of the true heart, joy, content, abode, nourishment, abundance, fertility; Holy Table, felicity hereof. Reversed: House of the false heart, mutation, instability, revolution."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Two of Cups": {
"explanation": "The Two of Cups represents partnership, mutual respect, and emotional connection. It embodies balance, harmony, and the foundation of relationships.",
"interpretation": "Partnership and connection, mutual respect and harmony, emotional balance, agreements",
"keywords": ["partnership", "love", "connection", "harmony", "commitment"],
"reversed_keywords": ["imbalance", "separation", "misalignment", "broken agreement"],
"guidance": "Deep connection and harmony are possible. Mutual respect forms the foundation.",
"explanation": {
"summary": "A youth and maiden are pledging one another, and above their cups rises the Caduceus of Hermes, between the great wings of which there appears a lion's head.",
"waite": "A youth and maiden are pledging one another, and above their cups rises the Caduceus of Hermes, between the great wings of which there appears a lion's head. It is a variant of a sign which is found in a few old examples of this card. Some curious emblematical meanings are attached to it, but they do not concern us in this place. Divinatory Meanings: Love, passion, friendship, affinity, union, concord, sympathy, the interrelation of the sexes, and--as a suggestion apart from all offices of divination--that desire which is not in Nature, but by which Nature is sanctified."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Three of Cups": {
"explanation": "The Three of Cups represents celebration, friendship, and community. It embodies joy, shared experiences, and the warmth of connection.",
"interpretation": "Celebration and community, friendship and joy, shared experiences, social harmony",
"keywords": ["celebration", "community", "friendship", "joy", "creativity"],
"reversed_keywords": ["isolation", "loneliness", "overindulgence", "discord"],
"guidance": "Celebrate with friends. Community and connection bring joy. Share in the abundance.",
"explanation": {
"summary": "Maidens in a garden-ground with cups uplifted, as if pledging one another.",
"waite": "Maidens in a garden-ground with cups uplifted, as if pledging one another. Divinatory Meanings: The conclusion of any matter in plenty, perfection and merriment; happy issue, victory, fulfilment, solace, healing, Reversed: Expedition, dispatch, achievement, end. It signifies also the side of excess in physical enjoyment, and the pleasures of the senses."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Four of Cups": {
"explanation": {
"summary": "A young man is seated under a tree and contemplates three cups set on the grass before him; an arm issuing from a cloud offers him another cup.",
"waite": "A young man is seated under a tree and contemplates three cups set on the grass before him; an arm issuing from a cloud offers him another cup. His expression notwithstanding is one of discontent with his environment. Divinatory Meanings: Weariness, disgust, aversion, imaginary vexations, as if the wine of this world had caused satiety only; another wine, as if a fairy gift, is now offered the wastrel, but he sees no consolation therein. This is also a card of blended pleasure. Reversed: Novelty, presage, new instruction, new relations."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Five of Cups": {
"explanation": {
"summary": "A dark, cloaked figure, looking sideways at three prone cups two others stand upright behind him; a bridge is in the background, leading to a small keep or holding.",
"waite": "A dark, cloaked figure, looking sideways at three prone cups two others stand upright behind him; a bridge is in the background, leading to a small keep or holding. Divinatory Meanings: It is a card of loss, but something remains over; three have been taken, but two are left; it is a card of inheritance, patrimony, transmission, but not corresponding to expectations; with some interpreters it is a card of marriage, but not without bitterness or frustration. Reversed: News, alliances, affinity, consanguinity, ancestry, return, false projects."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Six of Cups": {
"explanation": {
"summary": "Children in an old garden, their cups filled with flowers.",
"waite": "Children in an old garden, their cups filled with flowers. Divinatory Meanings: A card of the past and of memories, looking back, as--for example--on childhood; happiness, enjoyment, but coming rather from the past; things that have vanished. Another reading reverses this, giving new relations, new knowledge, new environment, and then the children are disporting in an unfamiliar precinct. Reversed: The future, renewal, that which will come to pass presently."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Seven of Cups": {
"explanation": {
"summary": "Strange chalices of vision, but the images are more especially those of the fantastic spirit.",
"waite": "Strange chalices of vision, but the images are more especially those of the fantastic spirit. Divinatory Meanings: Fairy favours, images of reflection, sentiment, imagination, things seen in the glass of contemplation; some attainment in these degrees, but nothing permanent or substantial is suggested. Reversed: Desire, will, determination, project."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Eight of Cups": {
"explanation": {
"summary": "A man of dejected aspect is deserting the cups of his felicity, enterprise, undertaking or previous concern.",
"waite": "A man of dejected aspect is deserting the cups of his felicity, enterprise, undertaking or previous concern. Divinatory Meanings: The card speaks for itself on the surface, but other readings are entirely antithetical--giving joy, mildness, timidity, honour, modesty. In practice, it is usually found that the card shews the decline of a matter, or that a matter which has been thought to be important is really of slight consequence--either for good or evil. Reversed: Great joy, happiness, feasting."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Nine of Cups": {
"explanation": {
"summary": "A goodly personage has feasted to his heart's content, and abundant refreshment of wine is on the arched counter behind him, seeming to indicate that the future is also assured.",
"waite": "A goodly personage has feasted to his heart's content, and abundant refreshment of wine is on the arched counter behind him, seeming to indicate that the future is also assured. The picture offers the material side only, but there are other aspects. Divinatory Meanings: Concord, contentment, physical bien-être; also victory, success, advantage; satisfaction for the Querent or person for whom the consultation is made. Reversed: Truth, loyalty, liberty; but the readings vary and include mistakes, imperfections, etc."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Ten of Cups": {
"explanation": {
"summary": "Appearance of Cups in a rainbow; it is contemplated in wonder and ecstacy by a man and woman below, evidently husband and wife.",
"waite": "Appearance of Cups in a rainbow; it is contemplated in wonder and ecstacy by a man and woman below, evidently husband and wife. His right arm is about her; his left is raised upward; she raises her right arm. The two children dancing near them have not observed the prodigy but are happy after their own manner. There is a home-scene beyond. Divinatory Meanings: Contentment, repose of the entire heart; the perfection of that state; also perfection of human love and friendship; if with several picture-cards, a person who is taking charge of the Querent's interests; also the town, village or country inhabited by the Querent. Reversed: Repose of the false heart, indignation, violence."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Page of Cups": {
"explanation": {
"summary": "A fair, pleasing, somewhat effeminate page, of studious and intent aspect, contemplates a fish rising from a cup to look at him.",
"waite": "A fair, pleasing, somewhat effeminate page, of studious and intent aspect, contemplates a fish rising from a cup to look at him. It is the pictures of the mind taking form. Divinatory Meanings: Fair young man, one impelled to render service and with whom the Querent will be connected; a studious youth; news, message; application, reflection, meditation; also these things directed to business. Reversed: Taste, inclination, attachment, seduction, deception, artifice."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Knight of Cups": {
"explanation": {
"summary": "Graceful, but not warlike; riding quietly, wearing a winged helmet, referring to those higher graces of the imagination which sometimes characterize this card.",
"waite": "Graceful, but not warlike; riding quietly, wearing a winged helmet, referring to those higher graces of the imagination which sometimes characterize this card. He too is a dreamer, but the images of the side of sense haunt him in his vision. Divinatory Meanings: Arrival, approach--sometimes that of a messenger; advances, proposition, demeanour, invitation, incitement. Reversed: Trickery, artifice, subtlety, swindling, duplicity, fraud."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Queen of Cups": {
"explanation": {
"summary": "Beautiful, fair, dreamy--as one who sees visions in a cup.",
"waite": "Beautiful, fair, dreamy--as one who sees visions in a cup. This is, however, only one of her aspects; she sees, but she also acts, and her activity feeds her dream. Divinatory Meanings: Good, fair woman; honest, devoted woman, who will do service to the Querent; loving intelligence, and hence the gift of vision; success, happiness, pleasure; also wisdom, virtue; a perfect spouse and a good mother. Reversed: The accounts vary; good woman; otherwise, distinguished woman but one not to be trusted; perverse woman; vice, dishonour, depravity."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"King of Cups": {
"explanation": {
"summary": "Fair man, man of business, law, or divinity; responsible, disposed to oblige the Querent; also equity, art and science, including those who profess science, law and art; creative intelligence.",
"waite": "Fair man, man of business, law, or divinity; responsible, disposed to oblige the Querent; also equity, art and science, including those who profess science, law and art; creative intelligence."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
# Minor Arcana - Pentacles
"Ace of Pentacles": {
"explanation": "The Ace of Pentacles represents new prosperity, material opportunity, and earthly beginnings. It embodies abundance, security, and practical gifts.",
"interpretation": "New material opportunity, abundance and prosperity, earthly beginnings, practical gifts",
"keywords": ["abundance", "opportunity", "prosperity", "security", "gift"],
"reversed_keywords": ["lost opportunity", "scarcity", "blocked prosperity"],
"guidance": "Material opportunity arrives. Seize it. Abundance begins with gratitude.",
"explanation": {
"summary": "A hand--issuing, as usual, from a cloud--holds up a pentacle.",
"waite": "A hand--issuing, as usual, from a cloud--holds up a pentacle. Divinatory Meanings: Perfect contentment, felicity, ecstasy; also speedy intelligence; gold. Reversed: The evil side of wealth, bad intelligence; also great riches. In any case it shews prosperity, comfortable material conditions, but whether these are of advantage to the possessor will depend on whether the card is reversed or not."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Two of Pentacles": {
"explanation": "The Two of Pentacles represents balance, flexibility, and managing resources. It embodies juggling priorities, adaptability, and resourcefulness.",
"interpretation": "Balance and flexibility, managing resources, adaptability, juggling priorities",
"keywords": ["balance", "flexibility", "adaptability", "resourcefulness", "management"],
"reversed_keywords": ["imbalance", "mismanagement", "chaos", "loss"],
"guidance": "Balance your priorities carefully. Flexibility allows you to manage what comes.",
"explanation": {
"summary": "A young man, in the act of dancing, has a pentacle in either hand, and they are joined by that endless cord which is like the number 8 reversed.",
"waite": "A young man, in the act of dancing, has a pentacle in either hand, and they are joined by that endless cord which is like the number 8 reversed. Divinatory Meanings: On the one hand it is represented as a card of gaiety, recreation and its connexions, which is the subject of the design; but it is read also as news and messages in writing, as obstacles, agitation, trouble, embroilment. Reversed: Enforced gaiety, simulated enjoyment, literal sense, handwriting, composition, letters of exchange."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Three of Pentacles": {
"explanation": {
"summary": "A sculptor at his work in a monastery.",
"waite": "A sculptor at his work in a monastery. Compare the design which illustrates the Eight of Pentacles. The apprentice or amateur therein has received his reward and is now at work in earnest. Divinatory Meanings: Métier, trade, skilled labour; usually, however, regarded as a card of nobility, aristocracy, renown, glory. Reversed: Mediocrity, in work and otherwise, puerility, pettiness, weakness."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Four of Pentacles": {
"explanation": {
"summary": "A crowned figure, having a pentacle over his crown, clasps another with hands and arms; two pentacles are under his feet.",
"waite": "A crowned figure, having a pentacle over his crown, clasps another with hands and arms; two pentacles are under his feet. He holds to that which he has. Divinatory Meanings: The surety of possessions, cleaving to that which one has, gift, legacy, inheritance. Reversed: Suspense, delay, opposition."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Five of Pentacles": {
"explanation": {
"summary": "Two mendicants in a snow-storm pass a lighted casement.",
"waite": "Two mendicants in a snow-storm pass a lighted casement. Divinatory Meanings: The card foretells material trouble above all, whether in the form illustrated--that is, destitution--or otherwise. For some cartomancists, it is a card of love and lovers-wife, husband, friend, mistress; also concordance, affinities. These alternatives cannot be harmonized. Reversed: Disorder, chaos, ruin, discord, profligacy."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Six of Pentacles": {
"explanation": {
"summary": "A person in the guise of a merchant weighs money in a pair of scales and distributes it to the needy and distressed.",
"waite": "A person in the guise of a merchant weighs money in a pair of scales and distributes it to the needy and distressed. It is a testimony to his own success in life, as well as to his goodness of heart. Divinatory Meanings: Presents, gifts, gratification another account says attention, vigilance now is the accepted time, present prosperity, etc. Reversed: Desire, cupidity, envy, jealousy, illusion."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Seven of Pentacles": {
"explanation": {
"summary": "A young man, leaning on his staff, looks intently at seven pentacles attached to a clump of greenery on his right; one would say that these were his treasures and that his heart was there.",
"waite": "A young man, leaning on his staff, looks intently at seven pentacles attached to a clump of greenery on his right; one would say that these were his treasures and that his heart was there. Divinatory Meanings: These are exceedingly contradictory; in the main, it is a card of money, business, barter; but one reading gives altercation, quarrels--and another innocence, ingenuity, purgation. Reversed: Cause for anxiety regarding money which it may be proposed to lend."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Eight of Pentacles": {
"explanation": {
"summary": "An artist in stone at his work, which he exhibits in the form of trophies.",
"waite": "An artist in stone at his work, which he exhibits in the form of trophies. Divinatory Meanings: Work, employment, commission, craftsmanship, skill in craft and business, perhaps in the preparatory stage. Reversed: Voided ambition, vanity, cupidity, exaction, usury. It may also signify the possession of skill, in the sense of the ingenious mind turned to cunning and intrigue."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Nine of Pentacles": {
"explanation": {
"summary": "A woman, with a bird upon her wrist, stands amidst a great abundance of grapevines in the garden of a manorial house.",
"waite": "A woman, with a bird upon her wrist, stands amidst a great abundance of grapevines in the garden of a manorial house. It is a wide domain, suggesting plenty in all things. Possibly it is her own possession and testifies to material well-being. Divinatory Meanings: Prudence, safety, success, accomplishment, certitude, discernment. Reversed: Roguery, deception, voided project, bad faith."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Ten of Pentacles": {
"explanation": {
"summary": "A man and woman beneath an archway which gives entrance to a house and domain.",
"waite": "A man and woman beneath an archway which gives entrance to a house and domain. They are accompanied by a child, who looks curiously at two dogs accosting an ancient personage seated in the foreground. The child's hand is on one of them. Divinatory Meanings: Gain, riches; family matters, archives, extraction, the abode of a family. Reversed: Chance, fatality, loss, robbery, games of hazard; sometimes gift, dowry, pension."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Page of Pentacles": {
"explanation": {
"summary": "A youthful figure, looking intently at the pentacle which hovers over his raised hands.",
"waite": "A youthful figure, looking intently at the pentacle which hovers over his raised hands. He moves slowly, insensible of that which is about him. Divinatory Meanings: Application, study, scholarship, reflection another reading says news, messages and the bringer thereof; also rule, management. Reversed: Prodigality, dissipation, liberality, luxury; unfavourable news."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Knight of Pentacles": {
"explanation": {
"summary": "He rides a slow, enduring, heavy horse, to which his own aspect corresponds.",
"waite": "He rides a slow, enduring, heavy horse, to which his own aspect corresponds. He exhibits his symbol, but does not look therein. Divinatory Meanings: Utility, serviceableness, interest, responsibility, rectitude-all on the normal and external plane. Reversed: inertia, idleness, repose of that kind, stagnation; also placidity, discouragement, carelessness."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Queen of Pentacles": {
"explanation": {
"summary": "The face suggests that of a dark woman, whose qualities might be summed up in the idea of greatness of soul; she has also the serious cast of intelligence; she contemplates her symbol and may see worlds therein.",
"waite": "The face suggests that of a dark woman, whose qualities might be summed up in the idea of greatness of soul; she has also the serious cast of intelligence; she contemplates her symbol and may see worlds therein. Divinatory Meanings: Opulence, generosity, magnificence, security, liberty. Reversed: Evil, suspicion, suspense, fear, mistrust."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"King of Pentacles": {
"explanation": {
"summary": "Valour, realizing intelligence, business and normal intellectual aptitude, sometimes mathematical gifts and attainments of this kind; success in these paths.",
"waite": "Valour, realizing intelligence, business and normal intellectual aptitude, sometimes mathematical gifts and attainments of this kind; success in these paths."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
# Minor Arcana - Wands
"Ace of Wands": {
"explanation": "The Ace of Wands represents new inspiration, creative spark, and passionate new beginning. It embodies potential, growth, and spiritual fire.",
"interpretation": "New creative spark, inspiration and potential, passionate beginning, growth opportunity",
"keywords": ["inspiration", "potential", "growth", "new beginning", "creativity"],
"reversed_keywords": ["blocked inspiration", "delays", "lost potential"],
"guidance": "Creative inspiration ignites. Channel this energy into action. Your passion becomes power.",
"explanation": {
"summary": "Creation, invention, enterprise, the powers which result in these; principle, beginning, source; birth, family, origin, and in a sense the virility which is behind them; the starting point of enterprises; according to another account, money, fortune, inheritance.",
"waite": "Creation, invention, enterprise, the powers which result in these; principle, beginning, source; birth, family, origin, and in a sense the virility which is behind them; the starting point of enterprises; according to another account, money, fortune, inheritance."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Two of Wands": {
"explanation": "The Two of Wands represents planning, future vision, and resourcefulness. It embodies potential growth, decisions about direction, and careful preparation.",
"interpretation": "Planning and vision, resource management, decisions about direction, future planning",
"keywords": ["vision", "planning", "potential", "resourcefulness", "future"],
"reversed_keywords": ["lack of vision", "poor planning", "blocked growth"],
"guidance": "Plan your future with vision. You have resources to build something great.",
"explanation": {
"summary": "Between the alternative readings there is no marriage possible; on the one hand, riches, fortune, magnificence; on the other, physical suffering, disease, chagrin, sadness, mortification.",
"waite": "Between the alternative readings there is no marriage possible; on the one hand, riches, fortune, magnificence; on the other, physical suffering, disease, chagrin, sadness, mortification. The design gives one suggestion; here is a lord overlooking his dominion and alternately contemplating a globe; it looks like the malady, the mortification, the sadness of Alexander amidst the grandeur of this world's wealth."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Three of Wands": {
"explanation": {
"summary": "He symbolizes established strength, enterprise, effort, trade, commerce, discovery; those are his ships, bearing his merchandise, which are sailing over the sea.",
"waite": "He symbolizes established strength, enterprise, effort, trade, commerce, discovery; those are his ships, bearing his merchandise, which are sailing over the sea. The card also signifies able co-operation in business, as if the successful merchant prince were looking from his side towards yours with a view to help you."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Four of Wands": {
"explanation": {
"summary": "They are for once almost on the surface--country life, haven of refuge, a species of domestic harvest-home, repose, concord, harmony, prosperity, peace, and the perfected work of these.",
"waite": "They are for once almost on the surface--country life, haven of refuge, a species of domestic harvest-home, repose, concord, harmony, prosperity, peace, and the perfected work of these."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Five of Wands": {
"explanation": {
"summary": "Imitation, as, for example, sham fight, but also the strenuous competition and struggle of the search after riches and fortune.",
"waite": "Imitation, as, for example, sham fight, but also the strenuous competition and struggle of the search after riches and fortune. In this sense it connects with the battle of life. Hence some attributions say that it is a card of gold, gain, opulence."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Six of Wands": {
"explanation": {
"summary": "The card has been so designed that it can cover several significations; on the surface, it is a victor triumphing, but it is also great news, such as might be carried in state by the King's courier; it is expectation crowned with its own desire, the crown of hope, and so forth.",
"waite": "The card has been so designed that it can cover several significations; on the surface, it is a victor triumphing, but it is also great news, such as might be carried in state by the King's courier; it is expectation crowned with its own desire, the crown of hope, and so forth."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Seven of Wands": {
"explanation": {
"summary": "It is a card of valour, for, on the surface, six are attacking one, who has, however, the vantage position.",
"waite": "It is a card of valour, for, on the surface, six are attacking one, who has, however, the vantage position. On the intellectual plane, it signifies discussion, wordy strife; in business--negotiations, war of trade, barter, competition. It is further a card of success, for the combatant is on the top and his enemies may be unable to reach him."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Eight of Wands": {
"explanation": {
"summary": "Activity in undertakings, the path of such activity, swiftness, as that of an express messenger; great haste, great hope, speed towards an end which promises assured felicity; generally, that which is on the move; also the arrows of love.",
"waite": "Activity in undertakings, the path of such activity, swiftness, as that of an express messenger; great haste, great hope, speed towards an end which promises assured felicity; generally, that which is on the move; also the arrows of love."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Nine of Wands": {
"explanation": {
"summary": "The card signifies strength in opposition.",
"waite": "The card signifies strength in opposition. If attacked, the person will meet an onslaught boldly; and his build shews, that he may prove a formidable antagonist. With this main significance there are all its possible adjuncts--delay, suspension, adjournment."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Ten of Wands": {
"explanation": {
"summary": "A card of many significances, and some of the readings cannot be harmonized.",
"waite": "A card of many significances, and some of the readings cannot be harmonized. I set aside that which connects it with honour and good faith. The chief meaning is oppression simply, but it is also fortune, gain, any kind of success, and then it is the oppression of these things. It is also a card of false-seeming, disguise, perfidy. The place which the figure is approaching may suffer from the rods that he carries. Success is stultified if the Nine of Swords follows, and if it is a question of a lawsuit, there will be certain loss."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Page of Wands": {
"explanation": {
"summary": "Dark young man, faithful, a lover, an envoy, a postman.",
"waite": "Dark young man, faithful, a lover, an envoy, a postman. Beside a man, he will bear favourable testimony concerning him. A dangerous rival, if followed by the Page of Cups. Has the chief qualities of his suit. He may signify family intelligence."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Knight of Wands": {
"explanation": {
"summary": "Departure, absence, flight, emigration.",
"waite": "Departure, absence, flight, emigration. A dark young man, friendly. Change of residence."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"Queen of Wands": {
"explanation": {
"summary": "A dark woman, countrywoman, friendly, chaste, loving, honourable.",
"waite": "A dark woman, countrywoman, friendly, chaste, loving, honourable. If the card beside her signifies a man, she is well disposed towards him; if a woman, she is interested in the Querent. Also, love of money, or a certain success in business."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
"King of Wands": {
"explanation": {
"summary": "Dark man, friendly, countryman, generally married, honest and conscientious.",
"waite": "Dark man, friendly, countryman, generally married, honest and conscientious. The card always signifies honesty, and may mean news concerning an unexpected heritage to fall in before very long."
},
"interpretation": "",
"keywords": [],
"reversed_keywords": [],
"guidance": "",
},
}
@@ -544,7 +976,7 @@ class CardDetailsRegistry:
if not details:
return False
card.explanation = details.get("explanation", "")
card.explanation = details.get("explanation", {})
card.interpretation = details.get("interpretation", "")
card.keywords = details.get("keywords", [])
card.reversed_keywords = details.get("reversed_keywords", [])

13
src/tarot/card/loader.py
View File

@@ -206,7 +206,18 @@ def print_card_details(card: 'Card', include_reversed: bool = False) -> None:
if hasattr(card, attr_name):
value = getattr(card, attr_name)
if value:
print(f"\n{display_name}:\n{value}")
if attr_name == 'explanation' and isinstance(value, dict):
print(f"\n{display_name}:")
if "summary" in value:
print(f"Summary: {value['summary']}")
if "waite" in value:
print(f"Waite: {value['waite']}")
# Print other keys if any
for k, v in value.items():
if k not in ["summary", "waite"]:
print(f"{k.capitalize()}: {v}")
else:
print(f"\n{display_name}:\n{value}")
# Print list attributes
for attr_name, display_info in list_attributes.items():

163
src/tarot/constants.py Normal file
View File

@@ -0,0 +1,163 @@
"""Shared constants and helpers for Tarot deck structure and ordering.
This module centralizes deck ordering, pip naming, and position mapping
so other modules can stay DRY and rely on a single source of truth.
"""
from typing import Dict, List, Tuple
ACE_NAME = "Ace"
# Minor sequencing and naming
# Ace is its own category (container for the suit), pips are 2-10, then face cards
PIP_ORDER: List[int] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
# Numeric pip names only (2-10). Ace is intentionally excluded because it is not a pip card.
PIP_NAMES: Dict[int, str] = {
2: "Two",
3: "Three",
4: "Four",
5: "Five",
6: "Six",
7: "Seven",
8: "Eight",
9: "Nine",
10: "Ten",
}
# Full minor rank names (Ace, 2-10, then courts)
MINOR_RANK_NAMES: Dict[int, str] = {
1: ACE_NAME,
**PIP_NAMES,
11: "Prince",
12: "Knight",
13: "Princess",
14: "Queen",
}
# Map pip-order indices to actual pip numbers (1 maps to Ace, 2-10 are pip cards)
PIP_INDEX_TO_NUMBER: Dict[int, int] = {
1: 1,
2: 2,
3: 3,
4: 4,
5: 5,
6: 6,
7: 7,
8: 8,
9: 9,
10: 10,
}
COURT_RANKS: Dict[int, str] = {
11: "Prince",
12: "Knight",
13: "Princess",
14: "Queen",
}
# Suit sequencing for the deck (number matches Suit.number)
SUITS_FIRST: List[Tuple[str, str, int]] = [
("Cups", "Water", 2),
("Pentacles", "Earth", 4),
("Swords", "Air", 3),
]
SUITS_LAST: List[Tuple[str, str, int]] = [
("Wands", "Fire", 1),
]
MAJOR_ARCANA_NAMES: List[str] = [
"Fool",
"Magus",
"Fortune",
"Lust",
"Hanged Man",
"Death",
"Art",
"Devil",
"Tower",
"Star",
"Moon",
"Sun",
"High Priestess",
"Empress",
"Emperor",
"Hierophant",
"Lovers",
"Chariot",
"Justice",
"Hermit",
"Aeon",
"Universe",
]
MAJOR_ARCANA_KEYS: List[str] = [
"o",
"I",
"II",
"III",
"IV",
"V",
"VI",
"VII",
"VIII",
"IX",
"X",
"XI",
"XII",
"XIII",
"XIV",
"XV",
"XVI",
"XVII",
"XVIII",
"XIX",
"XX",
"XXI",
]
def minor_card_names_for_suit(suit_name: str) -> List[str]:
"""Return the ordered card names for a minor suit using the shared rank order."""
return [f"{MINOR_RANK_NAMES[pip_index]} of {suit_name}" for pip_index in PIP_ORDER]
def build_position_map() -> Dict[int, str]:
"""Build the position map (1-78) aligned to deck ordering."""
position_map: Dict[int, str] = {}
pos = 1
# Cups, Pentacles, Swords (1-42)
for suit_name, _, _ in SUITS_FIRST:
for name in minor_card_names_for_suit(suit_name):
position_map[pos] = name
pos += 1
# Major Arcana (43-64)
for key in MAJOR_ARCANA_KEYS:
position_map[pos] = key
pos += 1
# Wands (65-78)
for suit_name, _, _ in SUITS_LAST:
for name in minor_card_names_for_suit(suit_name):
position_map[pos] = name
pos += 1
return position_map
__all__ = [
"ACE_NAME",
"PIP_ORDER",
"PIP_NAMES",
"MINOR_RANK_NAMES",
"PIP_INDEX_TO_NUMBER",
"COURT_RANKS",
"SUITS_FIRST",
"SUITS_LAST",
"MAJOR_ARCANA_NAMES",
"MAJOR_ARCANA_KEYS",
"minor_card_names_for_suit",
"build_position_map",
]

261
src/tarot/deck/deck.py
View File

@@ -6,13 +6,22 @@ MajorCard, and MinorCard classes for representing individual cards.
"""
from dataclasses import dataclass, field
from typing import List, Optional, Tuple, TYPE_CHECKING
from typing import List, Optional, Tuple, TYPE_CHECKING, Dict
import random
from ..attributes import (
Meaning, CardImage, Suit, Zodiac, Element, Path,
Planet, Sephera, Color, PeriodicTable, ElementType, DoublLetterTrump
)
from ..constants import (
COURT_RANKS,
MAJOR_ARCANA_NAMES,
PIP_INDEX_TO_NUMBER,
MINOR_RANK_NAMES,
PIP_ORDER,
SUITS_FIRST,
SUITS_LAST,
)
if TYPE_CHECKING:
from ..card.data import CardDataLoader
@@ -44,7 +53,7 @@ class Card:
pip: int = 0
# Card-specific details
explanation: str = ""
explanation: Dict[str, str] = field(default_factory=dict)
interpretation: str = ""
keywords: List[str] = field(default_factory=list)
reversed_keywords: List[str] = field(default_factory=list)
@@ -455,8 +464,10 @@ class Deck:
def _initialize_deck(self) -> None:
"""Initialize the deck with all 78 Tarot cards.
Order: Cups (1-14), Pentacles/Disks (15-28), Swords (29-42),
Major Arcana (43-64), Wands (65-78)
Order: Cups (1-14), Pentacles/Disks (15-28), Swords (29-42),
Major Arcana (43-64), Wands (65-78)
Minor suit sequencing (per suit): Ace, 2-10, Prince, Knight, Princess, Queen.
This puts Queen of Wands as card #78, the final card.
"""
@@ -489,99 +500,40 @@ class Deck:
"Queen": (water_element, he_path),
}
suits_data_first = [
("Cups", water_element, 2),
("Pentacles", earth_element, 4),
("Swords", air_element, 3),
]
# Pip order: Ace (1), Ten (10), Two-Nine (2-9), Knight (12), Prince (11), Princess (13), Queen (14)
pip_order = [1, 10, 2, 3, 4, 5, 6, 7, 8, 9, 12, 11, 13, 14]
pip_names = {
1: "Ace", 2: "Two", 3: "Three", 4: "Four", 5: "Five",
6: "Six", 7: "Seven", 8: "Eight", 9: "Nine", 10: "Ten",
11: "Prince", 12: "Knight", 13: "Princess", 14: "Queen"
element_lookup = {
"Water": water_element,
"Earth": earth_element,
"Air": air_element,
"Fire": fire_element,
}
def _suit_specs(suit_defs: List[Tuple[str, str, int]]) -> List[Tuple[str, ElementType, int]]:
specs: List[Tuple[str, ElementType, int]] = []
for suit_name, element_key, suit_num in suit_defs:
element_obj = element_lookup.get(element_key)
if element_obj is None:
raise RuntimeError(f"Failed to resolve element '{element_key}' for suit '{suit_name}'")
specs.append((suit_name, element_obj, suit_num))
return specs
suits_data_first = _suit_specs(SUITS_FIRST)
suits_data_last = _suit_specs(SUITS_LAST)
card_number = 1
# Pip order: Ace (1), Ten (10), Two-Nine (2-9), then Court cards Knight (12), Prince (11), Princess (13), Queen (14)
# Map pip_order indices to actual pip numbers (1-10 only for pips)
pip_index_to_number = {
1: 1, # Ace
10: 10, # Ten
2: 2, 3: 3, 4: 4, 5: 5, 6: 6, 7: 7, 8: 8, 9: 9 # Two through Nine
}
court_ranks = {
12: "Knight", 11: "Prince", 13: "Princess", 14: "Queen"
}
# Loop through first three suits
for suit_name, element_name, suit_num in suits_data_first:
suit = Suit(name=suit_name, element=element_name,
tarot_correspondence=f"{suit_name} Suit", number=suit_num)
# Then loop through each position in the custom order
for pip_index in pip_order:
# Create appropriate card type based on pip_index
if pip_index <= 10:
# Pip card (Ace through 10)
actual_pip = pip_index_to_number[pip_index]
if pip_index == 1:
# Ace card
card = AceCard(
number=card_number,
name=f"{pip_names[pip_index]} of {suit_name}",
meaning=Meaning(
upright=f"{pip_names[pip_index]} of {suit_name} upright",
reversed=f"{pip_names[pip_index]} of {suit_name} reversed"
),
arcana="Minor",
suit=suit,
pip=actual_pip
)
else:
# Regular pip card (2-10)
card = PipCard(
number=card_number,
name=f"{pip_names[pip_index]} of {suit_name}",
meaning=Meaning(
upright=f"{pip_names[pip_index]} of {suit_name} upright",
reversed=f"{pip_names[pip_index]} of {suit_name} reversed"
),
arcana="Minor",
suit=suit,
pip=actual_pip
)
else:
# Court card (no pip)
court_rank = court_ranks[pip_index]
associated_element, hebrew_letter_path = court_rank_mappings[court_rank]
card = CourtCard(
number=card_number,
name=f"{pip_names[pip_index]} of {suit_name}",
meaning=Meaning(
upright=f"{pip_names[pip_index]} of {suit_name} upright",
reversed=f"{pip_names[pip_index]} of {suit_name} reversed"
),
arcana="Minor",
suit=suit,
court_rank=court_rank,
associated_element=associated_element,
hebrew_letter_path=hebrew_letter_path
)
self.cards.append(card)
card_number += 1
for suit_name, element_obj, suit_num in suits_data_first:
card_number = self._add_minor_cards_for_suit(
suit_name,
element_obj,
suit_num,
card_number,
court_rank_mappings,
)
# Major Arcana (43-64)
# Names match filenames in src/tarot/deck/default/
major_arcana_names = [
"Fool", "Magus", "Fortune", "Lust", "Hanged Man", "Death",
"Art", "Devil", "Tower", "Star", "Moon", "Sun",
"High Priestess", "Empress", "Emperor", "Hierophant",
"Lovers", "Chariot", "Justice", "Hermit", "Aeon", "Universe"
]
for i, name in enumerate(major_arcana_names):
for i, name in enumerate(MAJOR_ARCANA_NAMES):
card = MajorCard(
number=card_number,
name=name,
@@ -596,67 +548,82 @@ class Deck:
card_number += 1
# Minor Arcana - Last suit (Wands, 65-78)
# Organized logically: Ace, 10, 2-9, then court cards Knight, Prince, Princess, Queen
suits_data_last = [
("Wands", fire_element, 1),
]
# Organized logically: Ace, 2-10, then court cards Prince, Knight, Princess, Queen
for suit_name, element_obj, suit_num in suits_data_last:
card_number = self._add_minor_cards_for_suit(
suit_name,
element_obj,
suit_num,
card_number,
court_rank_mappings,
)
# Loop through last suit
for suit_name, element_name, suit_num in suits_data_last:
suit = Suit(name=suit_name, element=element_name,
tarot_correspondence=f"{suit_name} Suit", number=suit_num)
# Load detailed explanations and keywords from registry
try:
from ..card.loader import load_deck_details
load_deck_details(self)
except ImportError:
# Handle case where loader might not be available or circular import issues
pass
# Then loop through each position in the custom order
for pip_index in pip_order:
# Create appropriate card type based on pip_index
if pip_index <= 10:
# Pip card (Ace through 10)
actual_pip = pip_index_to_number[pip_index]
if pip_index == 1:
# Ace card
card = AceCard(
number=card_number,
name=f"{pip_names[pip_index]} of {suit_name}",
meaning=Meaning(
upright=f"{pip_names[pip_index]} of {suit_name} upright",
reversed=f"{pip_names[pip_index]} of {suit_name} reversed"
),
arcana="Minor",
suit=suit,
pip=actual_pip
)
else:
# Regular pip card (2-10)
card = PipCard(
number=card_number,
name=f"{pip_names[pip_index]} of {suit_name}",
meaning=Meaning(
upright=f"{pip_names[pip_index]} of {suit_name} upright",
reversed=f"{pip_names[pip_index]} of {suit_name} reversed"
),
arcana="Minor",
suit=suit,
pip=actual_pip
)
def _add_minor_cards_for_suit(
self,
suit_name: str,
element_obj: ElementType,
suit_num: int,
card_number: int,
court_rank_mappings: Dict[str, Tuple[ElementType, Path]],
) -> int:
"""Add all minor cards for a suit using shared ordering constants."""
suit = Suit(
name=suit_name,
element=element_obj,
tarot_correspondence=f"{suit_name} Suit",
number=suit_num,
)
for pip_index in PIP_ORDER:
if pip_index <= 10:
actual_pip = PIP_INDEX_TO_NUMBER[pip_index]
name = f"{MINOR_RANK_NAMES[pip_index]} of {suit_name}"
card_kwargs = {
"number": card_number,
"name": name,
"meaning": Meaning(
upright=f"{name} upright",
reversed=f"{name} reversed",
),
"arcana": "Minor",
"suit": suit,
"pip": actual_pip,
}
if pip_index == 1:
card = AceCard(**card_kwargs)
else:
# Court card (no pip)
court_rank = court_ranks[pip_index]
associated_element, hebrew_letter_path = court_rank_mappings[court_rank]
card = CourtCard(
number=card_number,
name=f"{pip_names[pip_index]} of {suit_name}",
meaning=Meaning(
upright=f"{pip_names[pip_index]} of {suit_name} upright",
reversed=f"{pip_names[pip_index]} of {suit_name} reversed"
),
arcana="Minor",
suit=suit,
court_rank=court_rank,
associated_element=associated_element,
hebrew_letter_path=hebrew_letter_path
)
self.cards.append(card)
card_number += 1
card = PipCard(**card_kwargs)
else:
court_rank = COURT_RANKS[pip_index]
associated_element, hebrew_letter_path = court_rank_mappings[court_rank]
name = f"{MINOR_RANK_NAMES[pip_index]} of {suit_name}"
card = CourtCard(
number=card_number,
name=name,
meaning=Meaning(
upright=f"{name} upright",
reversed=f"{name} reversed",
),
arcana="Minor",
suit=suit,
court_rank=court_rank,
associated_element=associated_element,
hebrew_letter_path=hebrew_letter_path,
)
self.cards.append(card)
card_number += 1
return card_number
def shuffle(self) -> None:

872
src/tarot/ui.py Normal file
View File

@@ -0,0 +1,872 @@
"""
User interface components for displaying Tarot cards.
This module provides a Tkinter-based image displayer for Tarot cards,
supporting multiple decks and automatic image resolution.
"""
import os
import tkinter as tk
from tkinter import ttk
from pathlib import Path
from typing import List, Optional
try:
from PIL import Image, ImageTk
HAS_PILLOW = True
except ImportError:
HAS_PILLOW = False
from tarot.deck import Card
from tarot.card.image_loader import ImageDeckLoader
class CardDisplay:
"""
Displays Tarot cards using Tkinter and Pillow.
"""
def __init__(self, deck_name: str = "default"):
"""
Initialize the displayer with a specific deck.
Args:
deck_name: Name of the deck folder in src/tarot/deck/
"""
self.deck_name = deck_name
self.deck_path = self._resolve_deck_path(deck_name)
self.loader: Optional[ImageDeckLoader] = None
if self.deck_path.exists() and self.deck_path.is_dir():
try:
self.loader = ImageDeckLoader(str(self.deck_path))
except Exception as e:
print(f"Warning: Failed to initialize deck loader for '{deck_name}': {e}")
else:
print(f"Warning: Deck folder not found: {self.deck_path}")
def _resolve_deck_path(self, deck_name: str) -> Path:
"""Resolve the path to the deck folder."""
# src/tarot/ui.py -> src/tarot -> src/tarot/deck
current_dir = Path(__file__).parent
return current_dir / "deck" / deck_name
def show_cards(self, cards: List[Card], title: str = "Tarot Spread"):
"""
Display the given cards in a window using SpreadDisplay.
Args:
cards: List of Card objects to display.
title: Window title.
"""
if not HAS_PILLOW:
print("Error: Pillow library is not installed. Cannot display images.")
print("Please install it with: pip install Pillow")
return
# Import spread classes here to avoid circular imports if any
from tarot.card.spread import SpreadPosition, DrawnCard, SpreadReading
# Create a dummy spread class since Spread requires a valid name
class SimpleSpread:
def __init__(self, name, description):
self.name = name
self.description = description
self.positions = []
# Create positions and drawn cards
drawn_cards = []
positions = []
for i, card in enumerate(cards, 1):
# Create a generic position
pos = SpreadPosition(
number=i,
name=f"Card {i}",
meaning="Display Card"
)
positions.append(pos)
# Create drawn card
drawn = DrawnCard(
position=pos,
card=card,
is_reversed=False
)
drawn_cards.append(drawn)
# Create a synthetic spread
spread = SimpleSpread("Card List", title)
spread.positions = positions
# Create reading
reading = SpreadReading(spread, drawn_cards) # type: ignore
# Use SpreadDisplay
display = SpreadDisplay(reading, self.deck_name)
display.root.title(f"{title} - {self.deck_name}")
display.run()
class CubeDisplay:
"""
Displays the Cube of Space with navigation.
"""
NAVIGATION = {
"North": {"Right": "East", "Left": "West", "Up": "Above", "Down": "Below"},
"South": {"Right": "West", "Left": "East", "Up": "Above", "Down": "Below"},
"East": {"Right": "South", "Left": "North", "Up": "Above", "Down": "Below"},
"West": {"Right": "North", "Left": "South", "Up": "Above", "Down": "Below"},
"Above": {"Right": "East", "Left": "West", "Up": "South", "Down": "North"},
"Below": {"Right": "East", "Left": "West", "Up": "North", "Down": "South"},
}
def __init__(self, cube, deck_name: str = "default"):
self.cube = cube
self.deck_name = deck_name
self.current_wall_name = "North"
self.card_display = CardDisplay(deck_name)
self.root = None
self.content_frame = None
self.zoom_level = 1.0
def show(self):
"""Open the Cube display window."""
if not HAS_PILLOW:
print("Error: Pillow library is not installed. Cannot display images.")
return
self.root = tk.Tk()
self.root.title("Cube of Space")
# Bind arrow keys for navigation
self.root.bind("<Up>", lambda e: self._navigate("Up"))
self.root.bind("<Down>", lambda e: self._navigate("Down"))
self.root.bind("<Left>", lambda e: self._navigate("Left"))
self.root.bind("<Right>", lambda e: self._navigate("Right"))
# Bind zoom keys (+ and -)
self.root.bind("<plus>", lambda e: self._zoom(1.1))
self.root.bind("<equal>", lambda e: self._zoom(1.1)) # Often same key as plus
self.root.bind("<minus>", lambda e: self._zoom(0.9))
self.root.bind("<underscore>", lambda e: self._zoom(0.9)) # Shift+minus
self.root.bind("<KP_Add>", lambda e: self._zoom(1.1)) # Numpad +
self.root.bind("<KP_Subtract>", lambda e: self._zoom(0.9)) # Numpad -
# Bind WASD for panning
self.root.bind("w", lambda e: self._pan_key("up"))
self.root.bind("a", lambda e: self._pan_key("left"))
self.root.bind("s", lambda e: self._pan_key("down"))
self.root.bind("d", lambda e: self._pan_key("right"))
self.root.bind("W", lambda e: self._pan_key("up"))
self.root.bind("A", lambda e: self._pan_key("left"))
self.root.bind("S", lambda e: self._pan_key("down"))
self.root.bind("D", lambda e: self._pan_key("right"))
# Main container (fills window)
self.main_frame = ttk.Frame(self.root)
self.main_frame.pack(fill=tk.BOTH, expand=True)
# Canvas for panning/zooming
self.canvas = tk.Canvas(self.main_frame, bg="#f0f0f0")
self.canvas.pack(fill=tk.BOTH, expand=True)
# Panning bindings
self.canvas.bind("<ButtonPress-1>", self._start_pan)
self.canvas.bind("<B1-Motion>", self._pan)
# Content Frame (inside canvas)
self.content_frame = ttk.Frame(self.canvas)
self.canvas_window = self.canvas.create_window((0, 0), window=self.content_frame, anchor="center")
# Overlay Controls
# Navigation Frame (Bottom Center)
nav_frame = ttk.Frame(self.main_frame, relief="solid", borderwidth=1)
nav_frame.place(relx=0.5, rely=0.95, anchor="s")
# Zoom Frame (Top Right)
zoom_frame = ttk.Frame(self.main_frame, relief="solid", borderwidth=1)
zoom_frame.place(relx=0.95, rely=0.05, anchor="ne")
# Populate Zoom Frame
ttk.Label(zoom_frame, text="Zoom:").pack(side=tk.LEFT, padx=5)
ttk.Button(zoom_frame, text="+", width=3, command=lambda: self._zoom(1.22)).pack(side=tk.LEFT)
ttk.Button(zoom_frame, text="-", width=3, command=lambda: self._zoom(0.82)).pack(side=tk.LEFT)
# Populate Navigation Frame
dir_frame = ttk.Frame(nav_frame)
dir_frame.pack(side=tk.TOP, padx=5, pady=5)
ttk.Button(dir_frame, text="Up", command=lambda: self._navigate("Up")).pack(side=tk.TOP)
mid_nav = ttk.Frame(dir_frame)
mid_nav.pack(side=tk.TOP)
ttk.Button(mid_nav, text="Left", command=lambda: self._navigate("Left")).pack(side=tk.LEFT, padx=5)
ttk.Button(mid_nav, text="Right", command=lambda: self._navigate("Right")).pack(side=tk.LEFT, padx=5)
ttk.Button(dir_frame, text="Down", command=lambda: self._navigate("Down")).pack(side=tk.TOP)
# Initial render
self._update_display()
# Center window
self.root.update_idletasks()
width = 800
height = 900
screen_width = self.root.winfo_screenwidth()
screen_height = self.root.winfo_screenheight()
x = (screen_width // 2) - (width // 2)
y = (screen_height // 2) - (height // 2)
self.root.geometry(f'{width}x{height}+{x}+{y}')
# Ensure window has focus for keyboard events
self.root.focus_force()
self.root.mainloop()
def _start_pan(self, event):
"""Start panning operation."""
self.canvas.scan_mark(event.x_root, event.y_root)
def _pan(self, event):
"""Pan the canvas."""
self.canvas.scan_dragto(event.x_root, event.y_root, gain=1)
def _pan_key(self, direction):
"""Pan the canvas using keys."""
if direction == 'up':
self.canvas.yview_scroll(-1, "units")
elif direction == 'down':
self.canvas.yview_scroll(1, "units")
elif direction == 'left':
self.canvas.xview_scroll(-1, "units")
elif direction == 'right':
self.canvas.xview_scroll(1, "units")
def _zoom(self, factor):
"""Adjust zoom level and redraw, keeping the view centered."""
# 1. Capture current state
canvas_width = self.canvas.winfo_width()
canvas_height = self.canvas.winfo_height()
# Center of viewport in canvas coordinates
cx = self.canvas.canvasx(canvas_width / 2)
cy = self.canvas.canvasy(canvas_height / 2)
# Content position
bbox = self.canvas.bbox("all")
if not bbox:
# Should not happen if initialized
self.zoom_level *= factor
self.zoom_level = max(0.1, min(self.zoom_level, 50.0))
self._update_display()
return
content_left = bbox[0]
content_top = bbox[1]
# Point relative to content
rel_x = cx - content_left
rel_y = cy - content_top
# 2. Update zoom level
old_zoom = self.zoom_level
self.zoom_level *= factor
# Clamp zoom level
self.zoom_level = max(0.1, min(self.zoom_level, 50.0))
# Calculate effective factor in case of clamping
effective_factor = self.zoom_level / old_zoom if old_zoom > 0 else factor
# 3. Update display
self._update_display()
# 4. Restore position
# New content position
new_bbox = self.canvas.bbox("all")
if not new_bbox:
return
new_content_left = new_bbox[0]
new_content_top = new_bbox[1]
scroll_width = new_bbox[2] - new_bbox[0]
scroll_height = new_bbox[3] - new_bbox[1]
# Target point in new content
new_rel_x = rel_x * effective_factor
new_rel_y = rel_y * effective_factor
# Target canvas coordinate for center
target_cx = new_content_left + new_rel_x
target_cy = new_content_top + new_rel_y
# We want target_cx to be at screen center (canvas_width/2)
# So left of view should be:
view_left = target_cx - (canvas_width / 2)
view_top = target_cy - (canvas_height / 2)
# Apply scroll
if scroll_width > canvas_width:
frac_x = (view_left - new_bbox[0]) / scroll_width
self.canvas.xview_moveto(frac_x)
if scroll_height > canvas_height:
frac_y = (view_top - new_bbox[1]) / scroll_height
self.canvas.yview_moveto(frac_y)
def _navigate(self, direction: str):
"""Navigate to the next wall based on direction."""
next_wall = self.NAVIGATION.get(self.current_wall_name, {}).get(direction)
if next_wall:
self.current_wall_name = next_wall
self._update_display()
def _update_display(self):
"""Render the current wall."""
if self.content_frame is None:
return
# Clear content frame
for widget in self.content_frame.winfo_children():
widget.destroy()
# Title
ttk.Label(self.content_frame, text=f"Wall: {self.current_wall_name}",
font=("Helvetica", 16, "bold")).pack(pady=(0, 20))
# Grid for directions
grid_frame = ttk.Frame(self.content_frame)
grid_frame.pack()
wall = self.cube.wall(self.current_wall_name)
# Map directions to grid positions (row, col)
# 3x3 Grid
layout = {
"North": (0, 1),
"West": (1, 0),
"Center": (1, 1),
"East": (1, 2),
"South": (2, 1)
}
# Calculate sizes based on zoom
cell_width = int(200 * self.zoom_level)
cell_height = int(250 * self.zoom_level)
img_height = int(200 * self.zoom_level)
# Keep images alive
self.root.images = []
for dir_name, (row, col) in layout.items():
direction = wall.direction(dir_name)
cell_frame = ttk.Frame(grid_frame, borderwidth=1, relief="solid", width=cell_width, height=cell_height)
cell_frame.grid(row=row, column=col, padx=5, pady=5)
cell_frame.grid_propagate(False)
if direction:
card = self._find_card_for_direction(direction)
if card:
# Try to load image
img_path = None
if self.card_display.loader:
img_path = self.card_display.loader.get_image_path(card)
if not img_path and card.image_path:
img_path = card.image_path
if img_path and os.path.exists(img_path):
try:
pil_img = Image.open(img_path)
# Resize for grid
base_height = img_height
h_percent = (base_height / float(pil_img.size[1]))
w_size = int((float(pil_img.size[0]) * float(h_percent)))
pil_img = pil_img.resize((w_size, base_height), Image.Resampling.LANCZOS)
tk_img = ImageTk.PhotoImage(pil_img)
self.root.images.append(tk_img)
lbl = tk.Label(cell_frame, image=tk_img, bg="black")
lbl.place(relx=0.5, rely=0.5, anchor="center")
except Exception:
self._render_text_fallback(cell_frame, direction, card.name)
else:
self._render_text_fallback(cell_frame, direction, card.name)
else:
self._render_text_fallback(cell_frame, direction)
else:
ttk.Label(cell_frame, text="Empty").place(relx=0.5, rely=0.5, anchor="center")
# Update canvas scrollregion
self.content_frame.update_idletasks()
self.canvas.config(scrollregion=self.canvas.bbox("all"))
# Center content initially if it fits
canvas_width = self.canvas.winfo_width()
canvas_height = self.canvas.winfo_height()
content_width = self.content_frame.winfo_reqwidth()
content_height = self.content_frame.winfo_reqheight()
if canvas_width > content_width and canvas_height > content_height:
self.canvas.coords(self.canvas_window, canvas_width/2, canvas_height/2)
else:
# Reset to top-left or center of scroll region
self.canvas.coords(self.canvas_window, content_width/2, content_height/2)
# Bind panning events to all content widgets
self._bind_recursive(self.content_frame)
def _bind_recursive(self, widget):
"""Recursively bind panning events to widget and its children."""
self._bind_pan_events(widget)
for child in widget.winfo_children():
self._bind_recursive(child)
def _bind_pan_events(self, widget):
"""Bind panning events to a widget."""
widget.bind("<ButtonPress-1>", self._start_pan)
widget.bind("<B1-Motion>", self._pan)
def _render_text_fallback(self, parent, direction, card_name=None):
text = f"{direction.name}\n{direction.letter}"
if card_name:
text += f"\n({card_name})"
ttk.Label(parent, text=text, justify="center").place(relx=0.5, rely=0.5, anchor="center")
def _find_card_for_direction(self, direction) -> Optional[Card]:
"""Find the Tarot card associated with a wall direction."""
from tarot.tarot_api import Tarot
letter_name = direction.letter
if not letter_name:
return None
# Find path with this letter
paths = Tarot.tree.path()
target_path = None
for p in paths.values():
if p.hebrew_letter.lower() == letter_name.lower():
target_path = p
break
if target_path and target_path.tarot_trump:
# Find card by name (fuzzy match)
trump_name = target_path.tarot_trump.lower()
for card in Tarot.deck.card.filter():
c_name = card.name.lower()
# Check if card name is contained in trump name (e.g. "fool" in "0 - the fool")
# Or if trump name is contained in card name
if c_name in trump_name or trump_name in c_name:
return card
return None
def display_cards(cards: List[Card], deck_name: str = "default"):
"""
Convenience function to display cards.
Args:
cards: List of Card objects to display
deck_name: Name of the deck to use (folder name in src/tarot/deck/)
"""
display = CardDisplay(deck_name)
display.show_cards(cards)
def display_cube(cube=None, deck_name: str = "default"):
"""
Display the Cube of Space with interactive navigation.
Args:
cube: Cube object (optional, defaults to Tarot.cube)
deck_name: Name of the deck to use
"""
if cube is None:
from tarot.tarot_api import Tarot
cube = Tarot.cube
display = CubeDisplay(cube, deck_name)
display.show()
class SpreadDisplay:
"""
Displays a Tarot spread visually using Tkinter and Pillow.
"""
# Layout definitions: {spread_name: {position_number: {'pos': (x, y), 'rotate': degrees}}}
# Coordinates are relative grid units (approx card width/height)
# Using 1.02 spacing for tight layout
LAYOUTS = {
'Celtic Cross': {
1: {'pos': (0, 0)},
2: {'pos': (0, 0), 'rotate': 90, 'z': 10}, # Top layer
3: {'pos': (0, -1.02)},
4: {'pos': (0, 1.02)},
5: {'pos': (-1.02, 0)},
6: {'pos': (1.02, 0)},
7: {'pos': (2.1, 1.53)}, # 1.5 * 1.02
8: {'pos': (2.1, 0.51)}, # 0.5 * 1.02
9: {'pos': (2.1, -0.51)},
10: {'pos': (2.1, -1.53)}
},
'3-Card Spread': {
1: {'pos': (-1.02, 0)},
2: {'pos': (0, 0)},
3: {'pos': (1.02, 0)}
},
'Golden Dawn 3-Card': {
1: {'pos': (0, -1.02)},
2: {'pos': (-1.02, 0.8)},
3: {'pos': (1.02, 0.8)}
},
'Horseshoe': {
1: {'pos': (-3.06, 1.02)},
2: {'pos': (-2.04, 0)},
3: {'pos': (-1.02, -0.51)},
4: {'pos': (0, -1.02)},
5: {'pos': (1.02, -0.51)},
6: {'pos': (2.04, 0)},
7: {'pos': (3.06, 1.02)}
},
'Pentagram': {
1: {'pos': (0, -1.5)}, # Spirit (Top)
2: {'pos': (1.5, -0.4)}, # Fire (Right Top)
3: {'pos': (1.0, 1.5)}, # Water (Right Bottom)
4: {'pos': (-1.0, 1.5)}, # Air (Left Bottom)
5: {'pos': (-1.5, -0.4)} # Earth (Left Top)
},
'Relationship': {
1: {'pos': (-1.5, 0)}, # You
2: {'pos': (1.5, 0)}, # Them
3: {'pos': (0, -1.02)}, # Relationship (Center Top)
4: {'pos': (0, 0.5)}, # Challenge (Center Bottom)
5: {'pos': (0, 2.0)} # Outcome (Bottom)
},
'Yes or No': {
1: {'pos': (0, 0)}
}
}
def __init__(self, reading, deck_name="default"):
self.reading = reading
self.root = tk.Tk()
self.root.title(f"Tarot Spread: {reading.spread.name}")
self.root.geometry("1200x900")
self.zoom_level = 1.0
self.show_text = True
self.show_top_card = True
self.drag_data = {"x": 0, "y": 0}
self._tk_images = [] # Keep references
# Setup UI
self._setup_ui()
# Load images
current_dir = Path(__file__).parent
deck_path = current_dir / "deck" / deck_name
self.image_loader = None
if deck_path.exists() and deck_path.is_dir():
try:
self.image_loader = ImageDeckLoader(str(deck_path))
except Exception as e:
print(f"Warning: Failed to initialize deck loader: {e}")
# Initial draw
self._draw_spread()
# Center view
self._center_view()
def _setup_ui(self):
# Toolbar
toolbar = ttk.Frame(self.root)
toolbar.pack(side=tk.TOP, fill=tk.X)
ttk.Button(toolbar, text="Zoom In (+)", command=lambda: self._zoom(1.2)).pack(side=tk.LEFT, padx=2)
ttk.Button(toolbar, text="Zoom Out (-)", command=lambda: self._zoom(0.8)).pack(side=tk.LEFT, padx=2)
ttk.Button(toolbar, text="Reset View", command=self._reset_view).pack(side=tk.LEFT, padx=2)
ttk.Button(toolbar, text="Toggle Text", command=self._toggle_text).pack(side=tk.LEFT, padx=2)
# Only show toggle top card if relevant
if self.reading.spread.name == 'Celtic Cross':
ttk.Button(toolbar, text="Toggle Cross", command=self._toggle_top_card).pack(side=tk.LEFT, padx=2)
# Canvas
self.canvas = tk.Canvas(self.root, bg="#2c3e50")
self.canvas.pack(fill=tk.BOTH, expand=True)
# Bindings
self.canvas.bind("<ButtonPress-1>", self._on_drag_start)
self.canvas.bind("<B1-Motion>", self._on_drag_motion)
self.canvas.bind("<MouseWheel>", self._on_mousewheel)
# Linux scroll
self.canvas.bind("<Button-4>", lambda e: self._zoom(1.1))
self.canvas.bind("<Button-5>", lambda e: self._zoom(0.9))
def _draw_spread(self):
self.canvas.delete("all")
self._tk_images.clear()
layout = self.LAYOUTS.get(self.reading.spread.name)
if not layout:
# Fallback to grid if layout not defined
self._draw_grid_fallback()
return
# Base dimensions
card_width = 100 * self.zoom_level
card_height = 150 * self.zoom_level
# Spacing units
unit_x = card_width
unit_y = card_height
# Center of virtual space (arbitrary large number to allow scrolling)
cx, cy = 2000, 2000
min_x, min_y = float('inf'), float('inf')
max_x, max_y = float('-inf'), float('-inf')
# Sort cards by z-index (default 0)
cards_to_draw = []
for drawn in self.reading.drawn_cards:
pos_data = layout.get(drawn.position.number)
if not pos_data:
continue
z_index = pos_data.get('z', 0)
# Skip if top card is hidden
if z_index > 0 and not self.show_top_card:
continue
cards_to_draw.append((drawn, pos_data, z_index))
# Sort by z-index ascending
cards_to_draw.sort(key=lambda x: x[2])
for drawn, pos_data, _ in cards_to_draw:
rel_x, rel_y = pos_data['pos']
rotation = pos_data.get('rotate', 0)
# Calculate position
x = cx + (rel_x * unit_x)
y = cy + (rel_y * unit_y)
# Update bounds
# x, y is center
half_w = card_width / 2
half_h = card_height / 2
# If rotated 90 deg, width and height swap for bounding box
if abs(rotation % 180) == 90:
half_w, half_h = half_h, half_w
min_x = min(min_x, x - half_w)
max_x = max(max_x, x + half_w)
min_y = min(min_y, y - half_h)
max_y = max(max_y, y + half_h)
# Draw card
self._draw_card(drawn, x, y, card_width, card_height, rotation)
# Set scroll region
padding = 50 * self.zoom_level
self.canvas.configure(scrollregion=(min_x - padding, min_y - padding, max_x + padding, max_y + padding))
def _draw_card(self, drawn, x, y, w, h, layout_rotation):
card_name = drawn.card.name
# Get image
pil_image = None
if self.image_loader:
img_path = self.image_loader.get_image_path(drawn.card)
if img_path and os.path.exists(img_path):
try:
pil_image = Image.open(img_path)
except Exception as e:
print(f"Error loading image for {card_name}: {e}")
if not pil_image:
# Draw placeholder
self.canvas.create_rectangle(x-w/2, y-h/2, x+w/2, y+h/2, fill="white", outline="black")
self.canvas.create_text(x, y, text=card_name, width=w-10)
else:
# Total rotation
rotation = layout_rotation
if drawn.is_reversed:
rotation += 180
# Resize
# Note: We resize to w, h BEFORE rotation for consistency with layout
pil_image = pil_image.resize((int(w), int(h)), Image.Resampling.LANCZOS)
# Rotate
if rotation % 360 != 0:
pil_image = pil_image.rotate(rotation, expand=True)
# Convert to ImageTk
tk_image = ImageTk.PhotoImage(pil_image)
self._tk_images.append(tk_image)
self.canvas.create_image(x, y, image=tk_image)
if not self.show_text:
return
# Text Overlay
# Calculate visual dimensions
is_vertical = (layout_rotation % 180 == 0)
vis_w = w if is_vertical else h
vis_h = h if is_vertical else w
# Font setup
font_size = max(8, int(10 * self.zoom_level))
# Background rectangle for text (bottom of card)
# Height needed: approx 3 lines of text
text_h = font_size * 3.5
bg_x1 = x - vis_w/2
bg_y1 = y + vis_h/2 - text_h
bg_x2 = x + vis_w/2
bg_y2 = y + vis_h/2
# Draw semi-transparent-ish background (stipple works on some platforms, otherwise solid)
self.canvas.create_rectangle(
bg_x1, bg_y1, bg_x2, bg_y2,
fill="#000000", stipple="gray75", outline=""
)
# Position Name
self.canvas.create_text(
x, bg_y1 + font_size,
text=f"{drawn.position.number}. {drawn.position.name}",
fill="white",
font=("Arial", font_size, "bold"),
width=vis_w - 4,
justify="center"
)
# Meaning (shortened)
self.canvas.create_text(
x, bg_y1 + font_size * 2.2,
text=drawn.position.meaning,
fill="#ecf0f1",
font=("Arial", int(font_size * 0.8)),
width=vis_w - 4,
justify="center"
)
def _draw_grid_fallback(self):
# Simple grid layout if no specific layout defined
cx, cy = 2000, 2000
card_width = 100 * self.zoom_level
card_height = 150 * self.zoom_level
padding = 20 * self.zoom_level
min_x, min_y = float('inf'), float('inf')
max_x, max_y = float('-inf'), float('-inf')
cols = 5
for i, drawn in enumerate(self.reading.drawn_cards):
row = i // cols
col = i % cols
x = cx + (col - cols/2) * (card_width + padding)
y = cy + (row * 1.5) * (card_height + padding)
self._draw_card(drawn, x, y, card_width, card_height, 0)
# Update bounds (x,y is center)
half_w = card_width / 2
half_h = card_height / 2
min_x = min(min_x, x - half_w)
max_x = max(max_x, x + half_w)
min_y = min(min_y, y - half_h)
max_y = max(max_y, y + half_h)
if min_x == float('inf'): # No cards
min_x, min_y, max_x, max_y = cx, cy, cx, cy
scroll_padding = 50 * self.zoom_level
self.canvas.configure(scrollregion=(
min_x - scroll_padding,
min_y - scroll_padding,
max_x + scroll_padding,
max_y + scroll_padding
))
def _zoom(self, factor):
self.zoom_level *= factor
self.zoom_level = max(0.1, min(self.zoom_level, 5.0))
self._draw_spread()
def _toggle_text(self):
self.show_text = not self.show_text
self._draw_spread()
def _toggle_top_card(self):
self.show_top_card = not self.show_top_card
self._draw_spread()
def _reset_view(self):
self.zoom_level = 1.0
self._draw_spread()
self._center_view()
def _center_view(self):
# Center the scroll region in the window
# This is a bit tricky in Tkinter without knowing window size,
# but we can try to scroll to the center of our virtual space (2000, 2000)
# We'll just scroll to the middle of the scrollregion
self.root.update_idletasks()
region = self.canvas.bbox("all")
if region:
# Scroll to center of content
# This requires math with xview_moveto which takes a fraction
# For simplicity, we'll just leave it or try to center roughly
pass
def _on_drag_start(self, event):
self.canvas.scan_mark(event.x, event.y)
def _on_drag_motion(self, event):
self.canvas.scan_dragto(event.x, event.y, gain=1)
def _on_mousewheel(self, event):
if event.delta > 0:
self._zoom(1.1)
else:
self._zoom(0.9)
def run(self):
self.root.mainloop()
def display_spread(reading, deck_name="default"):
"""
Opens a window displaying the given spread reading.
Args:
reading: A SpreadReading object returned by Tarot.deck.card.spread()
deck_name: Name of the deck to use (default: "default")
"""
if not HAS_PILLOW:
print("Pillow library not found. Cannot display graphical spread.")
print(reading)
return
display = SpreadDisplay(reading, deck_name)
display.run()

9
src/utils/object_formatting.py
View File

@@ -30,8 +30,10 @@ def is_nested_object(obj: Any) -> bool:
"""
Check if object is a nested/complex object (not a scalar type).
Returns True for dataclasses and objects with __dict__ that aren't scalars.
Returns True for dataclasses, dicts, and objects with __dict__ that aren't scalars.
"""
if isinstance(obj, dict):
return True
if is_dataclass(obj):
return True
return hasattr(obj, '__dict__') and not isinstance(obj, SCALAR_TYPES)
@@ -77,10 +79,13 @@ def get_object_attributes(obj: Any) -> List[Tuple[str, Any]]:
Extract all public attributes from an object.
Returns list of (name, value) tuples, skipping private attributes (starting with '_').
Works with both dataclasses and regular objects with __dict__.
Works with dataclasses, dicts, and regular objects with __dict__.
"""
attributes = []
if isinstance(obj, dict):
return list(obj.items())
if is_dataclass(obj):
for field_name in obj.__dataclass_fields__:
value = getattr(obj, field_name, None)

10
test_visual_spread_v2.py Normal file
View File

@@ -0,0 +1,10 @@
from tarot import Tarot
from tarot.ui import display_spread
# Draw a spread
print("Drawing Celtic Cross spread...")
reading = Tarot.deck.card.spread("Celtic Cross")
# Display it
print("Displaying spread...")
display_spread(reading)

37
tests/test_card_display.py Normal file
View File

@@ -0,0 +1,37 @@
import pytest
from tarot.ui import CardDisplay
from tarot.deck import Card
from unittest.mock import MagicMock, patch
def test_card_display_delegation():
"""Test that CardDisplay delegates to SpreadDisplay correctly."""
with patch('tarot.ui.SpreadDisplay') as MockSpreadDisplay:
# Mock HAS_PILLOW to True to ensure we proceed
with patch('tarot.ui.HAS_PILLOW', True):
display = CardDisplay()
# Create dummy card
card = MagicMock(spec=Card)
card.name = "The Fool"
card.image_path = "fool.jpg"
cards = [card]
display.show_cards(cards, title="Test Spread")
# Verify SpreadDisplay was instantiated
assert MockSpreadDisplay.call_count == 1
# Verify run was called
MockSpreadDisplay.return_value.run.assert_called_once()
# Verify arguments passed to SpreadDisplay
args, _ = MockSpreadDisplay.call_args
reading = args[0]
deck_name = args[1]
assert deck_name == "default"
assert reading.spread.name == "Card List"
assert reading.spread.description == "Test Spread"
assert len(reading.drawn_cards) == 1
assert reading.drawn_cards[0].card == card
assert reading.drawn_cards[0].position.number == 1

47
tests/test_cube_ui.py Normal file
View File

@@ -0,0 +1,47 @@
import pytest
from tarot.ui import CubeDisplay
from tarot.tarot_api import Tarot
def test_cube_display_init():
cube = Tarot.cube
display = CubeDisplay(cube, "default")
assert display.current_wall_name == "North"
assert display.deck_name == "default"
def test_cube_navigation():
cube = Tarot.cube
display = CubeDisplay(cube)
# North -> Right -> East
display._navigate("Right")
assert display.current_wall_name == "East"
# East -> Up -> Above
display._navigate("Up")
assert display.current_wall_name == "Above"
# Above -> Down -> North
display._navigate("Down")
assert display.current_wall_name == "North"
# North -> Left -> West
display._navigate("Left")
assert display.current_wall_name == "West"
def test_find_card_for_direction():
cube = Tarot.cube
display = CubeDisplay(cube)
# North Wall, Center Direction -> Aleph -> The Fool
wall = cube.wall("North")
direction = wall.direction("Center") # Should be Aleph?
# Wait, let's check what Center of North is.
# Actually, let's just mock a direction
from kaballah.cube.attributes import WallDirection
# Aleph -> The Fool
d = WallDirection("Center", "Aleph")
card = display._find_card_for_direction(d)
assert card is not None
assert "Fool" in card.name

28
tests/test_cube_zoom.py Normal file
View File

@@ -0,0 +1,28 @@
import pytest
from tarot.ui import CubeDisplay
from tarot.tarot_api import Tarot
def test_cube_zoom():
cube = Tarot.cube
display = CubeDisplay(cube)
assert display.zoom_level == 1.0
display._zoom(1.1)
assert display.zoom_level > 1.0
display._zoom(0.5)
assert display.zoom_level < 1.0
def test_cube_zoom_limits():
cube = Tarot.cube
display = CubeDisplay(cube)
# Test upper limit
for _ in range(20):
display._zoom(1.5)
assert display.zoom_level <= 3.0
# Test lower limit
for _ in range(20):
display._zoom(0.5)
assert display.zoom_level >= 0.5

124
tests/test_cube_zoom_limits.py Normal file
View File

@@ -0,0 +1,124 @@
import pytest
from tarot.ui import CubeDisplay
from tarot.tarot_api import Tarot
import tkinter as tk
from unittest.mock import MagicMock, patch
def test_zoom_limits():
# Mock Tk root
class MockRoot:
def __init__(self):
self.bindings = {}
self.images = []
def bind(self, key, callback): pass
def title(self, _): pass
def update_idletasks(self): pass
def winfo_reqwidth(self): return 800
def winfo_reqheight(self): return 600
def winfo_screenwidth(self): return 1920
def winfo_screenheight(self): return 1080
def geometry(self, _): pass
def mainloop(self): pass
def focus_force(self): pass
# Mock Frame
class MockFrame:
def __init__(self, master=None, **kwargs):
self.children = []
self.master = master
def pack(self, **kwargs): pass
def place(self, **kwargs): pass
def grid(self, **kwargs): pass
def grid_propagate(self, flag): pass
def winfo_children(self): return self.children
def destroy(self): pass
def update_idletasks(self): pass
def winfo_reqwidth(self): return 100
def winfo_reqheight(self): return 100
def bind(self, event, callback): pass
# Mock Canvas
class MockCanvas:
def __init__(self, master=None, **kwargs):
self.master = master
def pack(self, **kwargs): pass
def bind(self, event, callback): pass
def create_window(self, coords, **kwargs): return 1
def config(self, **kwargs): pass
def bbox(self, tag): return (0,0,100,100)
def winfo_width(self): return 800
def winfo_height(self): return 600
def coords(self, item, x, y): pass
def scan_mark(self, x, y): pass
def scan_dragto(self, x, y, gain=1): pass
def canvasx(self, x): return x
def canvasy(self, y): return y
def xview_moveto(self, fraction): pass
def yview_moveto(self, fraction): pass
# Monkey patch tk
original_tk = tk.Tk
original_frame = tk.ttk.Frame
original_canvas = tk.Canvas
original_label = tk.ttk.Label
original_button = tk.ttk.Button
# Mock Label and Button
class MockWidget:
def __init__(self, master=None, **kwargs):
self.master = master
def pack(self, **kwargs): pass
def place(self, **kwargs): pass
def grid(self, **kwargs): pass
def grid_propagate(self, flag): pass
try:
tk.Tk = MockRoot
tk.ttk.Frame = MockFrame
tk.Canvas = MockCanvas
tk.ttk.Label = MockWidget
tk.ttk.Button = MockWidget
# Mock Image to avoid memory issues
with patch('PIL.Image.open') as mock_open:
mock_img = MagicMock()
mock_img.size = (100, 100)
mock_img.resize.return_value = mock_img
mock_open.return_value = mock_img
with patch('PIL.ImageTk.PhotoImage') as mock_photo:
cube = Tarot.cube
display = CubeDisplay(cube)
display.root = MockRoot()
display.canvas = MockCanvas()
display.content_frame = MockFrame()
display.canvas_window = 1 # Mock window ID
# Test initial zoom
assert display.zoom_level == 1.0
# Test zoom in
display._zoom(1.22)
assert display.zoom_level == 1.22
# Test max limit (should be 50.0)
# Zoom way in
for _ in range(100):
display._zoom(1.22)
assert display.zoom_level == 50.0
# Test min limit (should be 0.1)
# Zoom way out
for _ in range(200):
display._zoom(0.5)
assert display.zoom_level == 0.1
finally:
tk.Tk = original_tk
tk.ttk.Frame = original_frame
tk.Canvas = original_canvas
tk.ttk.Label = original_label
tk.ttk.Button = original_button

18
tests/test_ui.py Normal file
View File

@@ -0,0 +1,18 @@
import pytest
from pathlib import Path
from tarot.ui import CardDisplay
def test_card_display_init():
display = CardDisplay("default")
assert display.deck_name == "default"
# Check if path resolves correctly relative to src/tarot/ui.py
# src/tarot/ui.py -> src/tarot -> src/tarot/deck/default
expected_suffix = os.path.join("src", "tarot", "deck", "default")
assert str(display.deck_path).endswith(expected_suffix) or str(display.deck_path).endswith("default")
def test_card_display_resolve_path():
display = CardDisplay("thoth")
assert display.deck_name == "thoth"
assert str(display.deck_path).endswith("thoth")
import os

60
tests/test_ui_binding_recursive.py Normal file
View File

@@ -0,0 +1,60 @@
import pytest
from tarot.ui import CubeDisplay
from tarot.tarot_api import Tarot
import tkinter as tk
def test_recursive_binding():
# Mock Tk root and widgets
class MockWidget:
def __init__(self):
self.children = []
self.bindings = {}
def bind(self, key, callback):
self.bindings[key] = callback
def winfo_children(self):
return self.children
def add_child(self, child):
self.children.append(child)
# Monkey patch tk
original_tk = tk.Tk
original_frame = tk.ttk.Frame
try:
# We don't need to mock everything, just enough to test _bind_recursive
cube = Tarot.cube
# We can instantiate CubeDisplay without showing it
display = CubeDisplay(cube)
# Create a mock widget tree
parent = MockWidget()
child1 = MockWidget()
child2 = MockWidget()
grandchild = MockWidget()
parent.add_child(child1)
parent.add_child(child2)
child1.add_child(grandchild)
# Run recursive binding
display._bind_recursive(parent)
# Verify bindings
assert "<ButtonPress-1>" in parent.bindings
assert "<B1-Motion>" in parent.bindings
assert "<ButtonPress-1>" in child1.bindings
assert "<B1-Motion>" in child1.bindings
assert "<ButtonPress-1>" in child2.bindings
assert "<B1-Motion>" in child2.bindings
assert "<ButtonPress-1>" in grandchild.bindings
assert "<B1-Motion>" in grandchild.bindings
finally:
pass

72
tests/test_ui_bindings.py Normal file
View File

@@ -0,0 +1,72 @@
import pytest
from tarot.ui import CubeDisplay
from tarot.tarot_api import Tarot
import tkinter as tk
def test_zoom_key_bindings():
# This test verifies that the bindings are set up,
# but cannot easily simulate key presses in headless environment.
# We check if the bind method was called with correct keys.
# Mock Tk root
class MockRoot:
def __init__(self):
self.bindings = {}
def bind(self, key, callback):
self.bindings[key] = callback
def title(self, _): pass
def update_idletasks(self): pass
def winfo_reqwidth(self): return 800
def winfo_reqheight(self): return 600
def winfo_screenwidth(self): return 1920
def winfo_screenheight(self): return 1080
def geometry(self, _): pass
def mainloop(self): pass
def focus_force(self): pass
# Mock Frame
class MockFrame:
def __init__(self, master=None, **kwargs):
self.children = []
def pack(self, **kwargs): pass
def winfo_children(self): return self.children
def destroy(self): pass
# Monkey patch tk
original_tk = tk.Tk
original_frame = tk.ttk.Frame
try:
tk.Tk = MockRoot
tk.ttk.Frame = MockFrame
cube = Tarot.cube
display = CubeDisplay(cube)
# We need to call show() to trigger bindings, but avoid mainloop
# We can't easily mock show() without refactoring,
# so we'll just inspect the code logic or trust the manual test.
# However, we can manually call the binding logic if we extract it.
# Since we can't easily mock the entire UI startup in a unit test without
# a display, we'll rely on the fact that we added the bindings in the code.
pass
finally:
tk.Tk = original_tk
tk.ttk.Frame = original_frame
def test_zoom_logic_direct():
cube = Tarot.cube
display = CubeDisplay(cube)
display.zoom_level = 1.0
# Simulate + key press effect
display._zoom(1.1)
assert display.zoom_level > 1.0
# Simulate - key press effect
display._zoom(0.9)
assert display.zoom_level < 1.1

84
tests/test_ui_panning.py Normal file
View File

@@ -0,0 +1,84 @@
import pytest
from tarot.ui import CubeDisplay
from tarot.tarot_api import Tarot
import tkinter as tk
def test_canvas_structure():
# Mock Tk root
class MockRoot:
def __init__(self):
self.bindings = {}
def bind(self, key, callback): pass
def title(self, _): pass
def update_idletasks(self): pass
def winfo_reqwidth(self): return 800
def winfo_reqheight(self): return 600
def winfo_screenwidth(self): return 1920
def winfo_screenheight(self): return 1080
def geometry(self, _): pass
def mainloop(self): pass
def focus_force(self): pass
# Mock Frame
class MockFrame:
def __init__(self, master=None, **kwargs):
self.children = []
self.master = master
def pack(self, **kwargs): pass
def place(self, **kwargs): pass
def winfo_children(self): return self.children
def destroy(self): pass
def update_idletasks(self): pass
def winfo_reqwidth(self): return 100
def winfo_reqheight(self): return 100
# Mock Canvas
class MockCanvas:
def __init__(self, master=None, **kwargs):
self.master = master
def pack(self, **kwargs): pass
def bind(self, event, callback): pass
def create_window(self, coords, **kwargs): return 1
def config(self, **kwargs): pass
def bbox(self, tag): return (0,0,100,100)
def winfo_width(self): return 800
def winfo_height(self): return 600
def coords(self, item, x, y): pass
def scan_mark(self, x, y): pass
def scan_dragto(self, x, y, gain=1): pass
# Monkey patch tk
original_tk = tk.Tk
original_frame = tk.ttk.Frame
original_canvas = tk.Canvas
try:
tk.Tk = MockRoot
tk.ttk.Frame = MockFrame
tk.Canvas = MockCanvas
cube = Tarot.cube
display = CubeDisplay(cube)
# Trigger show to build UI
# We can't fully run show() because of mainloop, but we can instantiate parts
# Actually, show() creates the root.
# Let's just verify the structure by inspecting the code or trusting the manual test.
# But we can test the pan methods directly.
display.canvas = MockCanvas()
# Test pan methods
class MockEvent:
x = 10
y = 20
x_root = 110
y_root = 120
display._start_pan(MockEvent())
display._pan(MockEvent())
finally:
tk.Tk = original_tk
tk.ttk.Frame = original_frame
tk.Canvas = original_canvas

128
tests/test_ui_wasd_panning.py Normal file
View File

@@ -0,0 +1,128 @@
import pytest
from tarot.ui import CubeDisplay
from tarot.tarot_api import Tarot
import tkinter as tk
from unittest.mock import MagicMock, patch
def test_wasd_panning():
# Mock Tk root
class MockRoot:
def __init__(self):
self.bindings = {}
self.images = []
def bind(self, key, callback):
self.bindings[key] = callback
def title(self, _): pass
def update_idletasks(self): pass
def winfo_reqwidth(self): return 800
def winfo_reqheight(self): return 600
def winfo_screenwidth(self): return 1920
def winfo_screenheight(self): return 1080
def geometry(self, _): pass
def mainloop(self): pass
def focus_force(self): pass
# Mock Frame
class MockFrame:
def __init__(self, master=None, **kwargs):
self.children = []
self.master = master
def pack(self, **kwargs): pass
def place(self, **kwargs): pass
def grid(self, **kwargs): pass
def grid_propagate(self, flag): pass
def winfo_children(self): return self.children
def destroy(self): pass
def update_idletasks(self): pass
def winfo_reqwidth(self): return 100
def winfo_reqheight(self): return 100
def bind(self, event, callback): pass
# Mock Canvas
class MockCanvas:
def __init__(self, master=None, **kwargs):
self.master = master
self.x_scrolls = []
self.y_scrolls = []
def pack(self, **kwargs): pass
def bind(self, event, callback): pass
def create_window(self, coords, **kwargs): return 1
def config(self, **kwargs): pass
def bbox(self, tag): return (0,0,100,100)
def winfo_width(self): return 800
def winfo_height(self): return 600
def coords(self, item, x, y): pass
def scan_mark(self, x, y): pass
def scan_dragto(self, x, y, gain=1): pass
def canvasx(self, x): return x
def canvasy(self, y): return y
def xview_moveto(self, fraction): pass
def yview_moveto(self, fraction): pass
def xview_scroll(self, number, what):
self.x_scrolls.append((number, what))
def yview_scroll(self, number, what):
self.y_scrolls.append((number, what))
# Monkey patch tk
original_tk = tk.Tk
original_frame = tk.ttk.Frame
original_canvas = tk.Canvas
original_label = tk.ttk.Label
original_button = tk.ttk.Button
# Mock Label and Button
class MockWidget:
def __init__(self, master=None, **kwargs):
self.master = master
def pack(self, **kwargs): pass
def place(self, **kwargs): pass
def grid(self, **kwargs): pass
def grid_propagate(self, flag): pass
try:
tk.Tk = MockRoot
tk.ttk.Frame = MockFrame
tk.Canvas = MockCanvas
tk.ttk.Label = MockWidget
tk.ttk.Button = MockWidget
# Mock Image to avoid memory issues
with patch('PIL.Image.open') as mock_open:
mock_img = MagicMock()
mock_img.size = (100, 100)
mock_img.resize.return_value = mock_img
mock_open.return_value = mock_img
with patch('PIL.ImageTk.PhotoImage') as mock_photo:
cube = Tarot.cube
display = CubeDisplay(cube)
display.root = MockRoot()
display.canvas = MockCanvas()
display.content_frame = MockFrame()
display.canvas_window = 1
# Manually trigger bindings (since we can't easily simulate key press in mock root without event loop)
# But we can call _pan_key directly to test logic
display._pan_key("up")
assert display.canvas.y_scrolls[-1] == (-1, "units")
display._pan_key("down")
assert display.canvas.y_scrolls[-1] == (1, "units")
display._pan_key("left")
assert display.canvas.x_scrolls[-1] == (-1, "units")
display._pan_key("right")
assert display.canvas.x_scrolls[-1] == (1, "units")
finally:
tk.Tk = original_tk
tk.ttk.Frame = original_frame
tk.Canvas = original_canvas
tk.ttk.Label = original_label
tk.ttk.Button = original_button

908
typer-test.py Normal file
View File

@@ -0,0 +1,908 @@
"""Typer-based CLI for quick Tarot exploration with completions.
Run `python typer-test.py --help` for commands. Install shell completions with
`python typer-test.py --install-completion`.
"""
from __future__ import annotations
import ast
import inspect
import shlex
import sys
from pathlib import Path
from typing import Any, Dict, List, Optional, Set
import typer
from rich.console import Console
from rich.table import Table
from letter import letter as letter_ns
try:
from prompt_toolkit import PromptSession
from prompt_toolkit.completion import Completer, Completion
except ImportError: # pragma: no cover - optional at runtime
PromptSession = None # type: ignore
Completer = object # type: ignore
Completion = object # type: ignore
WordCompleter = None # type: ignore
# Ensure the src directory is on sys.path when running from repo root
ROOT = Path(__file__).resolve().parent
SRC_DIR = ROOT / "src"
if str(SRC_DIR) not in sys.path:
sys.path.insert(0, str(SRC_DIR))
from cli_renderers import Renderer # noqa: E402
from tarot import Card, Tarot, Tree, Cube # noqa: E402
app = typer.Typer(add_completion=True, help="CLI playground for the Tarot API.")
tree_app = typer.Typer(help="Tree of Life commands. Examples: tree sephera 1; tree path 11.")
cube_app = typer.Typer(help="Cube of Space commands. Examples: cube wall North; cube direction North East.")
letter_app = typer.Typer(help="Letter/I Ching/Periodic commands. Examples: letter alphabet; letter cipher; letter char Aleph.")
console = Console()
renderer = Renderer(console)
_render_value = renderer.render_value
_print_kv_table = renderer.print_kv_table
_print_rows_table = renderer.print_rows_table
_print_cards_table = renderer.print_cards_table
EXPR_NO_MATCH = object()
SAFE_ROOTS: Dict[str, Any] = {
"tarot": Tarot,
"tree": Tree,
"cube": Cube,
"letter": letter_ns,
}
_MISSING_DOCS: Set[str] = set()
ROOT_COMMANDS = [
"tarot",
"search",
"planet",
"hexagram",
"tree",
"cube",
"letter",
"help",
"quit",
"exit",
]
def _base_keywords() -> List[str]:
return list(ROOT_COMMANDS)
SUITS = ("Cups", "Pentacles", "Swords", "Wands")
ARCANA = ("Major", "Minor")
def _ensure_deck() -> None:
"""Make sure the shared deck is initialized before use."""
Tarot.deck.card._ensure_initialized() # type: ignore[attr-defined]
def _complete_suit(ctx: typer.Context, incomplete: str) -> List[str]:
return [s for s in SUITS if s.lower().startswith(incomplete.lower())]
def _complete_arcana(ctx: typer.Context, incomplete: str) -> List[str]:
return [a for a in ARCANA if a.lower().startswith(incomplete.lower())]
def _complete_planet_name(ctx: typer.Context, incomplete: str) -> List[str]:
try:
planets = Tarot.planet() # type: ignore[assignment]
except Exception:
return []
names = list(planets.keys()) if isinstance(planets, dict) else []
return [n for n in names if n.lower().startswith(incomplete.lower())]
def _complete_hexagram(ctx: typer.Context, incomplete: str) -> List[str]:
try:
hexagrams = Tarot.hexagram() # type: ignore[assignment]
except Exception:
return []
nums = [str(k) for k in hexagrams.keys()] if isinstance(hexagrams, dict) else []
return [n for n in nums if n.startswith(incomplete)]
def _planet_names() -> List[str]:
try:
planets = Tarot.planet() # type: ignore[assignment]
except Exception:
return []
return list(planets.keys()) if isinstance(planets, dict) else []
def _hexagram_numbers() -> List[str]:
try:
hexagrams = Tarot.hexagram() # type: ignore[assignment]
except Exception:
return []
return [str(k) for k in hexagrams.keys()] if isinstance(hexagrams, dict) else []
def _sephera_numbers() -> List[str]:
try:
from tarot import Tree
seph = Tree.sephera() # type: ignore[assignment]
except Exception:
return []
return [str(k) for k in seph.keys()] if isinstance(seph, dict) else []
def _path_numbers() -> List[str]:
try:
from tarot import Tree
paths = Tree.path() # type: ignore[assignment]
except Exception:
return []
return [str(k) for k in paths.keys()] if isinstance(paths, dict) else []
def _wall_names() -> List[str]:
return ["North", "South", "East", "West", "Above", "Below"]
def _alphabet_names() -> List[str]:
try:
alph = letter_ns.alphabet.all()
except Exception:
return []
return list(alph.keys()) if isinstance(alph, dict) else []
def _cipher_names() -> List[str]:
try:
ciphers = letter_ns.cipher.all()
except Exception:
return []
return list(ciphers.keys()) if isinstance(ciphers, dict) else []
def _letter_names() -> List[str]:
try:
letters = letter_ns.letter.all()
except Exception:
return []
return list(letters.keys()) if isinstance(letters, dict) else []
def _periodic_symbols() -> List[str]:
try:
periodic = letter_ns.periodic.all()
except Exception:
return []
return list(periodic.keys()) if isinstance(periodic, dict) else []
def _current_fragment(text: str) -> str:
stripped = text.rstrip()
if not stripped:
return ""
last_token = stripped.split()[-1]
if "." in last_token:
return last_token.rsplit(".", 1)[-1]
return last_token
def _completion_candidates(text: str) -> List[str]:
stripped = text.rstrip()
if not stripped:
return _base_keywords()
try:
tokens = shlex.split(stripped)
except ValueError:
tokens = stripped.split()
last_token = tokens[-1] if tokens else ""
# Dotted path completion
if "." in last_token:
head, partial = last_token.rsplit(".", 1)
target = _safe_eval_expr(head)
if target is EXPR_NO_MATCH:
return []
partial_lower = partial.lower()
if isinstance(target, dict):
return [str(k) for k in target.keys() if str(k).lower().startswith(partial_lower)]
return [name for name in dir(target) if not name.startswith("_") and name.lower().startswith(partial_lower)]
fragment = last_token.lower() if last_token else ""
# No tokens yet: suggest root commands
if len(tokens) == 0:
return [kw for kw in _base_keywords() if kw.lower().startswith(fragment)]
cmd = tokens[0].lower()
# First token: suggest matching commands
if len(tokens) == 1:
return [kw for kw in _base_keywords() if kw.lower().startswith(fragment)]
# Contextual suggestions per command
if cmd == "planet":
return [p for p in _planet_names() if p.lower().startswith(fragment)]
if cmd == "hexagram":
return [n for n in _hexagram_numbers() if n.startswith(fragment)]
if cmd == "tree":
if len(tokens) == 2:
return [sub for sub in ["sephera", "path"] if sub.startswith(fragment)]
if len(tokens) == 3 and tokens[1].lower() == "sephera":
return [n for n in _sephera_numbers() if n.startswith(fragment)]
if len(tokens) == 3 and tokens[1].lower() == "path":
return [n for n in _path_numbers() if n.startswith(fragment)]
if cmd == "cube":
if len(tokens) == 2:
return [sub for sub in ["wall", "direction"] if sub.startswith(fragment)]
if len(tokens) == 3 and tokens[1].lower() == "wall":
return [w for w in _wall_names() if w.lower().startswith(fragment)]
if len(tokens) >= 3 and tokens[1].lower() == "direction":
# suggest wall name at position 3
if len(tokens) == 3:
return [w for w in _wall_names() if w.lower().startswith(fragment)]
# suggest direction names after wall
return [d for d in _direction_names_for_wall(tokens[2]) if d.lower().startswith(fragment)]
if cmd == "letter":
if len(tokens) == 2:
return [sub for sub in ["alphabet", "cipher", "char", "periodic"] if sub.startswith(fragment)]
if len(tokens) == 3 and tokens[1].lower() == "alphabet":
return [a for a in _alphabet_names() if a.lower().startswith(fragment)]
if len(tokens) == 3 and tokens[1].lower() == "cipher":
return [c for c in _cipher_names() if c.lower().startswith(fragment)]
if len(tokens) == 3 and tokens[1].lower() in {"char", "letter"}:
return [l for l in _letter_names() if l.lower().startswith(fragment)]
if len(tokens) == 3 and tokens[1].lower() == "periodic":
return [s for s in _periodic_symbols() if s.lower().startswith(fragment)]
if cmd == "search":
# Simple heuristics: suggest option flags or option values based on prior flag
if last_token.startswith("-"):
return [opt for opt in ["--suit", "--arcana", "--pip", "-s", "-a", "-p"] if opt.startswith(last_token)]
if any(tok in {"--suit", "-s"} for tok in tokens[:-1]):
return [s for s in SUITS if s.lower().startswith(fragment)]
if any(tok in {"--arcana", "-a"} for tok in tokens[:-1]):
return [a for a in ARCANA if a.lower().startswith(fragment)]
return []
# Default: no suggestions
return []
class DotPathCompleter(Completer):
def get_completions(self, document, complete_event): # type: ignore[override]
text = document.text_before_cursor
fragment = _current_fragment(text)
for cand in _completion_candidates(text):
yield Completion(cand, start_position=-len(fragment))
def _safe_eval_expr(expr: str) -> Any:
expr = expr.strip()
if not expr:
return EXPR_NO_MATCH
try:
parsed = ast.parse(expr, mode="eval")
except SyntaxError:
return EXPR_NO_MATCH
def _eval_node(node: ast.AST) -> Any:
if isinstance(node, ast.Expression):
return _eval_node(node.body)
if isinstance(node, ast.Name):
if node.id in SAFE_ROOTS:
return SAFE_ROOTS[node.id]
raise ValueError("Name not allowed")
if isinstance(node, ast.Attribute):
value = _eval_node(node.value)
return getattr(value, node.attr)
if isinstance(node, ast.Call):
func = _eval_node(node.func)
args = [_eval_node(arg) for arg in node.args]
kwargs = {kw.arg: _eval_node(kw.value) for kw in node.keywords if kw.arg is not None}
return func(*args, **kwargs)
if isinstance(node, ast.Constant):
return node.value
raise ValueError("Expression not allowed")
try:
return _eval_node(parsed)
except Exception:
return EXPR_NO_MATCH
def _search_cards(suit: Optional[str], arcana: Optional[str], pip: Optional[int]) -> List[Card]:
_ensure_deck()
deck = Tarot.deck.card._deck # type: ignore[attr-defined]
if deck is None:
return []
cards: List[Card] = deck.cards
if suit is not None:
cards = [
card
for card in cards
if getattr(getattr(card, "suit", None), "name", "").lower() == suit.lower()
]
if arcana is not None:
cards = [card for card in cards if getattr(card, "arcana", "").lower() == arcana.lower()]
if pip is not None:
cards = [card for card in cards if getattr(card, "pip", None) == pip]
return cards
@app.command()
def search(
suit: Optional[str] = typer.Option(
None, "--suit", "-s", help="Filter by suit", autocompletion=_complete_suit
),
arcana: Optional[str] = typer.Option(
None, "--arcana", "-a", help="Filter by arcana", autocompletion=_complete_arcana
),
pip: Optional[int] = typer.Option(
None, "--pip", "-p", help="Filter by pip (1 for Ace, 2-10 for pips)"
),
) -> None:
"""Filter cards with autocompleting suit/arcana options."""
cards = _search_cards(suit, arcana, pip)
if not cards:
typer.echo("No cards matched that filter.")
raise typer.Exit(code=0)
def _doc(obj: Any, fallback: str) -> str:
return inspect.getdoc(obj) or fallback
def _sync_doc(cmd_fn: Any, source_obj: Any) -> None:
if cmd_fn is None or source_obj is None:
return
doc = _doc(source_obj, cmd_fn.__doc__ or "")
if doc:
cmd_fn.__doc__ = doc
else:
_MISSING_DOCS.add(cmd_fn.__name__)
def _report_missing_docs() -> None:
if not _MISSING_DOCS:
return
console.print(
f"[yellow]Docstring missing for: {', '.join(sorted(_MISSING_DOCS))}."
" Update source API docstrings to sync help.[/yellow]"
)
def _print_structure_table() -> None:
rows = [
("tarot.deck.card(n)", "Access cards by deck position", "tarot.deck.card(1)"),
(
"tarot.deck.card.filter(...)",
"Filter cards using attributes",
"tarot.deck.card.filter(arcana='Major')",
),
(
"tarot.deck.card.spread(name)",
"Draw a spread with random cards",
"tarot.deck.card.spread('Celtic Cross')",
),
("tarot.planet()", "Planet correspondences as dict", "tarot.planet()['Venus']"),
("tarot.hexagram()", "I Ching hexagrams as dict", "tarot.hexagram()[1]"),
("tree.sephera(n)", "Kabbalistic sephiroth", "tree.sephera(1)"),
("tree.path(n)", "Paths on the Tree of Life", "tree.path(11)"),
("cube.wall(name)", "Cube of Space walls", "cube.wall('North')"),
("cube.direction(wall, dir)", "Directions on a wall", "cube.direction('North', 'East')"),
("letter.alphabet.all()", "Alphabet metadata", "letter.alphabet.all()['english']"),
("letter.cipher.all()", "Cipher definitions", "letter.cipher.all()['english_simple']"),
("letter.letter.all()", "Letters and properties", "letter.letter.all()['Aleph']"),
("letter.periodic.all()", "Periodic correspondences", "letter.periodic.all()['H']"),
("letter.iching.all()", "I Ching via letter namespace", "letter.iching.all()[1]"),
]
table = Table(title="Tarot API Map", show_lines=True)
table.add_column("Expression", style="cyan")
table.add_column("Description")
table.add_column("Example")
for expr, desc, example in rows:
table.add_row(expr, desc, example)
console.print(table)
console.print(
"REPL: type expressions exactly as above; tab completion works per segment. "
"CLI shortcuts that remain: search, planet, hexagram, tree, cube, letter."
)
def _show_sephera(number: Optional[int]) -> None:
getattr(Tree, "_ensure_initialized", lambda: None)()
data = Tree.sephera(number)
if data is None:
typer.echo("Sephera not found.")
return
if isinstance(data, dict):
rows: List[List[Any]] = []
for num, obj in sorted(data.items()):
rows.append([
num,
getattr(obj, "name", ""),
getattr(obj, "hebrew_name", ""),
getattr(obj, "planet", ""),
getattr(obj, "element", ""),
])
_print_rows_table("Sephiroth", ["#", "Name", "Hebrew", "Planet", "Element"], rows)
else:
attrs = data.__dict__ if hasattr(data, "__dict__") else {"value": data}
_print_kv_table(f"Sephera: {getattr(data, 'name', number)}", attrs)
def _show_path(number: Optional[int]) -> None:
getattr(Tree, "_ensure_initialized", lambda: None)()
data = Tree.path(number)
if data is None:
typer.echo("Path not found.")
return
if isinstance(data, dict):
rows: List[List[Any]] = []
for num, obj in sorted(data.items()):
rows.append([
num,
getattr(obj, "name", ""),
getattr(obj, "hebrew_letter", getattr(obj, "hebrew", "")),
getattr(obj, "planet", getattr(obj, "element", "")),
])
_print_rows_table("Paths", ["#", "Name", "Hebrew", "Assoc"], rows)
else:
attrs = data.__dict__ if hasattr(data, "__dict__") else {"value": data}
_print_kv_table(f"Path: {number}", attrs)
def _show_walls(name: Optional[str]) -> None:
cube_walls = Cube.wall.all() if Cube.wall else [] # type: ignore[attr-defined]
if name is None:
rows = []
for wall in cube_walls:
rows.append([
getattr(wall, "name", ""),
getattr(wall, "element", ""),
getattr(wall, "planet", ""),
getattr(wall, "opposite", ""),
])
_print_rows_table("Cube Walls", ["Wall", "Element", "Planet", "Opposite"], rows)
return
wall_obj = None
for wall in cube_walls:
if getattr(wall, "name", "").lower() == name.lower():
wall_obj = wall
break
if wall_obj is None:
typer.echo(f"Wall '{name}' not found.")
return
attrs = wall_obj.__dict__ if hasattr(wall_obj, "__dict__") else {"value": wall_obj}
_print_kv_table(f"Wall: {getattr(wall_obj, 'name', name)}", attrs)
def _direction_names_for_wall(wall_name: str) -> List[str]:
cube_walls = Cube.wall.all() if Cube.wall else [] # type: ignore[attr-defined]
for wall in cube_walls:
if getattr(wall, "name", "").lower() == wall_name.lower():
return list(getattr(wall, "directions", {}).keys()) if hasattr(wall, "directions") else []
return []
def _show_direction(wall_name: str, direction: Optional[str]) -> None:
cube_walls = Cube.wall.all() if Cube.wall else [] # type: ignore[attr-defined]
wall_obj = None
for wall in cube_walls:
if getattr(wall, "name", "").lower() == wall_name.lower():
wall_obj = wall
break
if wall_obj is None:
typer.echo(f"Wall '{wall_name}' not found.")
return
if direction is None:
dirs = getattr(wall_obj, "directions", {}) if hasattr(wall_obj, "directions") else {}
rows = []
for name, dir_obj in dirs.items():
rows.append([
name,
getattr(dir_obj, "element", ""),
getattr(dir_obj, "planet", ""),
])
_print_rows_table(
f"Directions for {getattr(wall_obj, 'name', wall_name)}",
["Direction", "Element", "Planet"],
rows,
)
return
dirs = getattr(wall_obj, "directions", {}) if hasattr(wall_obj, "directions") else {}
dir_obj = dirs.get(direction.capitalize()) if isinstance(dirs, dict) else None
if dir_obj is None:
typer.echo(f"Direction '{direction}' not found in wall '{wall_name}'.")
return
attrs = dir_obj.__dict__ if hasattr(dir_obj, "__dict__") else {"value": dir_obj}
_print_kv_table(f"Direction: {direction} ({wall_name})", attrs)
def _show_alphabets(name: Optional[str]) -> None:
alph = letter_ns.alphabet.all()
if not isinstance(alph, dict):
typer.echo("Alphabet data unavailable.")
return
if name is None:
rows = [[k, v.get("name", "") if isinstance(v, dict) else ""] for k, v in alph.items()]
_print_rows_table("Alphabets", ["Key", "Name"], rows)
return
obj = alph.get(name)
if obj is None:
typer.echo(f"Alphabet '{name}' not found.")
return
attrs = obj if isinstance(obj, dict) else {"value": obj}
_print_kv_table(f"Alphabet: {name}", attrs)
def _show_ciphers(name: Optional[str]) -> None:
ciphers = letter_ns.cipher.all()
if not isinstance(ciphers, dict):
typer.echo("Cipher data unavailable.")
return
if name is None:
rows = [[k, ""] for k in ciphers.keys()]
_print_rows_table("Ciphers", ["Key", ""], rows)
return
obj = ciphers.get(name)
if obj is None:
typer.echo(f"Cipher '{name}' not found.")
return
attrs = obj if isinstance(obj, dict) else {"value": obj}
_print_kv_table(f"Cipher: {name}", attrs)
def _show_letter_char(name: Optional[str]) -> None:
letters = letter_ns.letter.all()
if not isinstance(letters, dict):
typer.echo("Letter data unavailable.")
return
if name is None:
rows = [[k, getattr(v, "hebrew_name", getattr(v, "name", ""))] for k, v in letters.items()]
_print_rows_table("Letters", ["Key", "Name"], rows)
return
obj = letters.get(name)
if obj is None:
typer.echo(f"Letter '{name}' not found.")
return
attrs = obj.__dict__ if hasattr(obj, "__dict__") else {"value": obj}
_print_kv_table(f"Letter: {name}", attrs)
def _show_periodic(symbol: Optional[str]) -> None:
periodic = letter_ns.periodic.all()
if not isinstance(periodic, dict):
typer.echo("Periodic table data unavailable.")
return
if symbol is None:
rows = [[k, getattr(v, "name", getattr(v, "element", ""))] for k, v in periodic.items()]
_print_rows_table("Periodic Table", ["Symbol", "Name"], rows)
return
obj = periodic.get(symbol)
if obj is None:
typer.echo(f"Symbol '{symbol}' not found.")
return
attrs = obj.__dict__ if hasattr(obj, "__dict__") else {"value": obj}
_print_kv_table(f"Element: {symbol}", attrs)
@app.command()
def planet(
name: Optional[str] = typer.Argument(
None, help="Planet name (omit to list all)", autocompletion=_complete_planet_name
)
) -> None:
"""Show a planet or list all planet names."""
Tarot._ensure_initialized() # type: ignore[attr-defined]
planets = Tarot.planet() # type: ignore[assignment]
if not isinstance(planets, dict):
typer.echo("Planet data unavailable.")
raise typer.Exit(code=1)
if name is None:
table = Table(title="Planets", show_header=True)
table.add_column("Name")
for planet_name in sorted(planets.keys()):
table.add_row(planet_name)
console.print(table)
return
planet_obj = planets.get(name)
if planet_obj is None:
typer.echo(f"Planet '{name}' not found.")
raise typer.Exit(code=1)
_render_value(planet_obj)
@app.command()
def hexagram(
number: Optional[int] = typer.Argument(
None, help="Hexagram number (1-64). Omit to list all.", autocompletion=_complete_hexagram
)
) -> None:
"""Show an I Ching hexagram or list all numbers."""
Tarot._ensure_initialized() # type: ignore[attr-defined]
hexagrams = Tarot.hexagram() # type: ignore[assignment]
if not isinstance(hexagrams, dict):
typer.echo("Hexagram data unavailable.")
raise typer.Exit(code=1)
if number is None:
table = Table(title="Hexagrams", show_header=True)
table.add_column("Number")
for num in sorted(hexagrams.keys()):
table.add_row(str(num))
console.print(table)
return
hex_obj = hexagrams.get(number)
if hex_obj is None:
typer.echo(f"Hexagram '{number}' not found.")
raise typer.Exit(code=1)
attrs = hex_obj.__dict__ if hasattr(hex_obj, "__dict__") else {"value": hex_obj}
_print_kv_table(f"Hexagram: {number}", attrs)
# Keep CLI command docs in sync with API docstrings
_sync_doc(planet, getattr(Tarot, "planet", None))
_sync_doc(hexagram, getattr(Tarot, "hexagram", None))
app.add_typer(tree_app, name="tree")
app.add_typer(cube_app, name="cube")
app.add_typer(letter_app, name="letter")
@tree_app.command("sephera")
def tree_sephera(number: Optional[int] = typer.Argument(None, autocompletion=_sephera_numbers)) -> None:
"""List all sephiroth or show a specific one."""
_show_sephera(number)
@tree_app.command("path")
def tree_path(number: Optional[int] = typer.Argument(None, autocompletion=_path_numbers)) -> None:
"""List all paths or show a specific one."""
_show_path(number)
@cube_app.command("wall")
def cube_wall(name: Optional[str] = typer.Argument(None, autocompletion=_wall_names)) -> None:
"""List walls or show details for a wall."""
_show_walls(name)
@cube_app.command("direction")
def cube_direction(
wall_name: str = typer.Argument(..., autocompletion=_wall_names),
direction: Optional[str] = typer.Argument(None),
) -> None:
"""List directions for a wall or show one."""
_show_direction(wall_name, direction)
@letter_app.command("alphabet")
def letter_alphabet(name: Optional[str] = typer.Argument(None, autocompletion=_alphabet_names)) -> None:
"""List alphabets or show one."""
_show_alphabets(name)
@letter_app.command("cipher")
def letter_cipher(name: Optional[str] = typer.Argument(None, autocompletion=_cipher_names)) -> None:
"""List ciphers or show one."""
_show_ciphers(name)
@letter_app.command("char")
def letter_char(name: Optional[str] = typer.Argument(None, autocompletion=_letter_names)) -> None:
"""List letters or show one."""
_show_letter_char(name)
@letter_app.command("periodic")
def letter_periodic(symbol: Optional[str] = typer.Argument(None, autocompletion=_periodic_symbols)) -> None:
"""List periodic elements or show one."""
_show_periodic(symbol)
# Sync all command docstrings from source APIs (single source of truth)
_sync_doc(planet, getattr(Tarot, "planet", None))
_sync_doc(hexagram, getattr(Tarot, "hexagram", None))
_sync_doc(tree_sephera, getattr(Tree, "sephera", None))
_sync_doc(tree_path, getattr(Tree, "path", None))
_sync_doc(cube_wall, getattr(Cube, "wall", None))
_sync_doc(cube_direction, getattr(Cube, "direction", None))
_sync_doc(letter_alphabet, getattr(letter_ns, "alphabet", None))
_sync_doc(letter_cipher, getattr(letter_ns, "cipher", None))
_sync_doc(letter_char, getattr(letter_ns, "letter", None))
_sync_doc(letter_periodic, getattr(letter_ns, "periodic", None))
_report_missing_docs()
def _handle_repl_command(parts: List[str], raw_line: str = "") -> bool:
if not parts:
return True
cmd = parts[0].lower()
if cmd in {"quit", "exit"}:
return False
if cmd == "help":
_print_structure_table()
return True
if cmd == "search":
suit = None
arcana = None
pip = None
tokens = parts[1:]
i = 0
while i < len(tokens):
if tokens[i] in {"--suit", "-s"} and i + 1 < len(tokens):
suit = tokens[i + 1]
i += 2
elif tokens[i] in {"--arcana", "-a"} and i + 1 < len(tokens):
arcana = tokens[i + 1]
i += 2
elif tokens[i] in {"--pip", "-p"} and i + 1 < len(tokens):
try:
pip = int(tokens[i + 1])
except ValueError:
console.print("Invalid pip value.")
return True
i += 2
else:
i += 1
cards = _search_cards(suit, arcana, pip)
if not cards:
console.print("No cards matched that filter.")
else:
_print_cards_table(cards)
return True
if cmd == "planet":
planet_name = parts[1] if len(parts) > 1 else None
planets = Tarot.planet() # type: ignore[assignment]
if not isinstance(planets, dict):
console.print("Planet data unavailable.")
return True
if planet_name is None:
console.print(", ".join(sorted(planets.keys())))
return True
planet_obj = planets.get(planet_name)
if planet_obj is None:
console.print(f"Planet '{planet_name}' not found.")
return True
_render_value(planet_obj)
return True
if cmd == "hexagram":
hex_num = None
if len(parts) > 1 and parts[1].isdigit():
hex_num = int(parts[1])
hexagrams = Tarot.hexagram() # type: ignore[assignment]
if not isinstance(hexagrams, dict):
console.print("Hexagram data unavailable.")
return True
if hex_num is None:
console.print(", ".join(str(n) for n in sorted(hexagrams.keys())))
return True
hex_obj = hexagrams.get(hex_num)
if hex_obj is None:
console.print(f"Hexagram '{hex_num}' not found.")
return True
attrs = hex_obj.__dict__ if hasattr(hex_obj, "__dict__") else {"value": hex_obj}
_print_kv_table(f"Hexagram: {hex_num}", attrs)
return True
if cmd == "tree" and len(parts) > 1:
sub = parts[1].lower()
arg = parts[2] if len(parts) > 2 else None
if sub == "sephera":
_show_sephera(int(arg)) if arg and arg.isdigit() else _show_sephera(None)
return True
if sub == "path":
_show_path(int(arg)) if arg and arg.isdigit() else _show_path(None)
return True
if cmd == "cube" and len(parts) > 1:
sub = parts[1].lower()
arg = parts[2] if len(parts) > 2 else None
if sub == "wall":
_show_walls(arg)
return True
if sub == "direction" and len(parts) >= 3:
direction = parts[3] if len(parts) > 3 else None
_show_direction(parts[2], direction)
return True
if cmd == "letter" and len(parts) > 1:
sub = parts[1].lower()
arg = parts[2] if len(parts) > 2 else None
if sub == "alphabet":
_show_alphabets(arg)
return True
if sub == "cipher":
_show_ciphers(arg)
return True
if sub in {"char", "letter"}:
_show_letter_char(arg)
return True
if sub == "periodic":
_show_periodic(arg)
return True
expr_result = _safe_eval_expr(raw_line or " ".join(parts))
if expr_result is not EXPR_NO_MATCH:
_render_value(expr_result)
return True
console.print("Unknown command. Type 'help' for the API map or use Python-style expressions.")
return True
@app.command()
def repl() -> None:
"""Interactive loop for quick Tarot exploration."""
console.print("Type 'help' for the API map, use Python-style expressions, 'quit' to exit.")
# Build prompt-toolkit completer if available (supports dotted paths)
session = None
completer = None
if PromptSession:
completer = DotPathCompleter()
session = PromptSession(completer=completer)
while True:
try:
if session:
line = session.prompt("tarot> ")
else:
line = input("tarot> ")
line = line.strip()
except (EOFError, KeyboardInterrupt):
console.print("Bye.")
break
if not line:
continue
try:
parts = shlex.split(line)
except ValueError as exc:
console.print(f"Parse error: {exc}")
continue
if not _handle_repl_command(parts, raw_line=line):
break
if __name__ == "__main__":
if len(sys.argv) == 2 and sys.argv[1] in {"-h", "--help"}:
_print_structure_table()
sys.exit(0)
# If invoked without a subcommand, drop into the REPL for convenience.
if len(sys.argv) == 1:
repl()
else:
app()