Extension Development¶
QuranKit uses a provider-neutral adapter pattern for integrating external resources (lexicons, tafsir, hadith, qira'at, tajwid, etc.). This guide explains how to build custom adapters.
Adapter Architecture¶
Core Principles¶
- Provider-neutral — Core library doesn't depend on specific datasets
- Explicit registration — Adapters registered at runtime
- Provenance tracking — Every adapter documents its source
- License awareness — Adapters declare redistribution status
- Optional dependencies — Adapter packages are optional extras
Adapter Types¶
| Adapter Type | Purpose | Base Class |
|---|---|---|
TextProvider |
Qur'anic text editions | TextProvider |
MorphologyProvider |
Word-level morphology | MorphologyProvider |
DictionaryAdapter |
Lexical entries | DictionaryAdapter |
TafsirAdapter |
Tafsir/exegesis | TafsirAdapter (planned) |
HadithAdapter |
Hadith collections | HadithAdapter (planned) |
QiraatAdapter |
Readings | QiraatAdapter (planned) |
TajwidAdapter |
Recitation rules | TajwidAdapter (planned) |
Building a Dictionary Adapter¶
1. Implement the Abstract Base Class¶
# my_package/adapters.py
from qurankit.lexicon import DictionaryAdapter
from qurankit.models.lexicon import LexicalEntry, LexicalSense
from typing import Iterator, Optional
class MyDictionaryAdapter(DictionaryAdapter):
"""Adapter for My Custom Dictionary."""
def __init__(self, data_path: str, source: str = "My Dictionary"):
self.data_path = data_path
self.source = source
self._index = None
@property
def adapter_id(self) -> str:
return "my-dictionary"
@property
def name(self) -> str:
return "My Custom Dictionary"
@property
def source_id(self) -> str:
return "my-dictionary-source"
@property
def license(self) -> str:
return "CC-BY-4.0"
@property
def redistribution_status(self) -> str:
return "allowed"
def load(self) -> None:
"""Load and index dictionary data."""
# Build search index from data_path
self._index = build_index(self.data_path)
def lookup_headword(self, headword: str, limit: int = 50) -> list[LexicalEntry]:
"""Look up entries by headword."""
if self._index is None:
self.load()
return self._index.search_headword(headword, limit)
def lookup_root(self, root_form: str, limit: int = 50) -> list[LexicalEntry]:
"""Look up entries by root."""
if self._index is None:
self.load()
return self._index.search_root(root_form, limit)
def lookup_lemma(self, lemma_form: str, limit: int = 50) -> list[LexicalEntry]:
"""Look up entries by lemma."""
if self._index is None:
self.load()
return self._index.search_lemma(lemma_form, limit)
def get_entry(self, entry_id: str) -> Optional[LexicalEntry]:
"""Get full entry by ID."""
if self._index is None:
self.load()
return self._index.get_entry(entry_id)
def iter_entries(self) -> Iterator[LexicalEntry]:
"""Iterate all entries (for bulk operations)."""
if self._index is None:
self.load()
yield from self._index.iter_entries()
2. Register the Adapter¶
# In your application code
from qurankit.lexicon import DictionaryAdapterRegistry
from my_package.adapters import MyDictionaryAdapter
registry = DictionaryAdapterRegistry()
adapter = MyDictionaryAdapter("/path/to/dictionary.jsonl")
registry.register("my-dict", adapter)
# Now available globally
from qurankit.lexicon import get_lexicon_registry
global_registry = get_lexicon_registry()
global_registry.register("my-dict", adapter)
3. Use with QuranicVocabulary¶
from qurankit import Quran
quran = Quran.load()
# Vocabulary automatically uses registered adapters
vocab = quran.vocabulary
# Dictionary lookups
entries = vocab.lookup_dictionary("رَحْمَة", source="my-dict")
for entry in entries:
print(f"{entry.headword}: {entry.senses[0].definition}")
FileBasedDictionaryAdapter (Built-in)¶
For JSONL or SQLite dictionary files, use the built-in adapter:
JSONL Format¶
{"entry_id": "001", "headword": "رَحْمَة", "root_form": "ر ح م", "lemma_form": "رَحْمَة", "senses": [{"definition": "Mercy", "definition_language": "en"}]}
{"entry_id": "002", "headword": "كِتَاب", "root_form": "ك ت ب", "lemma_form": "كِتَاب", "senses": [{"definition": "Book", "definition_language": "en"}]}
from qurankit.lexicon import FileBasedDictionaryAdapter
adapter = FileBasedDictionaryAdapter(
path="data/lexicons/my_dictionary.jsonl",
source="My Dictionary",
format="jsonl"
)
registry.register("my-dict", adapter)
SQLite Format¶
adapter = FileBasedDictionaryAdapter(
path="data/lexicons/my_dictionary.db",
source="My Dictionary",
format="sqlite"
)
SQLite schema:
CREATE TABLE entries (
entry_id TEXT PRIMARY KEY,
headword TEXT NOT NULL,
headword_original TEXT,
root_form TEXT,
lemma_form TEXT,
entry_text_original TEXT,
entry_location TEXT,
metadata_json TEXT
);
CREATE TABLE senses (
sense_id TEXT PRIMARY KEY,
entry_id TEXT REFERENCES entries(entry_id),
definition TEXT NOT NULL,
definition_language TEXT,
grammatical_info TEXT,
semantic_domain TEXT,
examples_json TEXT
);
CREATE INDEX idx_headword ON entries(headword);
CREATE INDEX idx_root ON entries(root_form);
CREATE INDEX idx_lemma ON entries(lemma_form);
Building a Text Provider¶
TextProvider Interface¶
from qurankit.providers import TextProvider
from qurankit.models.text import Surah, Ayah, TextEdition
from typing import Iterator
class MyTextProvider(TextProvider):
"""Provider for custom Qur'an text edition."""
def __init__(self, data_path: str):
self.data_path = data_path
@property
def provider_id(self) -> str:
return "my-text"
@property
def edition_id(self) -> str:
return "my-edition"
def get_edition(self) -> TextEdition:
return TextEdition(
edition_id=self.edition_id,
dataset_id="my-dataset",
name="My Edition",
language="ar",
script="arabic",
orthography="uthmani",
description="Custom text edition"
)
def get_surahs(self) -> Iterator[Surah]:
# Yield all 114 surahs
for surah_data in load_surahs(self.data_path):
yield Surah(**surah_data)
def get_ayahs(self, surah_number: int) -> Iterator[Ayah]:
# Yield ayahs for a surah
for ayah_data in load_ayahs(self.data_path, surah_number):
yield Ayah(**ayah_data)
def get_ayah_text(self, surah: int, ayah: int) -> str:
return load_ayah_text(self.data_path, surah, ayah)
Register with Dataset Registry¶
from qurankit.datasets import DatasetRegistry
registry = DatasetRegistry()
registry.register_provider(MyTextProvider("/path/to/data"))
Building a Morphology Provider¶
MorphologyProvider Interface¶
from qurankit.providers import MorphologyProvider
from qurankit.models.annotations import TokenAnalysis
from typing import Iterator, Optional
class MyMorphologyProvider(MorphologyProvider):
"""Provider for custom morphology annotations."""
def __init__(self, data_path: str):
self.data_path = data_path
@property
def provider_id(self) -> str:
return "my-morphology"
def get_analysis(self, token_id: str) -> Optional[TokenAnalysis]:
return load_analysis(self.data_path, token_id)
def get_analyses_for_ayah(self, surah: int, ayah: int) -> Iterator[TokenAnalysis]:
yield from load_ayah_analyses(self.data_path, surah, ayah)
def get_all_analyses(self) -> Iterator[TokenAnalysis]:
yield from load_all_analyses(self.data_path)
Adapter Registration Patterns¶
1. Entry Point Registration (Recommended)¶
In your package's pyproject.toml:
[project.entry-points."qurankit.adapters"]
my_dictionary = "my_package.adapters:MyDictionaryAdapter"
my_text = "my_package.providers:MyTextProvider"
my_morphology = "my_package.providers:MyMorphologyProvider"
Auto-discovery:
from qurankit.lexicon import auto_register_adapters
auto_register_adapters() # Loads from entry points
2. Manual Registration¶
from qurankit.lexicon import DictionaryAdapterRegistry, get_lexicon_registry
# Global registry (used by Quran.vocabulary)
registry = get_lexicon_registry()
registry.register("my-dict", MyDictionaryAdapter("/path/to/data"))
# Or create local registry
local_registry = DictionaryAdapterRegistry()
local_registry.register("my-dict", MyDictionaryAdapter("/path/to/data"))
vocab = QuranicVocabulary(adapter_registry=local_registry)
3. Configuration-Based¶
# config.toml
[lexicon.adapters]
my-dict = { class = "my_package.adapters:MyDictionaryAdapter", path = "/data/dict.jsonl" }
from qurankit.config import load_adapters_from_config
adapters = load_adapters_from_config("config.toml")
Provenance Requirements¶
Every adapter must provide:
class MyAdapter(DictionaryAdapter):
@property
def source_id(self) -> str:
return "my-dictionary-source"
@property
def license(self) -> str:
return "CC-BY-4.0"
@property
def license_url(self) -> str:
return "https://creativecommons.org/licenses/by/4.0/"
@property
def redistribution_status(self) -> str:
return "allowed" # or "restricted", "unknown"
@property
def version(self) -> str:
return "1.0.0"
@property
def retrieved_date(self) -> str:
return "2024-01-15"
Testing Adapters¶
# tests/test_my_adapter.py
import pytest
from my_package.adapters import MyDictionaryAdapter
class TestMyDictionaryAdapter:
@pytest.fixture
def adapter(self):
adapter = MyDictionaryAdapter("tests/fixtures/sample_dict.jsonl")
adapter.load()
return adapter
def test_lookup_headword(self, adapter):
entries = adapter.lookup_headword("رَحْمَة")
assert len(entries) > 0
assert entries[0].headword == "رَحْمَة"
assert entries[0].root_form == "ر ح م"
def test_lookup_root(self, adapter):
entries = adapter.lookup_root("ر ح م")
assert len(entries) >= 3 # الرحمن، الرحيم، رحمة، etc.
def test_provenance(self, adapter):
assert adapter.license == "CC-BY-4.0"
assert adapter.redistribution_status == "allowed"
Publishing Adapters¶
As Separate Package¶
my-qurankit-dictionary/
├── pyproject.toml
├── src/
│ └── my_qurankit_dictionary/
│ ├── __init__.py
│ └── adapters.py
├── tests/
└── README.md
pyproject.toml:
[project]
name = "my-qurankit-dictionary"
version = "0.1.0"
dependencies = ["qurankit-core"]
[project.entry-points."qurankit.adapters"]
my_dictionary = "my_qurankit_dictionary.adapters:MyDictionaryAdapter"
[project.optional-dependencies]
dev = ["pytest", "ruff"]
Installation¶
Auto-registration on import:
import my_qurankit_dictionary # Registers adapter automatically
from qurankit import Quran
quran = Quran.load()
# Adapter now available in vocabulary
Planned Adapter Interfaces (v0.3.0+)¶
TafsirAdapter¶
class TafsirAdapter(Protocol):
def get_tafsir(self, surah: int, ayah: int, tafsir_id: str) -> TafsirEntry: ...
def list_tafsir_sources(self) -> list[TafsirSource]: ...
def search_tafsir(self, query: str, tafsir_id: str) -> list[TafsirResult]: ...
HadithAdapter¶
class HadithAdapter(Protocol):
def get_hadith(self, collection: str, book: str, number: int) -> Hadith: ...
def search_hadith(self, query: str, collections: list[str]) -> list[HadithResult]: ...
def get_isnad(self, hadith_id: str) -> IsnadChain: ...
QiraatAdapter¶
class QiraatAdapter(Protocol):
def get_reading(self, surah: int, ayah: int, qiraat: str) -> QiraatReading: ...
def list_qiraat(self) -> list[QiraatInfo]: ...
def compare_readings(self, surah: int, ayah: int) -> ReadingComparison: ...