qurancom-py

A modern, fast, fully typed Python wrapper for the official Quran.com API (v4).

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

pip install qurancom-py

Or install with development dependencies:

pip install "qurancom-py[dev]"

Quickstart

1. Synchronous Client (QuranClient)

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)

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:

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:

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

4. Audio & Recitations

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:

# 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:

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:

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

# 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 for details.