Metadata-Version: 2.4
Name: kaeshur-quran
Version: 1.0.0
Summary: Complete Quranic data with Kashmiri translations, tafsirs, and transliterations
Home-page: https://github.com/izan-majeed/kaeshur-quran-data
Author: Izan Majeed
Author-email: Izan Majeed <izanmajeed03@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/izan-majeed/kaeshur-quran-data
Project-URL: Bug Tracker, https://github.com/izan-majeed/kaeshur-quran-data/issues
Project-URL: Source Code, https://github.com/izan-majeed/kaeshur-quran-data
Project-URL: App on Google Play, https://play.google.com/store/apps/details?id=com.izan.kaeshurquran
Keywords: quran,islam,kashmiri,translation,tafsir,arabic,urdu,religious,islamic-data,quran-api
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Religion
Classifier: Intended Audience :: Education
Classifier: Topic :: Religion
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
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: Operating System :: OS Independent
Classifier: Natural Language :: English
Classifier: Natural Language :: Urdu
Classifier: Natural Language :: Arabic
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Kaeshur Quran

[![Python Version](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A comprehensive Python package providing complete Quranic data with a special focus on Kashmiri translations and transliterations. This package makes the sacred text of the Quran accessible to everyone, especially Kashmiri speakers, with professionally curated translations, scholarly tafsirs (commentaries), and audio resources.

## Features

### Complete Quranic Data

- **All 114 Surahs**: Complete Arabic text using authentic Uthmani script
- **6,236 Verses**: Every verse with its unique identifier
- **Verse-by-verse Access**: Easy retrieval using standard notation (e.g., "2:255" for Ayat al-Kursi)

### Multiple Translations

#### Kashmiri (کٲشُر)

- **Athar Manigami** (ID: 300) - Kashmiri translation
- **Mirwaiz M. Yousuf Shah** (ID: 301) - Kashmiri translation
- **Athar Manigami Transliterated** (ID: 400) - Kashmiri-English transliteration
- **Mirwaiz M. Yousuf Shah Transliterated** (ID: 401) - Kashmiri-English transliteration

#### English

- **Saheeh International** (ID: 20) - Modern, easy-to-understand
- **Abdullah Yusuf Ali** (ID: 22) - Classical with commentary notes
- **Mufti Taqi Usmani** (ID: 84) - Contemporary scholarly
- **Abdul Haleem** (ID: 85) - Contemporary and clear
- **Verse Transliteration** (ID: 57) - Arabic-English transliteration

#### Urdu (اردو)

- **Fatah Muhammad Jalandhari** (ID: 234) - Popular classical
- **Maulana Muhammad Junagarhi** (ID: 54) - Traditional
- **Syed Abu A'la Maududi** (ID: 97) - Scholarly

### Scholarly Tafsirs (Commentaries)

#### English

- **Ibn Kathir (Abridged)** (ID: 169) by Hafiz Ibn Kathir - Classical, comprehensive
- **Ma'arif al-Qur'an** (ID: 168) by Mufti Muhammad Shafi - Modern comprehensive
- **Tazkirul Quran** (ID: 817) by Maulana Wahiduddin Khan - Contemporary, accessible

#### Urdu

- **Bayan ul Quran** (ID: 159) by Dr. Israr Ahmad - Contemporary scholarly

### Audio Resources

- YouTube links for Kashmiri audio recitations
- Surah-by-surah audio access

### Additional Islamic Content

- **Asmaul Husna**: The 99 Beautiful Names of Allah with English meanings and Arabic text

## Installation

```bash
pip install kaeshur-quran
```

Or install from source:

```bash
git clone https://github.com/izan-majeed/kaeshur-quran-data.git
cd kaeshur-quran-data
pip install -e .
```

## Quick Start

```python
from kaeshur_quran import QuranData

# Initialize the Quran data object
quran = QuranData()

# Get a verse (Ayat al-Kursi - The Throne Verse)
verse = quran.get_verse("2:255")
print(verse['verse_content'])  # Arabic text

# Get translation (Saheeh International)
translation = quran.get_translation("2:255", translator_id=20)
print(translation['translation'])

# Get Kashmiri translation
kashmiri = quran.get_translation("2:255", translator_id=300)
print(kashmiri['translation'])

# Get Kashmiri transliteration (Roman script)
transliteration = quran.get_translation("2:255", translator_id=400)
print(transliteration['translation'])
```

## Usage Examples

### Working with Verses

```python
# Get a single verse
verse = quran.get_verse("1:1")  # First verse of Al-Fatiha
print(f"{verse['verse_key']}: {verse['verse_content']}")

# Get entire surah (Al-Fatiha)
surah = quran.get_surah(1)
print(f"Al-Fatiha has {len(surah)} verses")
for verse in surah:
    print(f"Verse {verse['verse_key']}: {verse['verse_content']}")
```

### Working with Translations

```python
# Get all available translators
translators = quran.get_translators()
for t in translators:
    print(f"{t['translator']} (ID: {t['translator_id']}, Language: {t['language']})")

# Get only Kashmiri translators
kashmiri_translators = quran.get_translators(language='ks')
for t in kashmiri_translators:
    print(f"{t['translator']} (ID: {t['translator_id']})")

# Get entire surah translation
surah_translation = quran.get_surah_translation(1, translator_id=20)
for verse_trans in surah_translation:
    print(f"Verse {verse_trans['verse_id']}: {verse_trans['translation']}")

# Get verse with multiple translations at once
result = quran.get_verse_with_translations(
    "1:1",
    translator_ids=[20, 300, 400]  # English, Kashmiri, Kashmiri-transliterated
)
print("Arabic:", result['verse']['verse_content'])
print("English:", result['translations'][20]['translation'])
print("Kashmiri:", result['translations'][300]['translation'])
print("Transliteration:", result['translations'][400]['translation'])
```

### Working with Tafsir (Commentary)

```python
# Get available tafsirs
tafasir = quran.get_tafasir()
for t in tafasir:
    print(f"{t['tafsir_name']} by {t['author']} (ID: {t['tafsir_id']}, {t['language']})")

# Get tafsir for a specific verse (Ibn Kathir)
tafsir_entries = quran.get_tafsir("1:1", tafsir_id=169)
for entry in tafsir_entries:
    print(f"Verses {entry['start_verse']}-{entry['end_verse']}")
    print(entry['tafsir'])

# Get entire surah tafsir
surah_tafsir = quran.get_surah_tafsir(1, tafsir_id=169)
print(f"Total tafsir entries for Al-Fatiha: {len(surah_tafsir)}")
```

### Surah Metadata

```python
# Get all surahs metadata
surahs = quran.get_surahs()
for surah in surahs[:5]:
    print(f"{surah['surah_id']}. {surah['name_en']} ({surah['name_ar']})")
    print(f"   Meaning: {surah['meaning_en']}")
    print(f"   Verses: {surah['verses_count']}, Revealed in: {surah['revelation_place']}")

# Get specific surah info
al_baqarah = quran.get_surah_info(2)
print(f"{al_baqarah['name_en']}: {al_baqarah['meaning_en']}")
print(f"Verses: {al_baqarah['verses_count']}")
print(f"Revelation: {al_baqarah['revelation_place']}")
```

### YouTube Audio Links

```python
# Get YouTube link for a surah (Kashmiri recitation)
link = quran.get_youtube_link(1)
if link:
    print(f"Listen to Al-Fatiha: {link}")

# Get all available YouTube links
all_links = quran.get_youtube_links()
print(f"Audio available for {len(all_links)} surahs")
```

### Asmaul Husna (99 Names of Allah)

```python
# Get all 99 Names of Allah
names = quran.get_asmaul_husna()
for name in names:
    print(f"{name['id']}. {name['name']} ({name['arabic']}) - {name['meaning']}")

# Get first 10 names
first_ten = quran.get_asmaul_husna()[:10]
for name in first_ten:
    print(f"{name['name']}: {name['meaning']}")
```

### Search Functionality

```python
# Search for verses containing specific Arabic text
results = quran.search_verse_by_content("الرحمن")
print(f"Found {len(results)} verses containing 'الرحمن'")
for verse in results[:5]:
    print(f"{verse['verse_key']}: {verse['verse_content']}")
```

## Data Structure

### Translators

| ID  | Language | Translator                              |
| --- | -------- | --------------------------------------- |
| 20  | English  | Saheeh International                    |
| 22  | English  | Abdullah Yusuf Ali                      |
| 84  | English  | Mufti Taqi Usmani                       |
| 85  | English  | Abdul Haleem                            |
| 57  | ar-en    | Verse Transliteration                   |
| 234 | Urdu     | Fatah Muhammad Jalandhari               |
| 54  | Urdu     | Maulana Muhammad Junagarhi              |
| 97  | Urdu     | Syed Abu A'la Maududi                   |
| 300 | Kashmiri | Athar Manigami                          |
| 301 | Kashmiri | Mirwaiz M. Yousuf Shah                  |
| 400 | ks-en    | Athar Manigami (Transliterated)         |
| 401 | ks-en    | Mirwaiz M. Yousuf Shah (Transliterated) |

### Tafsirs

| ID  | Language | Tafsir Name           | Author                  |
| --- | -------- | --------------------- | ----------------------- |
| 169 | English  | Ibn Kathir (Abridged) | Hafiz Ibn Kathir        |
| 168 | English  | Ma'arif al-Qur'an     | Mufti Muhammad Shafi    |
| 817 | English  | Tazkirul Quran        | Maulana Wahiduddin Khan |
| 159 | Urdu     | Bayan ul Quran        | Dr. Israr Ahmad         |

## Use Cases

- **Islamic Apps**: Build Quran applications with Kashmiri language support
- **Research**: Academic research on Quranic translations and interpretations
- **Education**: Learning and teaching tools for Quran study
- **Accessibility**: Making Quran accessible to Kashmiri speakers worldwide
- **Data Analysis**: Linguistic and textual analysis of Quranic content
- **Voice Applications**: Integration with text-to-speech for audio Quran apps

## Contributing

Contributions are welcome! This project aims to make Islamic knowledge accessible to everyone. If you find any errors in translations or have suggestions for improvements:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/improvement`)
3. Commit your changes (`git commit -am 'Add improvement'`)
4. Push to the branch (`git push origin feature/improvement`)
5. Open a Pull Request

## Related Projects

This data powers the **Kaeshur Quran** mobile application available on Google Play:
[Download Kaeshur Quran](https://play.google.com/store/apps/details?id=com.izan.kaeshurquran)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- All the translators and scholars whose work is included in this package
- The Kashmiri Muslim community for preserving and promoting Islamic knowledge in Kashmiri language
- Contributors to the open-source Islamic data ecosystem

## Contact

**Izan Majeed**

- Email: izanmajeed03@gmail.com
- GitHub: [@izan-majeed](https://github.com/izan-majeed)
- App: [Kaeshur Quran on Google Play](https://play.google.com/store/apps/details?id=com.izan.kaeshurquran)

## Support

If you find this package useful, please:

- Star the repository
- Share it with others
- Try the Kaeshur Quran mobile app
- Make dua for the success of this project

---

**Note**: This package is provided as-is for educational and religious purposes. While we strive for accuracy, please consult qualified scholars for religious guidance and verification.
