# tarot-reader
A lightweight, text-based tarot reading package for Python with beautiful terminal display.
## Overview
A pure tarot reading package with randomized results and optional personal seeding for consistent readings.
**For entertainment purposes only.** This package provides a fun, text-only tarot reading experience that can be integrated into apps, chatbots, or used in the terminal.
## Features
### 🔮 Tarot Reading Features
- Complete tarot deck (78 cards) with upright and reversed meanings
- Multiple spreads: Single card, 3-Card (Past/Present/Future), Celtic Cross (10-card)
- Personal seed system with time component for truly random readings
- Beautiful terminal display with emojis and formatting
### 🎲 Randomness Features
- **156 unique outcomes** (78 cards × 2 orientations) with meaningful content
- **Time-influenced randomness** - different results each reading, even with same personal info
- **Personal context** - incorporate personal information while maintaining randomness
- **Scalable output** - generate 1 to 78 random cards in single call
- **Rich content** - each result includes names, orientations, and detailed meanings
## Installation
```bash
pip install tarot-reader
```
## Quick Start
### 🔮 Tarot Reading Usage
#### Basic Tarot Readings
```python
from src import draw_single, draw_three, celtic_cross
# Single card draw
card = draw_single()
print(f"{card['name']} - {card['meaning']}")
# 3-Card spread (Past/Present/Future)
reading = draw_three()
for position, card in reading.items():
print(f"{position}: {card['name']} - {card['meaning']}")
# Celtic Cross (10-card spread)
reading = celtic_cross()
for position, card in reading.items():
print(f"{position}: {card['name']} - {card['meaning']}")
```
#### Personal Context (Time-Influenced Randomness)
```python
# Personal info influences but doesn't determine results
personal_info = "INFP seeking career guidance"
card1 = draw_single(personal_info)
card2 = draw_single(personal_info) # Different from card1 due to time component
# Different personal info = different results
reading_a = draw_three("ENFJ + A+ blood type")
reading_b = draw_three("ISTJ + relationship questions")
```
#### Terminal Display
```python
from src import get_single_card_text, get_random_cards_text
# Beautiful terminal display
card_display = get_single_card_text()
# Returns: "🎴 Strength\n ↳ Courage, persuasion, influence, compassion"
# Multiple cards with formatting
cards_display = get_random_cards_text(3)
# Returns formatted multi-card display with headers and numbering
# Extract just the meanings for simple use
card = draw_single()
meaning = card['meaning']
# Returns: "New beginnings, innocence, spontaneity, free spirit"
```
#### Reading Applications
```python
# Daily guidance with personal context
def daily_guidance(user_info):
return get_single_card_text(user_info)
# Themed readings
def themed_reading(theme, num_cards=3):
return get_random_cards_text(num_cards, theme)
# Simple decision helper
def get_guidance(question):
card = draw_single(question)
return {
'card': card['name'],
'orientation': card['orientation'],
'guidance': card['meaning']
}
```
## Advanced Features
### Complete Reading Summaries
Get full reading experiences with context and beautiful formatting:
```python
from src import get_reading_summary
# Single card with decorative header
daily_reading = get_reading_summary("single", "INFP career guidance")
# Returns: Full formatted reading with header, card, and interpretation
# Three-card spread with guidance
three_card = get_reading_summary("three", "seeking relationship advice")
# Returns: Past/Present/Future spread with context
# Celtic Cross for deep insight
celtic = get_reading_summary("celtic", "major life decision")
# Returns: Full 10-card spread with position explanations
```
### Personal Context Examples
```python
# MBTI Personality Types
reading = get_reading_summary("three", "ENFJ")
# Personal Questions/Reasons
guidance = get_reading_summary("single", "seeking love guidance")
# Combined Personal Information
complex_reading = get_reading_summary("celtic", "INFP + career change 2025")
# Themed readings
themed = get_reading_summary("single", "morning meditation")
```
## Use Cases
### 🔮 Tarot Applications
- Personal tarot reading apps
- Daily card/guidance features
- Terminal-based tarot readers
- Meditation and mindfulness apps
- Fortune telling websites
- Personal guidance tools
### 🎲 Content Generation
- **Story/Game Development**: Generate character traits, plot elements, themes
- **Daily Content Apps**: Time-influenced daily quotes, moods, themes
- **Decision Making Tools**: Random guidance with meaningful context
- **Creative Writing**: Inspiration prompts and story seeds
- **Educational Tools**: Random discussion topics, icebreakers
- **Personal Tools**: Themed guidance and reflection prompts
## API Reference
### Core Functions
```python
# Basic tarot functions
draw_single(personal_seed=None) -> Dict
draw_three(personal_seed=None) -> Dict
celtic_cross(personal_seed=None) -> Dict
# Text formatter functions
get_single_card_text(personal_seed=None) -> str
get_three_card_text(personal_seed=None) -> str
get_celtic_cross_text(personal_seed=None) -> str
get_random_cards_text(num_cards, personal_seed=None) -> str
get_reading_summary(reading_type="single", personal_seed=None) -> str
```
**Parameters:**
- `personal_seed`: Any string for personal context (MBTI, questions, themes, etc.)
- `reading_type`: "single", "three", "celtic", or number as string
- `num_cards`: Integer 1-78 for random card draws
**Note:** All functions now include time-based randomness, so identical inputs will produce different results each time.
## Requirements
- Python 3.8+
- No external dependencies
## Development
```bash
# Clone the repository
git clone https://github.com/yourusername/tarot-reader.git
cd tarot-reader
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e .
# Run tests
python -m unittest discover tests
```
## License
MIT License - see LICENSE file for details.
## Disclaimer
This package is for entertainment purposes only. It is not intended for professional fortune-telling or making important life decisions.
Raw data
{
"_id": null,
"home_page": null,
"name": "tarot-reader",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "tarot, cards, random, generator, llm, content, seed, entertainment",
"author": null,
"author_email": "zafrem <zafrem@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d1/0a/7724e533131be918fd3c4e512711e491a72882172ca3e144c7e05cd2ca0e/tarot_reader-0.0.2.tar.gz",
"platform": null,
"description": "# tarot-reader\n\nA lightweight, text-based tarot reading package for Python with beautiful terminal display.\n\n## Overview\n\nA pure tarot reading package with randomized results and optional personal seeding for consistent readings.\n\n**For entertainment purposes only.** This package provides a fun, text-only tarot reading experience that can be integrated into apps, chatbots, or used in the terminal.\n\n## Features\n\n### \ud83d\udd2e Tarot Reading Features\n- Complete tarot deck (78 cards) with upright and reversed meanings\n- Multiple spreads: Single card, 3-Card (Past/Present/Future), Celtic Cross (10-card)\n- Personal seed system with time component for truly random readings\n- Beautiful terminal display with emojis and formatting\n\n### \ud83c\udfb2 Randomness Features\n- **156 unique outcomes** (78 cards \u00d7 2 orientations) with meaningful content\n- **Time-influenced randomness** - different results each reading, even with same personal info\n- **Personal context** - incorporate personal information while maintaining randomness\n- **Scalable output** - generate 1 to 78 random cards in single call\n- **Rich content** - each result includes names, orientations, and detailed meanings\n\n## Installation\n\n```bash\npip install tarot-reader\n```\n\n## Quick Start\n\n### \ud83d\udd2e Tarot Reading Usage\n\n#### Basic Tarot Readings\n```python\nfrom src import draw_single, draw_three, celtic_cross\n\n# Single card draw\ncard = draw_single()\nprint(f\"{card['name']} - {card['meaning']}\")\n\n# 3-Card spread (Past/Present/Future)\nreading = draw_three()\nfor position, card in reading.items():\n print(f\"{position}: {card['name']} - {card['meaning']}\")\n\n# Celtic Cross (10-card spread)\nreading = celtic_cross()\nfor position, card in reading.items():\n print(f\"{position}: {card['name']} - {card['meaning']}\")\n```\n\n#### Personal Context (Time-Influenced Randomness)\n```python\n# Personal info influences but doesn't determine results\npersonal_info = \"INFP seeking career guidance\"\n\ncard1 = draw_single(personal_info)\ncard2 = draw_single(personal_info) # Different from card1 due to time component\n\n# Different personal info = different results\nreading_a = draw_three(\"ENFJ + A+ blood type\")\nreading_b = draw_three(\"ISTJ + relationship questions\")\n```\n\n#### Terminal Display\n```python\nfrom src import get_single_card_text, get_random_cards_text\n\n# Beautiful terminal display\ncard_display = get_single_card_text()\n# Returns: \"\ud83c\udfb4 Strength\\n \u21b3 Courage, persuasion, influence, compassion\"\n\n# Multiple cards with formatting\ncards_display = get_random_cards_text(3)\n# Returns formatted multi-card display with headers and numbering\n\n# Extract just the meanings for simple use\ncard = draw_single()\nmeaning = card['meaning']\n# Returns: \"New beginnings, innocence, spontaneity, free spirit\"\n```\n\n#### Reading Applications\n```python\n# Daily guidance with personal context\ndef daily_guidance(user_info):\n return get_single_card_text(user_info)\n\n# Themed readings\ndef themed_reading(theme, num_cards=3):\n return get_random_cards_text(num_cards, theme)\n\n# Simple decision helper\ndef get_guidance(question):\n card = draw_single(question)\n return {\n 'card': card['name'],\n 'orientation': card['orientation'],\n 'guidance': card['meaning']\n }\n```\n\n## Advanced Features\n\n### Complete Reading Summaries\n\nGet full reading experiences with context and beautiful formatting:\n\n```python\nfrom src import get_reading_summary\n\n# Single card with decorative header\ndaily_reading = get_reading_summary(\"single\", \"INFP career guidance\")\n# Returns: Full formatted reading with header, card, and interpretation\n\n# Three-card spread with guidance\nthree_card = get_reading_summary(\"three\", \"seeking relationship advice\")\n# Returns: Past/Present/Future spread with context\n\n# Celtic Cross for deep insight\nceltic = get_reading_summary(\"celtic\", \"major life decision\")\n# Returns: Full 10-card spread with position explanations\n```\n\n### Personal Context Examples\n\n```python\n# MBTI Personality Types\nreading = get_reading_summary(\"three\", \"ENFJ\")\n\n# Personal Questions/Reasons\nguidance = get_reading_summary(\"single\", \"seeking love guidance\")\n\n# Combined Personal Information\ncomplex_reading = get_reading_summary(\"celtic\", \"INFP + career change 2025\")\n\n# Themed readings\nthemed = get_reading_summary(\"single\", \"morning meditation\")\n```\n\n## Use Cases\n\n### \ud83d\udd2e Tarot Applications\n- Personal tarot reading apps\n- Daily card/guidance features\n- Terminal-based tarot readers\n- Meditation and mindfulness apps\n- Fortune telling websites\n- Personal guidance tools\n\n### \ud83c\udfb2 Content Generation\n- **Story/Game Development**: Generate character traits, plot elements, themes\n- **Daily Content Apps**: Time-influenced daily quotes, moods, themes\n- **Decision Making Tools**: Random guidance with meaningful context\n- **Creative Writing**: Inspiration prompts and story seeds\n- **Educational Tools**: Random discussion topics, icebreakers\n- **Personal Tools**: Themed guidance and reflection prompts\n\n## API Reference\n\n### Core Functions\n```python\n# Basic tarot functions\ndraw_single(personal_seed=None) -> Dict\ndraw_three(personal_seed=None) -> Dict\nceltic_cross(personal_seed=None) -> Dict\n\n# Text formatter functions\nget_single_card_text(personal_seed=None) -> str\nget_three_card_text(personal_seed=None) -> str\nget_celtic_cross_text(personal_seed=None) -> str\nget_random_cards_text(num_cards, personal_seed=None) -> str\nget_reading_summary(reading_type=\"single\", personal_seed=None) -> str\n```\n\n**Parameters:**\n- `personal_seed`: Any string for personal context (MBTI, questions, themes, etc.)\n- `reading_type`: \"single\", \"three\", \"celtic\", or number as string\n- `num_cards`: Integer 1-78 for random card draws\n\n**Note:** All functions now include time-based randomness, so identical inputs will produce different results each time.\n\n## Requirements\n\n- Python 3.8+\n- No external dependencies\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/tarot-reader.git\ncd tarot-reader\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in development mode\npip install -e .\n\n# Run tests\npython -m unittest discover tests\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Disclaimer\n\nThis package is for entertainment purposes only. It is not intended for professional fortune-telling or making important life decisions.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A lightweight tarot reading package that doubles as a powerful random content generator with personal seed support",
"version": "0.0.2",
"project_urls": {
"Bug Reports": "https://github.com/zafrem/tarot-reader/issues",
"Homepage": "https://github.com/zafrem/tarot-reader",
"Source": "https://github.com/zafrem/tarot-reader"
},
"split_keywords": [
"tarot",
" cards",
" random",
" generator",
" llm",
" content",
" seed",
" entertainment"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a617473d680995da4d81589ead1a26da02c690debb252010e3679e656eceabab",
"md5": "189d60753e3a0d1a534bea232d7f7c13",
"sha256": "8a7c31dfce08bf843dee96d7d44393af62f4dd48e1855abdbe34e1bc46cf9eba"
},
"downloads": -1,
"filename": "tarot_reader-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "189d60753e3a0d1a534bea232d7f7c13",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 14285,
"upload_time": "2025-10-09T04:45:12",
"upload_time_iso_8601": "2025-10-09T04:45:12.498831Z",
"url": "https://files.pythonhosted.org/packages/a6/17/473d680995da4d81589ead1a26da02c690debb252010e3679e656eceabab/tarot_reader-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d10a7724e533131be918fd3c4e512711e491a72882172ca3e144c7e05cd2ca0e",
"md5": "a57dee6d3abb7e478c5c84fcab68e29a",
"sha256": "cb7258bf43c7dc9e9bd9633223396344105bd9e5e3f452fe0207ea2f9c8ac910"
},
"downloads": -1,
"filename": "tarot_reader-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "a57dee6d3abb7e478c5c84fcab68e29a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 20156,
"upload_time": "2025-10-09T04:45:13",
"upload_time_iso_8601": "2025-10-09T04:45:13.948361Z",
"url": "https://files.pythonhosted.org/packages/d1/0a/7724e533131be918fd3c4e512711e491a72882172ca3e144c7e05cd2ca0e/tarot_reader-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-09 04:45:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zafrem",
"github_project": "tarot-reader",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tarot-reader"
}
JSON
