Daily Tarot Card Readings
A light-hearted Python package that draws a three-card tarot reading (Past, Present, and Future) and interprets it. Give it a name and a date, and it deals three unique cards from a 78-card deck. Each card may be upright or reversed. The reading can be altered by topic (love, career, study, money, general) and tone (mystic, funny, programmer). The same name and date will always give the same cards.
PyPI: https://pypi.org/project/byteme-tarot/
Task board: https://github.com/orgs/software-students-fall2026/projects/95
Team members
Installation
Requires Python 3.11 or newer.
pip install byteme-tarot
If pip isn't found, use python3 -m pip install byteme-tarot
Then import it in your own code:
from tarot_package import daily_reading
print(daily_reading("Emma", topic="love", tone="funny"))
print(daily_reading("Uuree"))
Contributing
On Windows, use python or py in place of python3. If pipenv isn't found, run python -m pipenv
git clone https://github.com/software-students-fall2026/python-package-exercise-byteme.git
cd python-package-exercise-byteme
python3 -m pip install pipenv
pipenv install --dev
pipenv run python -m pytest tests/
pipenv run python -m build
If pipenv can't find the right Python, run pipenv --python python3 install --dev.
To run a single test file:
pipenv run python -m pytest tests/test_lookup.py -v
Every pull request is built and tested on Python 3.10, 3.11, and 3.12 by GitHub Actions.
Example Program
See examples/example.py, which uses every function in the package.
If you cloned the repository, install the package first, then run the example from the repository root:
python3 -m pip install -e .
python3 examples/example.py
If you installed from PyPI, run:
curl -O https://raw.githubusercontent.com/software-students-fall2026/python-package-exercise-byteme/main/examples/example.py
python3 example.py
Functions
lookup_card(query)
Finds a card by name or keyword, where small typos are forgiven. Raises ValueError if nothing matches and TypeError if query isn't a string
from tarot_package import lookup_card
print(lookup_card("the fool").name)
Output:
The Fool
draw_cards(name, date=None, count=3, allow_reversed=True)
Draws unique cards from the 78 card deck and each draw is seeded by name and date, so the same person on the same day gets the same cards. Returns a list of (Card, orientation)
from datetime import date
from tarot_package import draw_cards
drawn = draw_cards("Jingjing", date=date(2026, 11, 8))
for card, orientation in drawn:
print(f"{card.name} ({orientation})")
Output:
Four of Wands (reversed)
Five of Pentacles (reversed)
The Devil (reversed)
interpret_card(card, orientation, topic, tone)
Interprets a single card by phrasing its upright or reversed meaning for the chosen topic and tone, returning a String. Raises a TypeError for non-string input or ValueError if an option is unsupported.
from tarot_package import lookup_card, interpret_card
card = lookup_card("The Fool")
print(interpret_card(card, "upright", "love", "funny"))
Output:
Your tarot plot twist: A fresh start is calling, so take the leap with an open heart. For your relationships, keep beginnings, innocence, adventure, spontaneity on the guest list. Bring snacks.
interpret_spread(drawn, topic="general", tone="mystic")
Interprets Past, Present, and Future, plus a summary of the drawn 3 cards, returning a String.
from datetime import date
from tarot_package import draw_cards, interpret_spread
drawn = draw_cards("Tracy", date=date(2026, 11, 8))
print(interpret_spread(drawn, topic="career", tone="programmer"))
Output:
Past: Two of Wands (reversed)
Card output: Fear of the unknown keeps you in your comfort zone, so plan one bold step. For your work and career, debug your next step with these keywords: planning, decisions, vision, ambition.
Present: The High Priestess (upright)
Card output: Stay quiet and listen, because your intuition knows more than you think. For your work and career, debug your next step with these keywords: intuition, mystery, secrets, inner voice.
Future: Ten of Pentacles (reversed)
Card output: Money disputes or shaky foundations need attention before they grow. For your work and career, debug your next step with these keywords: legacy, family, wealth, long-term.
Summary: Pipeline: planning -> intuition -> legacy. Keep debugging and iterating; progress will come.
lucky_extras(drawn, category)
Categories: "color", "number", "advice"
Returns a lucky color, number, or advice based on the drawn cards. Raises a ValueError for an invalid category.
from datetime import date
from tarot_package import draw_cards, lucky_extras
drawn = draw_cards("Emma", date=date(2026, 11, 8))
print(lucky_extras(drawn, "color"))
print(lucky_extras(drawn, "number"))
print(lucky_extras(drawn, "advice"))
Output:
Lucky color: green
Lucky number: 8
Consider the potential impact of diligence on your well-being.
daily_reading(name, date=None, topic="general", tone="mystic")
Returns a full daily reading including interpretation of each card, interpretation of all 3 together, and lucky color, number, and advice.
from datetime import date
from tarot_package import daily_reading
print("Default (mystic tone)")
print(daily_reading("Uuree", date=date(2026, 11, 8)))
print()
print("Love topic, funny tone")
print(daily_reading("Uuree", date=date(2026, 11, 8), topic="love", tone="funny"))
Output:
Default (mystic tone)
Reading for Uuree
Past: Knight of Swords (upright)
The cards whisper: Quick, bold action pushes things forward, but mind your tone. In your daily life, let these themes guide your reflection: speed, ambition, bluntness, drive.
Present: Two of Pentacles (upright)
The cards whisper: You are juggling a lot, so stay flexible and keep your priorities straight. In your daily life, let these themes guide your reflection: balance, juggling, adaptability, priorities.
Future: The Tower (reversed)
The cards whisper: You are dodging an upheaval that needs to happen sooner or later. In your daily life, let these themes guide your reflection: upheaval, shock, revelation, collapse.
Summary: I see speed going through balance and towards upheaval. A lingering darkness is present, but it can be overcome.
Lucky color: yellow
Lucky number: 6
Be mindful of how upheaval affects your choices.
Love topic, funny tone
Reading for Uuree
Past: Knight of Swords (upright)
Your tarot plot twist: Quick, bold action pushes things forward, but mind your tone. For your relationships, keep speed, ambition, bluntness, drive on the guest list. Bring snacks.
Present: Two of Pentacles (upright)
Your tarot plot twist: You are juggling a lot, so stay flexible and keep your priorities straight. For your relationships, keep balance, juggling, adaptability, priorities on the guest list. Bring snacks.
Future: The Tower (reversed)
Your tarot plot twist: You are dodging an upheaval that needs to happen sooner or later. For your relationships, keep upheaval, shock, revelation, collapse on the guest list. Bring snacks.
Summary: Plot twist: speed, then balance, and finally upheaval. One little plot twist on the horizon.
Lucky color: yellow
Lucky number: 6
Be mindful of how upheaval affects your choices.
Valid options
- Topics:
love,career,study,money,general - Tones:
mystic,funny,programmer
Configuration
No "secret" configuration files, env variables, or databases are needed.
Metadata
Release files for byteme-tarot 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| byteme_tarot-0.1.1.tar.gz | 35.5 kB | Without provenance | Details for byteme_tarot-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| byteme_tarot-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for byteme_tarot-0.1.1-py3-none-any.whl |
Total release size: 66.9 kB
Release files / byteme_tarot-0.1.1.tar.gz
| Download URL | byteme_tarot-0.1.1.tar.gz |
|---|---|
| Size | 35.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
687d3515c15efb56686a2dc2a9cc6268ad317079223c8bd8881774786df64d05
|
|
BLAKE2b-256 checksum How to use checksums |
87daa3a77723ab7be74ad3ed37acfc79df5fb4002e4bc0697d6846745e8a9550
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Release files / byteme_tarot-0.1.1-py3-none-any.whl
| Download URL | byteme_tarot-0.1.1-py3-none-any.whl |
|---|---|
| Size | 31.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
86054e1c7816c9ab140d027972723a654f11eccdf9576e016456ddecf3e76113
|
|
BLAKE2b-256 checksum How to use checksums |
b2b33d7ba2da1c931b37ac065369bba648aefa7a888f15d0998355bc55dde317
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Security for byteme-tarot 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.