qurankit 0.4.0__tar.gz

qurankit-0.4.0/PKG-INFO

@@ -0,0 +1,354 @@
+Metadata-Version: 2.4
+Name: qurankit
+Version: 0.4.0
+Summary: A query-first Python toolkit for Quranic text, morphology, translations, tafsir, and pattern discovery.
+Author-email: Faisal Alshargi <alshargi.de@gmail.com>
+License: MIT
+Project-URL: Homepage, https://sanaa.ai
+Project-URL: Repository, https://github.com/alshargi/qurankit
+Project-URL: Documentation, https://sanaa.ai/qurankit
+Keywords: quran,arabic,nlp,morphology,roots,lemmas,translations,islamic-studies
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# QuranKit
+
+**QuranKit** is a query-first Python toolkit for computational Quran analysis, providing structured access to Quranic text, morphology, roots, lemmas, translations, tafsir, and linguistic pattern discovery.
+
+Developed by **Dr. Faisal Alshargi**.
+
+---
+
+## Features
+
+* Quranic verse retrieval
+* Root-based search
+* Lemma-based search
+* Word-level linguistic analysis
+* POS tagging access
+* Morphological feature access
+* Multi-language translations
+* Tafsir retrieval
+* Root-order pattern discovery
+* Frequency analysis
+* Research-oriented querying
+* Memory-only dataset loading
+
+---
+
+## Design Philosophy
+
+QuranKit is designed around **feature-level access rather than dataset export**.
+
+Users interact with the Quran through focused search and analysis functions instead of downloading or manipulating the complete dataset.
+
+### Core Principles
+
+* Returns only the requested information
+* Compact results by default
+* No API key required
+* No remote inference
+* Query-first architecture
+* Memory-only dataset loading
+* Translation and tafsir access only when explicitly requested
+
+QuranKit intentionally does **not** provide:
+
+```python
+q.to_dataframe()
+q.export_json()
+q.export_dataset()
+q.dump_all()
+```
+
+This keeps the package focused on analysis, exploration, and research rather than dataset replication.
+
+---
+
+## Installation
+
+```bash
+pip install qurankit
+```
+
+For development:
+
+```bash
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+```python
+from qurankit import QuranKit
+
+q = QuranKit()
+
+print(q.stats())
+
+ayah = q.get_ayah(1, 1)
+print(ayah)
+
+results = q.search_root("رحم", limit=3)
+
+translation = q.get_translation(2, 255, lang="en")
+print(translation["translation"])
+```
+
+---
+
+## Statistics
+
+```python
+q.stats()
+```
+
+Example:
+
+```python
+{
+    "surahs": 114,
+    "ayahs": 6236,
+    "languages": 20,
+    "roots": 1600,
+    "lemmas": 14000
+}
+```
+
+---
+
+## Verse Retrieval
+
+```python
+q.get_ayah(1, 1)
+```
+
+Example output:
+
+```python
+{
+    "sura": 1,
+    "ayah": 1,
+    "sura_ar": "الفاتحة",
+    "sura_en": "Al-Fātiḥah",
+    "ayatext_nt": "بسم الله الرحمن الرحيم"
+}
+```
+
+---
+
+## Linguistic Features
+
+Retrieve individual linguistic layers without loading unnecessary information.
+
+```python
+q.get_words(2, 255)
+
+q.get_roots(2, 255)
+
+q.get_lemmas(2, 255)
+
+q.get_pos(2, 255)
+
+q.get_morph_tags(2, 255)
+
+q.get_analysis(2, 255)
+
+q.word_analysis(2, 255)
+```
+
+---
+
+## Search
+
+### Search Text
+
+```python
+q.search_text("الله", limit=5)
+```
+
+### Search Word
+
+```python
+q.search_word("جنة", limit=5)
+```
+
+### Search Root
+
+```python
+q.search_root("رحم", limit=5)
+```
+
+### Search Lemma
+
+```python
+q.search_lemma("ٱللَّه", limit=5)
+```
+
+### Search POS Tags
+
+```python
+q.search_pos("V", limit=5)
+```
+
+Search results remain compact and exclude long translations and tafsir content.
+
+---
+
+## Translations
+
+List available languages:
+
+```python
+q.available_languages()
+```
+
+Retrieve a specific translation:
+
+```python
+q.get_translation(2, 255, lang="en")
+```
+
+Retrieve multiple translations:
+
+```python
+q.get_translations(
+    1,
+    1,
+    langs=["en", "tr", "de"]
+)
+```
+
+Search inside translations:
+
+```python
+q.search_translation(
+    "mercy",
+    lang="en",
+    limit=5
+)
+```
+
+---
+
+## Tafsir
+
+Retrieve tafsir only when requested.
+
+### Al-Muyassar
+
+```python
+q.get_tafsir(
+    1,
+    1,
+    source="muyassar"
+)
+```
+
+### Al-Jalalayn
+
+```python
+q.get_tafsir(
+    1,
+    1,
+    source="jalalayn"
+)
+```
+
+---
+
+## Pattern Discovery
+
+Repeated root-order patterns:
+
+```python
+q.find_repeated_root_orders(
+    min_occurrences=2,
+    limit=10
+)
+```
+
+Root frequency statistics:
+
+```python
+q.root_frequency(limit=20)
+```
+
+---
+
+## Random Verse
+
+```python
+q.random_ayah()
+```
+
+---
+
+## Dataset Handling
+
+QuranKit ships with a minimal bundled sample dataset for testing and fallback purposes.
+
+The complete Quran dataset is loaded from the internal default dataset source into memory only.
+
+QuranKit does not intentionally persist the full dataset to local storage and does not provide dataset export utilities.
+
+---
+
+## Performance
+
+```python
+import time
+
+start = time.time()
+
+q = QuranKit()
+
+print(
+    "Load time:",
+    round(time.time() - start, 2),
+    "seconds"
+)
+```
+
+---
+
+## Example Research Workflow
+
+```python
+from qurankit import QuranKit
+
+q = QuranKit()
+
+verses = q.search_root("رحم", limit=10)
+
+for verse in verses:
+    print(
+        verse["sura"],
+        verse["ayah"],
+        verse["ayatext_nt"]
+    )
+```
+
+---
+
+## Disclaimer
+
+QuranKit is intended for computational analysis, research, education, and software development.
+
+It is not a source of religious rulings, legal opinions, or authoritative tafsir.
+
+```
+```
+

qurankit-0.4.0/README.md

@@ -0,0 +1,331 @@
+# QuranKit
+
+**QuranKit** is a query-first Python toolkit for computational Quran analysis, providing structured access to Quranic text, morphology, roots, lemmas, translations, tafsir, and linguistic pattern discovery.
+
+Developed by **Dr. Faisal Alshargi**.
+
+---
+
+## Features
+
+* Quranic verse retrieval
+* Root-based search
+* Lemma-based search
+* Word-level linguistic analysis
+* POS tagging access
+* Morphological feature access
+* Multi-language translations
+* Tafsir retrieval
+* Root-order pattern discovery
+* Frequency analysis
+* Research-oriented querying
+* Memory-only dataset loading
+
+---
+
+## Design Philosophy
+
+QuranKit is designed around **feature-level access rather than dataset export**.
+
+Users interact with the Quran through focused search and analysis functions instead of downloading or manipulating the complete dataset.
+
+### Core Principles
+
+* Returns only the requested information
+* Compact results by default
+* No API key required
+* No remote inference
+* Query-first architecture
+* Memory-only dataset loading
+* Translation and tafsir access only when explicitly requested
+
+QuranKit intentionally does **not** provide:
+
+```python
+q.to_dataframe()
+q.export_json()
+q.export_dataset()
+q.dump_all()
+```
+
+This keeps the package focused on analysis, exploration, and research rather than dataset replication.
+
+---
+
+## Installation
+
+```bash
+pip install qurankit
+```
+
+For development:
+
+```bash
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+```python
+from qurankit import QuranKit
+
+q = QuranKit()
+
+print(q.stats())
+
+ayah = q.get_ayah(1, 1)
+print(ayah)
+
+results = q.search_root("رحم", limit=3)
+
+translation = q.get_translation(2, 255, lang="en")
+print(translation["translation"])
+```
+
+---
+
+## Statistics
+
+```python
+q.stats()
+```
+
+Example:
+
+```python
+{
+    "surahs": 114,
+    "ayahs": 6236,
+    "languages": 20,
+    "roots": 1600,
+    "lemmas": 14000
+}
+```
+
+---
+
+## Verse Retrieval
+
+```python
+q.get_ayah(1, 1)
+```
+
+Example output:
+
+```python
+{
+    "sura": 1,
+    "ayah": 1,
+    "sura_ar": "الفاتحة",
+    "sura_en": "Al-Fātiḥah",
+    "ayatext_nt": "بسم الله الرحمن الرحيم"
+}
+```
+
+---
+
+## Linguistic Features
+
+Retrieve individual linguistic layers without loading unnecessary information.
+
+```python
+q.get_words(2, 255)
+
+q.get_roots(2, 255)
+
+q.get_lemmas(2, 255)
+
+q.get_pos(2, 255)
+
+q.get_morph_tags(2, 255)
+
+q.get_analysis(2, 255)
+
+q.word_analysis(2, 255)
+```
+
+---
+
+## Search
+
+### Search Text
+
+```python
+q.search_text("الله", limit=5)
+```
+
+### Search Word
+
+```python
+q.search_word("جنة", limit=5)
+```
+
+### Search Root
+
+```python
+q.search_root("رحم", limit=5)
+```
+
+### Search Lemma
+
+```python
+q.search_lemma("ٱللَّه", limit=5)
+```
+
+### Search POS Tags
+
+```python
+q.search_pos("V", limit=5)
+```
+
+Search results remain compact and exclude long translations and tafsir content.
+
+---
+
+## Translations
+
+List available languages:
+
+```python
+q.available_languages()
+```
+
+Retrieve a specific translation:
+
+```python
+q.get_translation(2, 255, lang="en")
+```
+
+Retrieve multiple translations:
+
+```python
+q.get_translations(
+    1,
+    1,
+    langs=["en", "tr", "de"]
+)
+```
+
+Search inside translations:
+
+```python
+q.search_translation(
+    "mercy",
+    lang="en",
+    limit=5
+)
+```
+
+---
+
+## Tafsir
+
+Retrieve tafsir only when requested.
+
+### Al-Muyassar
+
+```python
+q.get_tafsir(
+    1,
+    1,
+    source="muyassar"
+)
+```
+
+### Al-Jalalayn
+
+```python
+q.get_tafsir(
+    1,
+    1,
+    source="jalalayn"
+)
+```
+
+---
+
+## Pattern Discovery
+
+Repeated root-order patterns:
+
+```python
+q.find_repeated_root_orders(
+    min_occurrences=2,
+    limit=10
+)
+```
+
+Root frequency statistics:
+
+```python
+q.root_frequency(limit=20)
+```
+
+---
+
+## Random Verse
+
+```python
+q.random_ayah()
+```
+
+---
+
+## Dataset Handling
+
+QuranKit ships with a minimal bundled sample dataset for testing and fallback purposes.
+
+The complete Quran dataset is loaded from the internal default dataset source into memory only.
+
+QuranKit does not intentionally persist the full dataset to local storage and does not provide dataset export utilities.
+
+---
+
+## Performance
+
+```python
+import time
+
+start = time.time()
+
+q = QuranKit()
+
+print(
+    "Load time:",
+    round(time.time() - start, 2),
+    "seconds"
+)
+```
+
+---
+
+## Example Research Workflow
+
+```python
+from qurankit import QuranKit
+
+q = QuranKit()
+
+verses = q.search_root("رحم", limit=10)
+
+for verse in verses:
+    print(
+        verse["sura"],
+        verse["ayah"],
+        verse["ayatext_nt"]
+    )
+```
+
+---
+
+## Disclaimer
+
+QuranKit is intended for computational analysis, research, education, and software development.
+
+It is not a source of religious rulings, legal opinions, or authoritative tafsir.
+
+```
+```
+

qurankit-0.4.0/examples/quickstart.py

@@ -0,0 +1,10 @@
+from qurankit import QuranKit
+
+q = QuranKit()
+
+print(q.stats())
+print(q.get_ayah(1, 1))
+print(q.get_roots(1, 1))
+print(q.search_root("رحم", limit=3))
+print(q.get_translation(2, 255, lang="en"))
+print(q.word_analysis(1, 1))