orbpondering 0.1.0

Tarot spreads seeded by daily astrological calculations

Orbpondering

Orbpondering generates daily tarot readings based on astrological calculations. It uses your location and the current date to compute planetary positions and generate a deterministic tarot spread.

Features

• Daily Tarot Draws: Receive a tarot reading based on current planetary positions
• Educational Mode: Walk through the astrological calculations step by step
• Natal Chart Support: Personalize readings with your birth chart
• Multiple Spreads: Choose from different tarot spread types
• Deterministic: Same date/location always produces same reading

Installation

Install the package with pip:

pip install orbpondering

Or install with the optional CLI dependencies for enhanced display:

pip install orbpondering[cli]

Quick Start

Basic Daily Tarot Reading

orbpondering

By default, this draws for today's date and location (0° latitude/longitude).

Custom Date and Location

orbpondering 2025-06-15 --lat 40.7128 --lon -74.0060

Educational Mode

orbpondering --education

This shows step-by-step calculations of planetary positions, house cusps, and the seed generation.

Natal Chart Mode

With Birth Data

orbpondering \
  --birth-date 1990-05-15 \
  --birth-time 14:30 \
  --birth-zone "America/New_York" \
  --birth-lat 41.8781 \
  --birth-lon -87.6298 \
  --spread three_card

This enables natal chart mode, incorporating your birth chart into the tarot reading.

Available Spreads

• Daily (default): Single card for the day's theme
• Three Card: Past, Present, Future
• Celtic Cross: Detailed 10-card spread

Command Line Options

usage: orbpondering [-h] [--lat LAT] [--lon LON]
                   [--house {whole_sign,equal,porphyry,placidus}]
                   [--spread {daily,three_card,celtic_cross}] [--education]
                   [--verbose] [--birth-date BIRTH_DATE]
                   [--birth-time BIRTH_TIME] [--birth-zone BIRTH_ZONE]
                   [--birth-lat BIRTH_LAT] [--birth-lon BIRTH_LON]
                   [date]

Daily tarot draw seeded by astrological chart

positional arguments:
  date                  ISO date (YYYY-MM-DD). Default: today

options:
  -h, --help            show this help message and exit
  --lat LAT             Observer latitude
  --lon LON             Observer longitude
  --house {whole_sign,equal,porphyry,placidus}
                        House system
  --spread {daily,three_card,celtic_cross}
                        Spread name
  --education, -e       Educational mode: walk through calculations step by
                        step
  --verbose, -v         Verbose educational output
  --birth-date BIRTH_DATE
                        Birth date (YYYY-MM-DD) to enable natal chart mode
  --birth-time BIRTH_TIME
                        Birth time (HH:MM) - optional, defaults to noon UTC
  --birth-zone BIRTH_ZONE
                        Birth timezone (IANA format) - optional, defaults to
                        UTC
  --birth-lat BIRTH_LAT
                        Birth latitude
  --birth-lon BIRTH_LON
                        Birth longitude

Development

To develop orbpondering, clone the repository and install in development mode:

git clone https://github.com/phildini/orbpondering.git
cd orbpondering
uv sync --all-extras  # Install all dependencies including dev
uv run pytest         # Run tests
uv run ruff check     # Lint code
uv run mypy src/      # Type check

License

This project is licensed under the MIT License - see the LICENSE file for details.