Metadata-Version: 2.5
Name: qurancom-py
Version: 0.1.0
Summary: Modern, fully typed Python wrapper for the official Quran.com API (v4) with sync and async support.
Project-URL: Homepage, https://github.com/ayoubanlouf/qurancom-py
Project-URL: Documentation, https://api-docs.quran.com
Project-URL: Repository, https://github.com/ayoubanlouf/qurancom-py.git
Project-URL: Issues, https://github.com/ayoubanlouf/qurancom-py/issues
Author: Ayoub Anlouf
License-Expression: MIT
License-File: LICENSE
Keywords: api-wrapper,asyncio,ayah,httpx,islam,quran,qurancom,recitation,sdk,surah,tafsir
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1.0.0,>=0.24.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Requires-Dist: respx>=0.21.0; extra == 'test'
Description-Content-Type: text/markdown

# qurancom-py

[![PyPI Version](https://img.shields.io/pypi/v/qurancom-py.svg)](https://pypi.org/project/qurancom-py/)
[![Python Versions](https://img.shields.io/pypi/pyversions/qurancom-py.svg)](https://pypi.org/project/qurancom-py/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![CI/CD](https://github.com/ayoubanlouf/qurancom-py/actions/workflows/publish.yml/badge.svg)](https://github.com/ayoubanlouf/qurancom-py/actions)


A modern, fast, fully typed Python wrapper for the official **[Quran.com API (v4)](https://api-docs.quran.com/)**.

Built with `httpx` and Python standard library `dataclasses`, providing both **synchronous** (`QuranClient`) and **asynchronous** (`AsyncQuranClient`) interfaces, automatic pagination, word-by-word timing segments, multi-script Quranic text, tafsirs, translations, audio streaming, and a built-in CLI.

---

## Features

- ✨ **Full Quran.com v4 Endpoint Coverage**: Chapters, Verses, Tafsirs, Translations, Audio, Juzs, and Search.
- ⚡ **Sync & Async**: Dual client interfaces (`QuranClient` & `AsyncQuranClient`) sharing the same typed abstractions.
- 🔄 **Smart Pagination**: Seamlessly iterate across chapters, juzs, and pages item-by-item or page-by-page (`Paginator` & `AsyncPaginator`).
- 📜 **Multi-Script Support**: Uthmani, Tajweed, Indo-Pak, Imlaei, and Madani V1/V2 font glyphs.
- 🎧 **Audio & Timestamps**: Complete verse and chapter-level recitation streams with word-by-word sync timestamps.
- 🛡️ **Type-Safe & Lightweight**: Zero bloated dependencies (only `httpx`), powered by standard dataclasses with `slots=True`.
- 💻 **Built-in CLI**: Query chapters, verses, search, and recitations directly from your terminal.

---

## Installation

```bash
pip install qurancom-py
```

Or install with development dependencies:

```bash
pip install "qurancom-py[dev]"
```

---

## Quickstart

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

```python
from qurancom import QuranClient

with QuranClient() as client:
    # 1. Fetch all chapters (Surahs)
    chapters = client.chapters.list()
    for chapter in chapters[:3]:
        print(f"Surah {chapter.id}: {chapter.name_simple} ({chapter.name_arabic}) - {chapter.verses_count} verses")

    # 2. Fetch Ayat al-Kursi with English translation
    verse = client.verses.by_key("2:255", translations=[20])
    print(f"\nArabic: {verse.arabic_text}")
    print(f"Translation: {verse.primary_translation}")

    # 3. Search the Quran
    search_results = client.search.search("mercy", size=3)
    for result in search_results.results:
        print(f"[{result.verse_key}] {result.text}")
```

---

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

```python
import asyncio
from qurancom import AsyncQuranClient

async def main():
    async with AsyncQuranClient() as client:
        # Fetch chapter information
        surah = await client.chapters.get(1)
        print(f"Surah {surah.name_simple} - Revelation: {surah.revelation_place}")

        # Fetch raw Uthmani text of Surah Al-Ikhlas (Chapter 112)
        verses = await client.quran.uthmani(chapter_number=112)
        for v in verses:
            print(f"{v.verse_key}: {v.text}")

asyncio.run(main())
```

---

### 3. Automatic Pagination

Stream through verses without manual page calculation:

```python
from qurancom import QuranClient

with QuranClient() as client:
    # Auto-paginates across all 7 verses of Surah Al-Fatihah
    for verse in client.verses.iterate_chapter(1, per_page=2):
        print(f"{verse.verse_key} -> {verse.arabic_text}")
```

Async iteration is equally straightforward:

```python
async for verse in async_client.verses.iterate_chapter(1):
    print(verse.verse_key)
```

---

### 4. Audio & Recitations

```python
from qurancom import QuranClient

with QuranClient() as client:
    # Fetch full chapter audio stream
    audio = client.audio.chapter_recitation(reciter_id=7, chapter_id=1)
    print(f"Audio URL: {audio.audio_url} (Format: {audio.format})")

    # Fetch verse audio with word-by-word timestamps
    ayah_audio = client.audio.by_ayah(reciter_id=7, verse_key="1:1")
    print(f"Ayah Audio: {ayah_audio.url}")
    print(f"Segments: {ayah_audio.segments}")
```

---

## Command Line Interface (CLI)

`qurancom-py` comes with a built-in CLI tool `qurancom`:

```bash
# List all 114 Surahs
qurancom chapter list

# Get Surah details
qurancom chapter get 1

# Read historical chapter background
qurancom chapter info 1

# Fetch verse by key with English translation
qurancom verse get 1:1
qurancom verse get 2:255 --translations 20,85

# Get a random Ayah
qurancom verse random

# Search the Quran
qurancom search "patience" --size 5

# List available translations & reciters
qurancom resources translations
qurancom resources recitations
```

---

## Authentication & Custom Configuration

While public endpoints on Quran.com do not require authentication, you can supply OAuth2 credentials if using Quran Foundation developer features:

```python
client = QuranClient(
    auth_token="YOUR_OAUTH_TOKEN",
    client_id="YOUR_CLIENT_ID",
    timeout=45.0,
    max_retries=5,
)
```

---

## Error Handling

All API errors inherit from `QuranAPIError`:

```python
from qurancom import QuranClient
from qurancom.exceptions import ResourceNotFoundError, RateLimitError, QuranAPIError

with QuranClient() as client:
    try:
        client.chapters.get(999)
    except ResourceNotFoundError as e:
        print(f"Chapter not found: {e}")
    except RateLimitError as e:
        print(f"Rate limited: {e}")
    except QuranAPIError as e:
        print(f"API Error [{e.status_code}]: {e.message}")
```

---

## Contributing & Testing

```bash
# Clone the repository
git clone https://github.com/ayoubanlouf/qurancom-py.git
cd qurancom-py


# Install in editable mode with test dependencies
pip install -e ".[dev]"

# Run unit tests
pytest tests/unit/ -v

# Run live integration tests
pytest tests/integration/ -v
```

---

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
