Metadata-Version: 2.4
Name: astroinsight-python-sdk
Version: 1.0.0
Summary: Official Python SDK for the Astro Insight API - Astrology, Panchang, Tarot, and Numerology services.
Author-email: Astro Insight Team <support@astroinsightapi.com>
License: MIT
Project-URL: Homepage, https://github.com/AstroInsightApi/astroinsight-python-sdk
Project-URL: Documentation, https://github.com/AstroInsightApi/astroinsight-python-sdk#readme
Project-URL: Repository, https://github.com/AstroInsightApi/astroinsight-python-sdk.git
Project-URL: Issues, https://github.com/AstroInsightApi/astroinsight-python-sdk/issues
Keywords: astrology,vedic-astrology,panchang,horoscope,tarot,numerology,astroinsight,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Requires-Dist: httpx>=0.23.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
Requires-Dist: responses>=0.23.0; extra == "dev"

# Astro Insight Python SDK

[![PyPI Version](https://img.shields.io/pypi/v/astroinsight-python-sdk.svg)](https://pypi.org/project/astroinsight-python-sdk/)
[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

Official, strongly-typed **Python 3.9+ SDK** for the **Astro Insight API**. Supports both **Synchronous** (`requests`) and **Asynchronous** (`httpx` / `asyncio`) execution modes to easily integrate Vedic Astrology, Western Astrology, Matchmaking, Panchang, Muhurta, Tarot, Numerology, Chinese Astrology, and Geolocation calculations into your Python applications.

---

## Features

- 🪐 **Vedic Astrology**: Ashtakvarga, Vimshottari / Char / Yogini Dashas, KP System, Jaimini, Lal Kitab, Varshaphal, Ghat Chakra, Horoscope Charts & Doshas.
- 💍 **Matchmaking**: Guna Milan, Kundali Compatibility, Manglik Matching.
- 🗓️ **Panchang & Muhurta**: Daily Panchang, Choghadiya, Hora, Shubh Muhurta timing.
- 🔮 **Western Astrology & Tarot**: Natal Charts, Solar Return, Daily/Weekly/Monthly Transits, Synastry, Tarot spreads (One-card, Three-card, Celtic Cross, Love, Career).
- 🔢 **Numerology**: Vedic & Western Numerology (Life Path, Destiny, Soul Urge).
- ☯️ **Chinese Astrology & Biorhythm**: Zodiac sign compatibility & biorhythm calculations.
- 🌍 **Geo Utilities**: Place search, timezone lookup by coordinates or ID.
- ⚡ **Dual Execution Modes**: Synchronous (`AstroClient`) and Async (`AsyncAstroClient`) with `asyncio`.
- 🛡️ **Strongly Typed Dataclasses**: `BirthDetails`, `MatchInput`, and `GeoLocation` models.

---

## Installation

Install the package via pip:

```bash
pip install astroinsight-python-sdk
```

---

## Quick Start

### 1. Synchronous Client (`AstroClient`)

```python
from astroinsight import AstroClient, BirthDetails

client = AstroClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET"
)

birth = BirthDetails(
    day=15, month=8, year=1995,
    hour=10, min=30, sec=0,
    tzone=5.5, lat=28.6139, lon=77.2090
)

# Fetch Birth Details
details = client.vedic.astro_details.get_birth_details(birth)
print(details["data"]["birth_details"]["day"]) # Tuesday

# Fetch Sun Bhinnashtakavarga
ashtak = client.vedic.ashtakvarga.get_planet_ashtak("sun", birth)

# One Card Tarot Reading
tarot = client.tarot.get_one_card_reading()
```

### 2. Asynchronous Client (`AsyncAstroClient`)

```python
import asyncio
from astroinsight import AsyncAstroClient, BirthDetails

async def main():
    async with AsyncAstroClient(
        client_id="YOUR_CLIENT_ID",
        client_secret="YOUR_CLIENT_SECRET"
    ) as async_client:
        
        birth = BirthDetails(day=15, month=8, year=1995, hour=10, min=30)
        
        # Async call
        details = await async_client.vedic.astro_details.get_birth_details(birth)
        print(details["message"])

asyncio.run(main())
```

---

## Code Examples

### 🪐 Vedic Astrology & Dashas

```python
# Major Vimshottari Dasha
dasha = client.vedic.vimshottari_dasha.get_major_dasha(birth)

# Gemstone Suggestions
remedies = client.vedic.suggestions.get_gemstone_suggestions(birth)

# Manglik Dosha Check
manglik = client.vedic.horoscope_dosha.get_manglik_dosha(birth)
```

### 💍 Matchmaking (Guna Milan)

```python
from astroinsight import MatchInput

male = BirthDetails(15, 8, 1995, 10, 30, lat=28.6139, lon=77.2090)
female = BirthDetails(20, 11, 1997, 14, 15, lat=19.0760, lon=72.8777)

match_input = MatchInput(male=male, female=female)

# Calculate Guna Milan
score = client.vedic.match_making.get_guna_milan(match_input)
```

### 🗓️ Daily Panchang & Muhurta

```python
panchang = client.vedic.panchang.get_daily_panchang(birth)
choghadiya = client.vedic.muhurta.get_choghadiya(birth)
```

### 📊 Horoscope & Geo Services

```python
# Daily Horoscope for Leo
leo_daily = client.horoscope.get_daily_horoscope("leo")

# Search Place Coordinates
place_info = client.geo.search_place("Delhi")
```

---

## Dynamic Configuration & Headers

```python
# Switch language dynamically
client.set_language("hi")

# Switch Ayanamsha system
client.set_ayanamsha("raman")
```

---

## Exception Handling

```python
from astroinsight import (
    AstroClient, BirthDetails,
    AuthenticationError, ValidationError, RateLimitError, AstroException
)

client = AstroClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
birth = BirthDetails(15, 8, 1995, 10, 30)

try:
    response = client.vedic.astro_details.get_birth_details(birth)
except AuthenticationError as e:
    print(f"Auth failed: {e.message}")
except ValidationError as e:
    print(f"Validation failed: {e.message}, Errors: {e.errors}")
except RateLimitError as e:
    print("Rate limit exceeded. Retry later.")
except AstroException as e:
    print(f"API Error [{e.status_code}]: {e.message}")
```

---

## Running Tests

Run unit tests using pytest:

```bash
pip install -e .[dev]
python3 -m pytest
```

---

## License

This SDK is open-sourced software licensed under the [MIT License](LICENSE).
