Basic Usage Examples
Setup
from qurankit import Quran
# Load default edition
quran = Quran.load()
# Or specify edition
quran = Quran.load(edition="tanzil-simple")
Surah Access
# Get surah by number
surah = quran.surah(1)
print(f"Surah 1: {surah.name_arabic} ({surah.name_english})")
print(f"Ayahs: {surah.ayah_count}")
print(f"Revelation: {surah.revelation_type}")
# List all surahs
for surah in quran.surahs:
print(f"{surah.number:3d}: {surah.name_arabic:15s} {surah.name_english}")
Ayah Access
# Get specific ayah
ayah = quran.ayah(1, 1)
print(f"{ayah.reference}: {ayah.text_original}")
# Get ayah with all metadata
ayah = quran.ayah(2, 255) # Ayat al-Kursi
print(f"Surah: {ayah.surah_number}")
print(f"Ayah: {ayah.number}")
print(f"Juz: {ayah.juz}")
print(f"Hizb: {ayah.hizb}")
print(f"Page: {ayah.page}")
print(f"Sajdah: {ayah.sajdah}")
print(f"Text: {ayah.text_original}")
Iterating Ayahs
# Iterate surah ayahs
for ayah in quran.surah(1).ayahs:
print(f"{ayah.reference}: {ayah.text_original}")
# Iterate with word tokens (requires QAC)
for ayah in quran.surah(1).ayahs:
print(f"{ayah.reference}: {ayah.text_original}")
for token in ayah.word_tokens:
print(f" {token.position}: {token.text_original} (lemma: {token.lemma}, root: {token.root})")
Structural Navigation
# By Juz
juz_1 = quran.get_juz(1)
print(f"Juz 1: {juz_1.surah_range} - {len(juz_1.ayahs)} ayahs")
# By Hizb
hizb_1 = quran.get_hizb(1)
# By Page
page_1 = quran.get_page(1)
# Sajdah verses
for ayah in quran.get_sajdah_ayahs():
print(f"Sajdah at {ayah.reference}")
# Range
ayahs = quran.get_ayahs_range(2, 255, 2, 260)
for ayah in ayahs:
print(ayah.reference, ayah.text_original[:50])
Edition Switching
# List available editions
for edition in quran.available_editions:
print(f"{edition.id}: {edition.name}")
# Switch edition
quran.set_edition("tanzil-uthmani")
ayah = quran.ayah(1, 1)
print(ayah.text_original) # Uthmani orthography
Configuration
from qurankit import QuranKitConfig
config = QuranKitConfig(
data_dir="/custom/data/path",
default_edition="tanzil-uthmani",
cache_enabled=True
)
quran = Quran.load(config=config)