📖 Qurango -- Hadith Module

Qurango is a Python library that provides fast, structured, and searchable access to authentic Hadith collections using JSON data bundled directly inside the package.
It is optimized for research, data analysis, NLP, and educational use.

This README explains how the Hadith system works internally and how to use it step by step.

✨ Key Highlights

• 📚 Loads Hadith data directly from packaged JSON files
• ⚡ Preprocessed and optimized for fast searching
• 🔍 Search Hadith by:
  • Keyword
  • Narrator
  • Book name
  • Hadith number
• 📊 Outputs results as Pandas DataFrames
• 🌐 Supports Urdu & English text normalization
• 🧠 Ideal for NLP, ML, and text analytics

📦 Installation

pip install Qurango

🚀 Quick Start

from Qurango.hadith import HadithLoader, HadithSearch

📘 Loading Hadith Data

The HadithLoader class automatically loads all Hadith JSON files from the package data directory and preprocesses them.

loader = HadithLoader()
``>

### ✔ What happens internally?

- Loads JSON files from `qurango.data`
- Converts data to a Pandas DataFrame
- Normalizes Urdu & English text
- Maps Arabic book titles to English names
- Prepares searchable columns for fast queries

---

## 📊 Accessing the DataFrame

```python
df = loader.get_dataframe()
print(df.head())

Total Hadith & Books

loader.total_hadiths()
loader.total_books()

📚 Available Hadith Books

Get as List

books = loader.get_available_books()
print(books)

Get as DataFrame

books_df = loader.get_available_books(as_dataframe=True)
print(books_df)

Print Books Nicely

loader.show_available_books()

🔍 Searching Hadith

Create the search engine:

search = HadithSearch(df)

🔎 Search by Keyword

results = search.search_by_keyword("iman")
print(results)

Search works across: - Hadith title - Urdu translation - English translation

🧑 Search by Narrator

results = search.search_by_narrator("Abu Huraira")
print(results)

Language options: - "urdu" - "english" - "auto" (default)

📖 Search by Book

results = search.search_by_book("Sahih Bukhari")
print(results)

Search by book + hadith number:

results = search.search_by_book("Sahih Bukhari", hadith_number=1)
print(results)

🔢 Search by Hadith Number

results = search.search_by_hadith_number(5)
print(results)

📊 Output Format

All search methods return:

• ✅ Pandas DataFrame
• ✅ Easy export to CSV / JSON
• ✅ Ready for NLP pipelines

Example:

results.to_csv("hadith_results.csv", index=False)

🧠 Use Cases

• Islamic research & academia
• NLP on religious texts
• Machine learning datasets
• Search engines & chatbots
• Educational software

🛠 Requirements

• Python 3.8+
• pandas

📜 License

MIT License

🙏 Acknowledgment

This Hadith module is built to make authentic Islamic knowledge accessible for developers, researchers, and the global community using modern data tools.