Extension Adapters Guide¶
This notebook demonstrates how to use and develop extension adapters for QuranKit.
QuranKit v0.3.0+ includes an extension framework with 5 adapter types:
- TafsirAdapter - Exegesis/commentary
- HadithAdapter - Hadith collections
- QiraatAdapter - Qur'anic readings (qira'at)
- TajwidAdapter - Tajwid rules and annotations
- WaqfAdapter - Waqf (stopping) and ibtida' (starting) rules
Prerequisites¶
- QuranKit installed
- Sample data in
data/directory (included with package)
In [ ]:
Copied!
from qurankit import Quran
quran = Quran.load()
# All adapters are lazy-loaded via properties
print("Adapter registries:")
print(f" Tafsir: {type(quran.tafsir).__name__}")
print(f" Hadith: {type(quran.hadith).__name__}")
print(f" Qira'at: {type(quran.qiraat).__name__}")
print(f" Tajwid: {type(quran.tajwid).__name__}")
print(f" Waqf: {type(quran.waqf).__name__}")
from qurankit import Quran
quran = Quran.load()
# All adapters are lazy-loaded via properties
print("Adapter registries:")
print(f" Tafsir: {type(quran.tafsir).__name__}")
print(f" Hadith: {type(quran.hadith).__name__}")
print(f" Qira'at: {type(quran.qiraat).__name__}")
print(f" Tajwid: {type(quran.tajwid).__name__}")
print(f" Waqf: {type(quran.waqf).__name__}")
Using Built-in File-Based Adapters¶
QuranKit includes file-based implementations that load data from JSONL files.
In [ ]:
Copied!
# Check what sample data is available
import os
data_dir = "data"
if os.path.exists(data_dir):
for adapter_type in ["tafsir", "hadith", "qiraat", "tajwid", "waqf"]:
adapter_path = os.path.join(data_dir, adapter_type)
if os.path.exists(adapter_path):
files = os.listdir(adapter_path)
print(f"{adapter_type}: {files}")
else:
print(f"{adapter_type}: no data directory")
# Check what sample data is available
import os
data_dir = "data"
if os.path.exists(data_dir):
for adapter_type in ["tafsir", "hadith", "qiraat", "tajwid", "waqf"]:
adapter_path = os.path.join(data_dir, adapter_type)
if os.path.exists(adapter_path):
files = os.listdir(adapter_path)
print(f"{adapter_type}: {files}")
else:
print(f"{adapter_type}: no data directory")
Tafsir Adapter¶
Access tafsir (exegesis) entries for specific ayahs.
In [ ]:
Copied!
# Get tafsir for Al-Fatiha (1:1)
try:
entries = quran.tafsir.get_tafsir(1, 1)
print(f"Tafsir entries for 1:1: {len(entries)}")
for entry in entries:
print(f"\n Source: {entry.source_id} ({entry.source_name})")
print(f" Author: {entry.author}")
print(f" Text: {entry.text[:200]}...")
if entry.language:
print(f" Language: {entry.language}")
except Exception as e:
print(f"Error: {e}")
# Get tafsir for Al-Fatiha (1:1)
try:
entries = quran.tafsir.get_tafsir(1, 1)
print(f"Tafsir entries for 1:1: {len(entries)}")
for entry in entries:
print(f"\n Source: {entry.source_id} ({entry.source_name})")
print(f" Author: {entry.author}")
print(f" Text: {entry.text[:200]}...")
if entry.language:
print(f" Language: {entry.language}")
except Exception as e:
print(f"Error: {e}")
In [ ]:
Copied!
# Get tafsir for Ayat al-Kursi (2:255)
try:
entries = quran.tafsir.get_tafsir(2, 255)
print(f"Tafsir entries for 2:255: {len(entries)}")
for entry in entries:
print(f"\n Source: {entry.source_id}")
print(f" Text: {entry.text[:300]}...")
except Exception as e:
print(f"Error: {e}")
# Get tafsir for Ayat al-Kursi (2:255)
try:
entries = quran.tafsir.get_tafsir(2, 255)
print(f"Tafsir entries for 2:255: {len(entries)}")
for entry in entries:
print(f"\n Source: {entry.source_id}")
print(f" Text: {entry.text[:300]}...")
except Exception as e:
print(f"Error: {e}")
Hadith Adapter¶
Access hadith collections related to specific ayahs.
In [ ]:
Copied!
# Get hadith for 1:1
try:
hadiths = quran.hadith.get_hadith("sahih_bukhari", 1, 1)
print(f"Hadith from Sahih Bukhari for 1:1: {len(hadiths)}")
for h in hadiths:
print(f"\n Book: {h.book_name}")
print(f" Number: {h.hadith_number}")
print(f" Text: {h.text_arabic[:200]}...")
if h.text_translation:
print(f" Translation: {h.text_translation[:200]}...")
print(f" Grade: {h.grade}")
except Exception as e:
print(f"Error: {e}")
# Get hadith for 1:1
try:
hadiths = quran.hadith.get_hadith("sahih_bukhari", 1, 1)
print(f"Hadith from Sahih Bukhari for 1:1: {len(hadiths)}")
for h in hadiths:
print(f"\n Book: {h.book_name}")
print(f" Number: {h.hadith_number}")
print(f" Text: {h.text_arabic[:200]}...")
if h.text_translation:
print(f" Translation: {h.text_translation[:200]}...")
print(f" Grade: {h.grade}")
except Exception as e:
print(f"Error: {e}")
In [ ]:
Copied!
# Search hadith by text
try:
results = quran.hadith.search_hadith("بسم الله", collection="sahih_bukhari", limit=5)
print(f"Hadith search results: {len(results)}")
for h in results:
print(f" {h.collection_id} {h.book_number}:{h.hadith_number} - {h.text_arabic[:100]}...")
except Exception as e:
print(f"Error: {e}")
# Search hadith by text
try:
results = quran.hadith.search_hadith("بسم الله", collection="sahih_bukhari", limit=5)
print(f"Hadith search results: {len(results)}")
for h in results:
print(f" {h.collection_id} {h.book_number}:{h.hadith_number} - {h.text_arabic[:100]}...")
except Exception as e:
print(f"Error: {e}")
Qira'at Adapter¶
Compare different Qur'anic readings (qira'at).
In [ ]:
Copied!
# Compare readings for 2:10
try:
comparison = quran.qiraat.compare_readings(2, 10, ["hafs", "warsh"])
print(f"Comparison for 2:10:")
print(f" Base (Hafs): {comparison.base_text}")
for reading in comparison.readings:
print(f" {reading.qiraat_id}: {reading.text}")
print(f" Differences: {comparison.difference_summary}")
except Exception as e:
print(f"Error: {e}")
# Compare readings for 2:10
try:
comparison = quran.qiraat.compare_readings(2, 10, ["hafs", "warsh"])
print(f"Comparison for 2:10:")
print(f" Base (Hafs): {comparison.base_text}")
for reading in comparison.readings:
print(f" {reading.qiraat_id}: {reading.text}")
print(f" Differences: {comparison.difference_summary}")
except Exception as e:
print(f"Error: {e}")
In [ ]:
Copied!
# Get all available readings for an ayah
try:
readings = quran.qiraat.get_all_readings_for_ayah(1, 1)
print(f"All readings for 1:1: {len(readings)}")
for r in readings:
print(f" {r.qiraat_id}: {r.text}")
except Exception as e:
print(f"Error: {e}")
# Get all available readings for an ayah
try:
readings = quran.qiraat.get_all_readings_for_ayah(1, 1)
print(f"All readings for 1:1: {len(readings)}")
for r in readings:
print(f" {r.qiraat_id}: {r.text}")
except Exception as e:
print(f"Error: {e}")
Tajwid Adapter¶
Access tajwid rules and annotations.
In [ ]:
Copied!
# Get all tajwid rules
try:
rules = quran.tajwid.get_rules()
print(f"Tajwid rules loaded: {len(rules)}")
for rule in rules[:5]:
print(f"\n Type: {rule.rule_type.value}")
print(f" Description: {rule.description}")
print(f" Arabic: {rule.description_arabic}")
if rule.examples:
for ex in rule.examples[:2]:
print(f" Example: {ex['surah']}:{ex['ayah']} - {ex['text']} (highlight: {ex['highlight']})")
except Exception as e:
print(f"Error: {e}")
# Get all tajwid rules
try:
rules = quran.tajwid.get_rules()
print(f"Tajwid rules loaded: {len(rules)}")
for rule in rules[:5]:
print(f"\n Type: {rule.rule_type.value}")
print(f" Description: {rule.description}")
print(f" Arabic: {rule.description_arabic}")
if rule.examples:
for ex in rule.examples[:2]:
print(f" Example: {ex['surah']}:{ex['ayah']} - {ex['text']} (highlight: {ex['highlight']})")
except Exception as e:
print(f"Error: {e}")
In [ ]:
Copied!
# Get tajwid annotations for specific ayah
try:
annotations = quran.tajwid.get_annotations(2, 10)
print(f"Tajwid annotations for 2:10: {len(annotations)}")
for ann in annotations:
print(f" {ann.rule_type.value}: position {ann.position_start}-{ann.position_end}")
print(f" Note: {ann.note}")
except Exception as e:
print(f"Error: {e}")
# Get tajwid annotations for specific ayah
try:
annotations = quran.tajwid.get_annotations(2, 10)
print(f"Tajwid annotations for 2:10: {len(annotations)}")
for ann in annotations:
print(f" {ann.rule_type.value}: position {ann.position_start}-{ann.position_end}")
print(f" Note: {ann.note}")
except Exception as e:
print(f"Error: {e}")
Waqf Adapter¶
Access waqf (stopping) and ibtida' (starting) rules.
In [ ]:
Copied!
# Get waqf rules
try:
rules = quran.waqf.get_waqf_rules()
print(f"Waqf rules loaded: {len(rules)}")
for rule in rules[:5]:
print(f"\n Type: {rule.waqf_type.value}")
print(f" Description: {rule.description}")
print(f" Arabic: {rule.description_arabic}")
if rule.examples:
for ex in rule.examples[:2]:
print(f" Example: {ex['surah']}:{ex['ayah']} - {ex['text']} (highlight: {ex['highlight']})")
except Exception as e:
print(f"Error: {e}")
# Get waqf rules
try:
rules = quran.waqf.get_waqf_rules()
print(f"Waqf rules loaded: {len(rules)}")
for rule in rules[:5]:
print(f"\n Type: {rule.waqf_type.value}")
print(f" Description: {rule.description}")
print(f" Arabic: {rule.description_arabic}")
if rule.examples:
for ex in rule.examples[:2]:
print(f" Example: {ex['surah']}:{ex['ayah']} - {ex['text']} (highlight: {ex['highlight']})")
except Exception as e:
print(f"Error: {e}")
In [ ]:
Copied!
# Get ibtida' rules
try:
rules = quran.waqf.get_ibtida_rules()
print(f"Ibtida rules loaded: {len(rules)}")
for rule in rules[:5]:
print(f"\n Type: {rule.ibtida_type.value}")
print(f" Description: {rule.description}")
print(f" Arabic: {rule.description_arabic}")
except Exception as e:
print(f"Error: {e}")
# Get ibtida' rules
try:
rules = quran.waqf.get_ibtida_rules()
print(f"Ibtida rules loaded: {len(rules)}")
for rule in rules[:5]:
print(f"\n Type: {rule.ibtida_type.value}")
print(f" Description: {rule.description}")
print(f" Arabic: {rule.description_arabic}")
except Exception as e:
print(f"Error: {e}")
Developing Custom Adapters¶
See docs/extension-development.md for a complete guide on creating custom adapters.
Key steps:
- Subclass the appropriate base adapter (e.g.,
TafsirAdapter) - Implement required abstract methods
- Register with the adapter registry
- Provide data in JSONL format
from qurankit.adapters import TafsirAdapter, TafsirEntry, TafsirSource
class MyTafsirAdapter(TafsirAdapter):
def load(self) -> None:
# Load your data
pass
def get_tafsir(self, surah: int, ayah: int) -> list[TafsirEntry]:
# Return tafsir entries
pass
# Register
from qurankit.adapters import get_tafsir_registry
registry = get_tafsir_registry()
registry.register("my_tafsir", MyTafsirAdapter(data_path="/path/to/data"))
Adapter Registry Statistics¶
Check what data is loaded in each adapter.
In [ ]:
Copied!
# Get registry statistics
try:
print("Adapter Statistics:")
tafsir_stats = quran.tafsir._registry.get("file_tafsir")
if tafsir_stats and hasattr(tafsir_stats, 'get_stats'):
stats = tafsir_stats.get_stats()
print(f" Tafsir: {stats}")
hadith_stats = quran.hadith._registry.get("file_hadith")
if hadith_stats and hasattr(hadith_stats, 'get_stats'):
stats = hadith_stats.get_stats()
print(f" Hadith: {stats}")
qiraat_stats = quran.qiraat._registry.get("file_qiraat")
if qiraat_stats and hasattr(qiraat_stats, 'get_stats'):
stats = qiraat_stats.get_stats()
print(f" Qira'at: {stats}")
tajwid_stats = quran.tajwid._registry.get("file_tajwid")
if tajwid_stats and hasattr(tajwid_stats, 'get_stats'):
stats = tajwid_stats.get_stats()
print(f" Tajwid: {stats}")
waqf_stats = quran.waqf._registry.get("file_waqf")
if waqf_stats and hasattr(waqf_stats, 'get_stats'):
stats = waqf_stats.get_stats()
print(f" Waqf: {stats}")
except Exception as e:
print(f"Error getting stats: {e}")
# Get registry statistics
try:
print("Adapter Statistics:")
tafsir_stats = quran.tafsir._registry.get("file_tafsir")
if tafsir_stats and hasattr(tafsir_stats, 'get_stats'):
stats = tafsir_stats.get_stats()
print(f" Tafsir: {stats}")
hadith_stats = quran.hadith._registry.get("file_hadith")
if hadith_stats and hasattr(hadith_stats, 'get_stats'):
stats = hadith_stats.get_stats()
print(f" Hadith: {stats}")
qiraat_stats = quran.qiraat._registry.get("file_qiraat")
if qiraat_stats and hasattr(qiraat_stats, 'get_stats'):
stats = qiraat_stats.get_stats()
print(f" Qira'at: {stats}")
tajwid_stats = quran.tajwid._registry.get("file_tajwid")
if tajwid_stats and hasattr(tajwid_stats, 'get_stats'):
stats = tajwid_stats.get_stats()
print(f" Tajwid: {stats}")
waqf_stats = quran.waqf._registry.get("file_waqf")
if waqf_stats and hasattr(waqf_stats, 'get_stats'):
stats = waqf_stats.get_stats()
print(f" Waqf: {stats}")
except Exception as e:
print(f"Error getting stats: {e}")