Skip to main content

Daily Tarot Card Readings

Build and Test

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)

Source distribution for byteme-tarot 0.1.1
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)

Table of built distributions (wheels) for byteme-tarot 0.1.1
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page