quran-processing-toolkit 0.4.0__py3-none-any.whl

quran_processing_toolkit/translations.py

@@ -0,0 +1,313 @@
+"""Explicit, hash-verified translation downloads and user-installed text layers.
+
+Nothing is downloaded at import or ordinary corpus load. Translations are never
+bundled in either distribution or written into the installed data directory.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+import warnings
+from collections.abc import Iterable, Mapping
+from contextlib import suppress
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any
+from urllib.error import URLError
+from urllib.parse import urlsplit
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+from .chapter_names import CHAPTERS
+from .source_data import DataError, default_cache_directory
+from .text import TranslationNotAvailableError
+
+Address = tuple[int, int]
+_MAX_BYTES = 8 * 1024 * 1024
+
+
+class TranslationDownloadError(DataError):
+    """An explicit translation download or offline-cache lookup failed."""
+
+
+class TranslationIntegrityError(DataError):
+    """Downloaded or cached translation bytes differ from the pinned source hash."""
+
+
+class TranslationLicenseWarning(UserWarning):
+    """A translation download has third-party usage terms distinct from the code."""
+
+
+class _HTTPSOnlyRedirect(HTTPRedirectHandler):
+    """Reject a transport downgrade before urllib sends the redirected request."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        if urlsplit(newurl).scheme.lower() != "https":
+            raise TranslationDownloadError("Refusing a non-HTTPS translation redirect")
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+def _open_translation(request: Request, *, timeout: float):
+    return build_opener(_HTTPSOnlyRedirect()).open(request, timeout=timeout)
+
+
+@dataclass(frozen=True)
+class TranslationSource:
+    """One curated external translation, including a reproducible content pin."""
+
+    identifier: str
+    name: str
+    translator: str
+    language: str
+    url: str
+    sha256: str
+    terms_url: str
+    terms: str
+
+
+_SOURCES = (
+    TranslationSource(
+        "en.qarai",
+        "Qarai",
+        "Ali Quli Qarai",
+        "English",
+        "https://tanzil.net/trans/en.qarai",
+        "1207b98ee7ae47891b4dd01b608416da2278820acf54cdaf3943d0a6f9823fdf",
+        "https://tanzil.net/trans/",
+        "Tanzil provides translations for non-commercial purposes only; other use "
+        "requires permission from the translator or publisher. Check the source terms "
+        "before use or redistribution. The Python code's Apache license does not apply.",
+    ),
+)
+
+
+def translation_sources() -> tuple[TranslationSource, ...]:
+    """List the curated download catalog without contacting the network."""
+    return _SOURCES
+
+
+@dataclass(frozen=True)
+class TranslationCoverage:
+    """Coverage of a requested set of verse addresses by a translation layer."""
+
+    total: int
+    translated: int
+    missing: tuple[Address, ...]
+
+    @property
+    def complete(self) -> bool:
+        """Return whether every requested verse has nonempty translation text."""
+        return not self.missing
+
+    @property
+    def fraction(self) -> float:
+        """Return translated/total, treating an empty requested set as complete."""
+        return self.translated / self.total if self.total else 1.0
+
+
+@dataclass(frozen=True)
+class Translation:
+    """An immutable user-installed translation with text and source metadata.
+
+    Use load_translation() or download_translation() rather than constructing it
+    directly. Texts retain their supplied content, including embedded newlines.
+    """
+
+    path: Path
+    texts: Mapping[Address, str]
+    metadata: Mapping[str, str]
+    fingerprint: str = field(init=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "path", self.path.expanduser().resolve())
+        object.__setattr__(self, "texts", MappingProxyType(dict(self.texts)))
+        object.__setattr__(self, "metadata", MappingProxyType(dict(self.metadata)))
+        identity = json.dumps(
+            (sorted(self.texts.items()), sorted(self.metadata.items())), ensure_ascii=False
+        ).encode("utf-8")
+        object.__setattr__(self, "fingerprint", hashlib.sha256(identity).hexdigest())
+
+    def coverage(self, addresses: Iterable[Address] | None = None) -> TranslationCoverage:
+        """Check all 6,236 canonical verses, or a caller-supplied address subset."""
+        expected = set(addresses) if addresses is not None else _canonical_addresses()
+        missing = tuple(sorted(expected - self.texts.keys()))
+        return TranslationCoverage(len(expected), len(expected) - len(missing), missing)
+
+    def require_complete(self, addresses: Iterable[Address] | None = None) -> None:
+        """Raise TranslationNotAvailableError when any requested verse is missing."""
+        coverage = self.coverage(addresses)
+        if coverage.missing:
+            sample = ", ".join(f"{c}:{v}" for c, v in coverage.missing[:8])
+            raise TranslationNotAvailableError(
+                f"Translation missing for {len(coverage.missing)} verses: {sample}"
+            )
+
+
+def _canonical_addresses() -> set[Address]:
+    return {(c, v) for c, row in enumerate(CHAPTERS, 1) for v in range(1, row[3] + 1)}
+
+
+def _parse(payload: bytes, *, json_format: bool) -> dict[Address, str]:
+    text = payload.decode("utf-8-sig")
+    rows: list[tuple[Any, Any, Any]] = []
+    if json_format:
+        data = json.loads(text)
+        for surah in data["surahs"]:
+            for verse in surah["verses"]:
+                rows.append((surah["number"], verse["number"], verse["text"]))
+    else:
+        for number, line in enumerate(text.splitlines(), 1):
+            if not line.strip() or line.startswith("#"):
+                continue
+            fields = line.split("|", 2)
+            if len(fields) != 3:
+                raise ValueError(
+                    f"Malformed translation line {number}: expected chapter|verse|text"
+                )
+            rows.append((fields[0], fields[1], fields[2]))
+    canonical = _canonical_addresses()
+    result = {}
+    for chapter, verse_number, value in rows:
+        # Reject lossy conversions such as JSON floats or boolean verse numbers.
+        if isinstance(chapter, bool) or isinstance(verse_number, bool):
+            raise ValueError("Translation addresses must be integer verse numbers")
+        if not str(chapter).isdigit() or not str(verse_number).isdigit():
+            raise ValueError("Translation addresses must be integer verse numbers")
+        address = int(chapter), int(verse_number)
+        if address not in canonical:
+            raise ValueError(f"Invalid translation address {address[0]}:{address[1]}")
+        if address in result:
+            raise ValueError(f"Duplicate translation verse {address[0]}:{address[1]}")
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError(f"Empty translation at {address[0]}:{address[1]}")
+        result[address] = value
+    if not result:
+        raise ValueError("Translation contains no verse records")
+    return result
+
+
+def load_translation(
+    path: str | os.PathLike[str],
+    *,
+    name: str | None = None,
+    translator: str | None = None,
+    language: str | None = None,
+) -> Translation:
+    """Load numbered UTF-8 text or structured surahs/verses JSON without a network call.
+
+    Local files may be partial. Metadata supplied by the caller is descriptive,
+    not a certification of authorship. The SHA-256 identifies the exact file bytes.
+    """
+    path = Path(path).expanduser().resolve()
+    payload = path.read_bytes()
+    metadata = {"path": str(path), "sha256": hashlib.sha256(payload).hexdigest()}
+    metadata.update(
+        {
+            k: v
+            for k, v in (("name", name), ("translator", translator), ("language", language))
+            if v is not None
+        }
+    )
+    return Translation(path, _parse(payload, json_format=path.suffix.lower() == ".json"), metadata)
+
+
+def _atomic_write(path: Path, payload: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary = tempfile.mkstemp(prefix=path.name + ".", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "wb") as output:
+            output.write(payload)
+        os.replace(temporary, path)
+    finally:
+        with suppress(FileNotFoundError):
+            os.unlink(temporary)
+
+
+def download_translation(
+    identifier: str = "en.qarai",
+    *,
+    cache_dir: str | os.PathLike[str] | None = None,
+    offline: bool = False,
+    refresh: bool = False,
+    timeout: float = 30.0,
+) -> Translation:
+    """Explicitly download a curated translation, verify its pin, and cache verbatim bytes.
+
+    The default cache is the toolkit user cache's translations/ subdirectory, never
+    either installed package. A verified cached copy is reused without networking.
+    offline=True forbids networking; refresh=True deliberately re-fetches the SAME
+    pinned revision, not an unreviewed upstream update. Unknown IDs fail locally.
+    Third-party usage terms are retained in metadata and warned about before fetching.
+    """
+    identifier = {"qarai": "en.qarai"}.get(identifier.lower(), identifier.lower())
+    source = next((s for s in _SOURCES if s.identifier == identifier), None)
+    if source is None:
+        raise ValueError(f"Unknown translation {identifier!r}; see translation_sources()")
+    if offline and refresh:
+        raise ValueError("offline=True and refresh=True cannot be combined")
+    if timeout <= 0:
+        raise ValueError("timeout must be positive")
+    directory = (
+        Path(cache_dir).expanduser().resolve()
+        if cache_dir
+        else default_cache_directory() / "translations"
+    )
+    path = directory / f"{source.identifier}-{source.sha256}.txt"
+    manifest_path = path.with_suffix(".metadata.json")
+    downloaded_at = ""
+    if path.exists() and not refresh:
+        payload = path.read_bytes()
+        if manifest_path.exists():
+            with suppress(ValueError, OSError, TypeError, AttributeError):
+                downloaded_at = str(
+                    json.loads(manifest_path.read_text(encoding="utf-8")).get("downloaded_at", "")
+                )
+    elif offline:
+        raise TranslationDownloadError(f"No offline cached translation at {path}")
+    else:
+        warnings.warn(
+            f"{source.translator}: {source.terms} {source.terms_url}",
+            TranslationLicenseWarning,
+            stacklevel=2,
+        )
+        request = Request(source.url, headers={"User-Agent": "quran-processing-toolkit"})
+        try:
+            with _open_translation(request, timeout=timeout) as response:
+                if not response.geturl().startswith("https://"):
+                    raise TranslationDownloadError("Refusing a non-HTTPS translation redirect")
+                payload = response.read(_MAX_BYTES + 1)
+        except (URLError, OSError) as error:
+            raise TranslationDownloadError(f"Could not download {source.url}: {error}") from error
+        downloaded_at = datetime.now(timezone.utc).isoformat()
+    if len(payload) > _MAX_BYTES:
+        raise TranslationDownloadError("Translation exceeds the 8 MiB size limit")
+    digest = hashlib.sha256(payload).hexdigest()
+    if digest != source.sha256:
+        raise TranslationIntegrityError(
+            f"Translation SHA-256 mismatch for {source.identifier}: {digest} != {source.sha256}. "
+            "An upstream change requires a reviewed catalog update; cached corruption can "
+            "be repaired with refresh=True."
+        )
+    texts = _parse(payload, json_format=False)
+    if texts.keys() != _canonical_addresses():
+        raise TranslationIntegrityError("Curated translation does not cover all 6,236 verses")
+    metadata = {
+        "identifier": source.identifier,
+        "name": source.name,
+        "translator": source.translator,
+        "language": source.language,
+        "source_url": source.url,
+        "terms_url": source.terms_url,
+        "terms": source.terms,
+        "sha256": digest,
+        "downloaded_at": downloaded_at,
+        "path": str(path),
+    }
+    if not path.exists() or refresh:
+        _atomic_write(path, payload)
+        _atomic_write(manifest_path, json.dumps(metadata, ensure_ascii=False, indent=2).encode())
+    return Translation(path, texts, metadata)

quran_processing_toolkit/validation.py

@@ -0,0 +1,73 @@
+"""Structural, provenance, and semantic validation of installed source data."""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+
+from .build import SUPPORTED_DERIVED_DIGESTS, load_source_records, rebuild_records, records_digest
+from .corpus import QuranCorpus
+from .source_data import DataError, default_data_directory, verify_data_directory
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationIssue:
+    """One machine-readable validation finding and human-readable explanation."""
+
+    severity: str
+    code: str
+    message: str
+
+
+def validate_corpus(data_dir: Path | None = None) -> tuple[ValidationIssue, ...]:
+    """Return every structural or semantic validation issue for a data directory."""
+    issues: list[ValidationIssue] = []
+    path = data_dir or default_data_directory()
+    try:
+        manifest = verify_data_directory(path)
+        corpus = QuranCorpus(path)
+    except DataError as error:
+        return (ValidationIssue("error", "source-data", str(error)),)
+
+    expected_counts = {"chapters": 114, "verses": 6236, "words": 77429, "tokens": 128219}
+    for field, expected in expected_counts.items():
+        actual = len(getattr(corpus, field))
+        if actual != expected:
+            issues.append(
+                ValidationIssue(
+                    "error", "unexpected-count", f"{field}: {actual}, expected {expected}"
+                )
+            )
+    if len(corpus.juzs) != 30 or sum(len(juz) for juz in corpus.juzs) != len(corpus.verses):
+        issues.append(
+            ValidationIssue(
+                "error", "juz-coverage", "Juz boundaries do not cover 30 complete parts"
+            )
+        )
+
+    source = manifest["sources"]["morphology"]
+    records = rebuild_records(load_source_records(path / source["filename"]))
+    digest = records_digest(records)
+    expected_digest = SUPPORTED_DERIVED_DIGESTS.get(source["sha256"])
+    if digest != expected_digest:
+        issues.append(
+            ValidationIssue(
+                "error",
+                "derived-digest",
+                f"derived morphology SHA-256 is {digest}, expected {expected_digest}",
+            )
+        )
+
+    aspects = Counter(record.get("ASPECT") for record in records if record.get("POS") == "V")
+    expected_aspects = Counter(PERFECT=9150, IMPERFECT=8330, IMPERATIVE=1876)
+    if aspects != expected_aspects:
+        issues.append(ValidationIssue("error", "verb-aspects", f"verb aspects differ: {aspects}"))
+    passive = sum(
+        record.get("VOICE") == "PASSIVE" for record in records if record.get("POS") == "V"
+    )
+    if passive != 1140:
+        issues.append(
+            ValidationIssue("error", "passive-verbs", f"passive finite verbs: {passive} != 1140")
+        )
+    return tuple(issues)

quran_processing_toolkit-0.4.0.dist-info/METADATA

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: quran-processing-toolkit
+Version: 0.4.0
+Summary: Natural, queryable access to Quranic text and morphology
+Author: Maysum Panju
+License-Expression: Apache-2.0 AND LicenseRef-Tanzil-Metadata-CC-BY
+Project-URL: Homepage, https://github.com/mhpanju/QuranProcessingToolkit
+Project-URL: Documentation, https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/README.md
+Project-URL: Repository, https://github.com/mhpanju/QuranProcessingToolkit
+Project-URL: Issues, https://github.com/mhpanju/QuranProcessingToolkit/issues
+Project-URL: Changelog, https://github.com/mhpanju/QuranProcessingToolkit/blob/master/CHANGELOG.md
+Keywords: quran,arabic,corpus,morphology,linguistics,buckwalter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: licenses/TANZIL-METADATA-NOTICE.txt
+Provides-Extra: fast
+Requires-Dist: orjson>=3.10; extra == "fast"
+Provides-Extra: data
+Requires-Dist: quran-processing-toolkit-qac-data==0.4.0; extra == "data"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.17; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.12; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# Quran Processing Toolkit
+
+Typed Python access to Quranic text, morphology, and composable research queries.
+Search in Arabic or ASCII Buckwalter, inspect every original annotation, and address
+chapters, verses, words, and tokens using Quranic 1-based indexes.
+
+Requires **Python 3.10+**. Version **0.4.0** is the first production PyPI release;
+the API is early-stage and future minor releases may introduce documented changes.
+
+## Install and run
+
+```bash
+python -m pip install "quran-processing-toolkit[data]"
+```
+
+```python
+from quran_processing_toolkit import load_quran
+
+quran = load_quran()
+assert len(quran.chapters) == 114
+assert len(quran.verses) == 6236
+
+print(quran.chapter(2).name)  # al-Baqarah
+print(quran.verse(2, 255).get_arabic())
+
+# ASCII search input is Buckwalter, so an Arabic keyboard is optional.
+quran.search("muwsaY").show("arabic", limit=3)
+
+# These are verb tokens: all filters apply to the same morphological stem.
+present = quran.verbs().with_tense("present")
+print(present.most_common_forms(limit=5))
+
+quran.verses.ends_with("n", strip_diacritics=True).show("arabic", limit=3)
+```
+
+Loading is offline and verifies the installed source data. Nothing is downloaded
+implicitly. The core has no mandatory third-party Python dependencies. Code and data
+are separate distributions because their licenses differ; the `data` extra installs
+the matching source-data package. For optional faster cache decoding, install
+`"quran-processing-toolkit[data,fast]"`.
+
+## What you can do
+
+| Task | API | Guide |
+|---|---|---|
+| Look up an address | `quran.verse(2, 255)` | [Getting started](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/GETTING_STARTED.md) |
+| Search Arabic or Buckwalter | `quran.search("muwsaY")` | [Query cookbook](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/QUERY_COOKBOOK.md) |
+| Filter stems by root, form, tense, voice, person, or number | `quran.verbs().with_root("qwl")` | [Morphology](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/MORPHOLOGY.md) |
+| Select nouns, pronouns, particles, and other parts of speech | `quran.nouns()`, `quran.pronouns()` | [API reference](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/API_REFERENCE.md) |
+| Count, group, and export results | `results.count_by("root")`, `results.select("address")` | [Cookbook](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/QUERY_COOKBOOK.md) |
+| Compare two verses for one-word edits | `compare_verses(a, b)` | [Comparison API](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/API_REFERENCE.md#chapter-names-and-surface-word-comparison) |
+| Add a local translation or explicitly download one | `load_translation()`, `download_translation()` | [Translations](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/TRANSLATIONS.md) |
+| Inspect sources and validate the corpus | `quran.provenance()`, `quran-toolkit validate` | [Data provenance](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/DATA_PROVENANCE.md) |
+
+SQL and a database server are not required. Named helpers cover ordinary queries;
+`where()`, `filter()`, `group_by()`, and `count_by()` support custom analyses.
+
+## Addresses, words, and tokens
+
+```python
+chapter = quran.chapters[1]
+verse = quran.verses[2, 255]
+word = quran.words[2, 255, 1]
+token = quran.tokens[2, 255, 1, 1]
+juz = quran.juzs[1]
+
+results = quran.verbs().in_chapter(2)
+first_result = results[0]  # filtered results use ordinary zero-based positions
+```
+
+A **word** is a QAC-aligned orthographic word. A **token** is one morphological
+segment: prefixes, stems, and suffixes can be separate tokens inside a word.
+`quran.verbs()` and `quran.nouns()` return tokens; `quran.verb_words` and
+`quran.noun_words` return whole words. Chained word filters aggregate stem values,
+so use token queries when all conditions must match a single stem.
+
+On a token, `form` is its surface spelling and `verb_form` is its Roman-numeral
+morphological form. The query `with_form("IV")` selects the morphological form.
+Roots and lemmas use case-sensitive Buckwalter; categorical aliases such as
+`"present"`, `"IMPF"`, `"passive"`, and `"PASS"` are accepted by the relevant helpers.
+
+See [Data model and indexing](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/DATA_MODEL.md)
+for multi-stem behavior and the full hierarchy.
+
+## Compose research queries
+
+```python
+# Roots found in first-person plural verbs but never first-person singular verbs.
+plural = quran.verbs().with_person(1).with_number("plural")
+singular = quran.verbs().with_person(1).with_number("singular")
+plural_only_roots = plural.roots() - singular.roots()
+
+# Three-letter noun roots with at least two weak letters.
+weak_roots = quran.nouns().with_root_length(3).with_minimum_root_letter_count("Awy", 2)
+
+# Explicit nun-of-emphasis annotations associated with their verb stem.
+emphatic = quran.verbs().with_nun_of_emphasis()
+assert len(emphatic) == 243
+
+# The longest within-verse word run containing neither mim nor nun.
+longest = quran.longest_word_sequence_without_letters("mn", strip_diacritics=True)
+
+# Preserve access to every original annotation.
+token = quran.token(2, 38, 6, 1)
+print(token.source_feature_text)
+print(token.source_features)
+```
+
+Text matching is literal by default. ASCII input selects Buckwalter; non-ASCII
+input selects Arabic. Pass normalization options explicitly, for example
+`strip_diacritics=True`, `strip_quranic_marks=True`, or `normalize_alif=True`.
+Use `representation="translation"` for translation search so English input is
+not interpreted as Buckwalter.
+
+## Translations and verse comparison
+
+Translations are optional. Load your own UTF-8 `chapter|verse|text` file or supported
+JSON file:
+
+```python
+translated = load_quran(translation="/path/to/translation.txt")
+print(translated.verse(1, 1).get_translation())
+```
+
+An explicit, hash-verified downloader is also available:
+
+```python
+from quran_processing_toolkit import compare_verses, download_translation
+
+# This call opts into a network download on first use.
+translated = load_quran(translation=download_translation("en.qarai"))
+translated.require_translation()  # require coverage of all 6,236 verses
+
+changes = compare_verses(
+    quran.verse(27, 68),
+    quran.verse(23, 83),
+    ignore_pause_marks=True,
+)
+for change in changes:
+    print(change.kind, change.verse_a.address, change.verse_b.address)
+```
+
+The catalog currently contains Ali Quli Qarai's English translation from Tanzil.
+Its terms specify non-commercial use unless permission is obtained from the
+translator or publisher. Downloads are cached outside the package and support
+`offline=True`. Missing translation output raises `TranslationNotAvailableError`.
+See [Translations](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/TRANSLATIONS.md)
+for terms, formats, coverage checks, and provenance.
+
+`compare_verses()` explains a single-word addition, substitution, or shift between
+two verses. It returns zero or one match, rather than a general similarity score.
+Its space-delimited surface positions differ from QAC word addresses; it performs
+no spelling or vowel normalization.
+
+## Command line
+
+```bash
+quran-toolkit stats
+quran-toolkit search muwsaY --level verse --limit 5
+quran-toolkit word 2:255:1
+quran-toolkit sources
+quran-toolkit validate
+quran-rebuild --check
+```
+
+The [CLI reference](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/CLI.md)
+explains all commands, options, and exit behavior.
+
+## Integrity and caching
+
+Every newly constructed corpus verifies source filenames, sizes, and SHA-256 hashes,
+plus the canonical derived morphology digest. Later equivalent `load_quran()` calls
+reuse the same in-process object. A local derived JSON cache speeds up new processes;
+installed source files are never changed.
+
+```python
+fresh = load_quran(cache=False)  # a new object graph
+uncached = load_quran(cache=False, disk_cache=False)  # rederive from source
+```
+
+Set `QURAN_PROCESSING_TOOLKIT_CACHE` or pass `cache_dir=...` to relocate the derived
+cache. Read-only cache locations fall back to uncached loading. See
+[Architecture](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/ARCHITECTURE.md).
+
+## Documentation for people and AI assistants
+
+Start at the [documentation index](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/README.md).
+The [AI usage guide](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/AI_GUIDE.md)
+provides a compact, executable introduction, task-to-API mapping, and common mistakes.
+[`llms.txt`](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/llms.txt)
+links to the authoritative Markdown references.
+
+- [Getting started](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/GETTING_STARTED.md)
+- [Query cookbook](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/QUERY_COOKBOOK.md)
+- [API reference](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/API_REFERENCE.md)
+- [Morphology reference](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/MORPHOLOGY.md)
+- [Release notes and preview migration](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/CHANGELOG.md)
+- [Runnable examples](https://github.com/mhpanju/QuranProcessingToolkit/tree/master/examples), including a [complete verb JSON exporter](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/examples/export_verb_index.py)
+- [Known limits and roadmap](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/ROADMAP.md)
+- [Contributing](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/CONTRIBUTING.md)
+
+## Development
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e packages/quran_processing_toolkit_qac_data
+python -m pip install -e ".[dev]"
+ruff check .
+ruff format --check .
+mypy quran_processing_toolkit packages/quran_processing_toolkit_qac_data/src
+python -m unittest discover -s tests -v
+python -m quran_processing_toolkit.build --check
+python -m quran_processing_toolkit validate
+```
+
+The historical `from tools import QuranCorpus` import is available in source
+checkouts. Installed applications should import `quran_processing_toolkit`.
+
+## License and attribution
+
+The Python code is Apache-2.0. The core also includes separately attributed Tanzil
+chapter-label metadata, whose upstream declaration is CC-BY without a version;
+see [Third-party notices](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/THIRD_PARTY_NOTICES.md).
+The data package preserves the QAC and Tanzil sources verbatim under their respective
+upstream terms, with full notices. No translation is bundled. Read
+[Data provenance and licensing](https://github.com/mhpanju/QuranProcessingToolkit/blob/master/docs/DATA_PROVENANCE.md)
+before redistributing data or derived artifacts.

quran_processing_toolkit-0.4.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+quran_processing_toolkit/__init__.py,sha256=xWCGLZp8nb_dS1pKsPKIoXmQuSJZ1KO3tKfrpzDqQBs,2139
+quran_processing_toolkit/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+quran_processing_toolkit/build.py,sha256=35NzxpzEgXfW8u8TfysiRtkgradMeRyDJy5JPJXBQPc,8839
+quran_processing_toolkit/chapter_names.py,sha256=K0f5mmzCPOM_tTCnh9PvZ2kBKR7NaSI5LSZfNdAb4dc,7356
+quran_processing_toolkit/cli.py,sha256=B4e-WW5yxaTb3ROjx3dQZv79uixFFK29UUYGkUIJQNI,4198
+quran_processing_toolkit/collections.py,sha256=jlyBY7CXxJIsoBMo3Z4h1PPfppqbQg_DWC6qrDmT1qk,23418
+quran_processing_toolkit/corpus.py,sha256=S3ratqlt2JYyldkAj7ItmKM-in6fiTw0rSj6_lmeGeE,24170
+quran_processing_toolkit/models.py,sha256=c04YDKF1B1GwVs5-uuiei6gzfKTC8w-l9k6zY7H-_88,22669
+quran_processing_toolkit/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+quran_processing_toolkit/similarity.py,sha256=3e6tYjfH1M4c19HSPVesX6y0f8uVV2W14A60JhP8hgM,3535
+quran_processing_toolkit/source_data.py,sha256=mpTDcyzcD0Bd7TM95PuhZqxo0kOc53FBMqWj1_LVP9w,7299
+quran_processing_toolkit/text.py,sha256=mtb9rEeZXUrmPnXHfOBqg-ieWznBh8QYeNeZCuLI1vk,10823
+quran_processing_toolkit/translations.py,sha256=fCQXcZiZD6RZtnj-xXQL_M1BqMrr5CfMIDUFhe3YWM4,12469
+quran_processing_toolkit/validation.py,sha256=F6lp4OGx_a_j8mAfQQGTPbB5jetgMYvRqNprXRTdsrg,2816
+quran_processing_toolkit-0.4.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+quran_processing_toolkit-0.4.0.dist-info/licenses/licenses/TANZIL-METADATA-NOTICE.txt,sha256=7qYNCx9uLVEv17eoYt57qWNYNlnfO-43MEB8umS8eho,730
+quran_processing_toolkit-0.4.0.dist-info/METADATA,sha256=3-O3Byn-kzi9Pa0wJ8QvmEV0-bTyzoGh4wx3_FPjk5M,12818
+quran_processing_toolkit-0.4.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+quran_processing_toolkit-0.4.0.dist-info/entry_points.txt,sha256=vPVscdjPGg4HqIcnshkNhaYaI7e9tQJ9YTZby-aFkrM,120
+quran_processing_toolkit-0.4.0.dist-info/top_level.txt,sha256=RFTOfcqLLatlwvm6UY_UFvcaZnB8-JpY0hlDFwFYWlc,25
+quran_processing_toolkit-0.4.0.dist-info/RECORD,,