# Quran Ayah Lookup
[](https://badge.fury.io/py/quran-ayah-lookup)
[](https://pypi.org/project/quran-ayah-lookup/)
[](https://opensource.org/licenses/MIT)
A high-performance Python package for Quranic ayah lookup with **O(1) verse access** and Arabic text normalization. **Arabic only** - translations are not supported at this time.
**Quran Corpus Source**: This package uses the Quran text corpus from [Tanzil.net](https://tanzil.net/), a trusted source for accurate Quranic text.
## Features
- 🚀 **O(1) Performance**: Lightning-fast verse lookup (956x faster than linear search!)
- ⚡ **207x Faster Sliding Window**: New alignment-based algorithm (54ms vs 11s per query!)
- 📖 **Ayah Lookup**: Direct access with `db[surah][ayah]` syntax
- 🔍 **Arabic Text Search**: Search for ayahs using Arabic text
- 🎯 **Fuzzy Search**: Advanced partial text matching with similarity scoring
- 🔄 **Multi-Ayah Search**: Sliding window search for text spanning multiple verses
- 🧠 **Smart Search**: Automatic method selection for optimal results
- 📏 **Word-level Positioning**: Precise match locations within verses
- 🎚️ **Smart Basmala Handling**: Automatic Basmala extraction and organization
- 🔤 **Text Normalization**: Advanced Arabic diacritics removal and Alif normalization
- 🏗️ **Chapter-based Structure**: Efficient QuranChapter organization
- 💾 **Performance Cache**: Pre-computed corpus and word lists for optimal speed
- 📊 **Basmalah-Aware Counting**: Precise verse counts with/without Basmalas
- 🎯 **Absolute Indexing**: O(1) access to any verse by absolute position (0-6347)
- 💻 **CLI Interface**: Command-line tool with interactive REPL mode (`qal` command)
- 🌐 **REST API**: HTTP endpoints with Swagger documentation (`qal serve`)
- 🕌 **Arabic Only**: Focused on Arabic Quranic text (no translations supported)
- 📚 **Tanzil.net Corpus**: Uses trusted Quran text from Tanzil.net
- ✨ **Complete Coverage**: Full Quran with 6,348 verses including Basmalas
## Installation
### From PyPI (Recommended)
```bash
pip install quran-ayah-lookup
```
### From Source
```bash
git clone https://github.com/sayedmahmoud266/quran-ayah-lookup.git
cd quran-ayah-lookup
pip install -e .
```
## Quick Start
### Python API
```python
import quran_ayah_lookup as qal
# Database loads automatically on import
# ✓ Quran database loaded successfully:
# - Total verses: 6348
# - Total surahs: 114
# - Source: Tanzil.net
# O(1) Direct verse access
verse = qal.get_verse(3, 35) # Surah Al-Imran, Ayah 35
print(verse.text) # Original Arabic text with diacritics
print(verse.text_normalized) # Normalized text without diacritics
# Even faster: Direct database access
db = qal.get_quran_database()
verse = db[3][35] # O(1) lookup!
# Get entire surah/chapter
surah = qal.get_surah(3) # Al-Imran
basmala = surah[0] # Basmala (ayah 0)
first_ayah = surah[1] # First ayah
print(f"Surah has {len(surah)} verses")
# Search Arabic text
results = qal.search_text("الله")
print(f"Found {len(results)} verses containing 'الله'")
# Fuzzy search with partial matching
fuzzy_results = qal.fuzzy_search("كذلك يجتبيك ربك ويعلمك", threshold=0.8)
for result in fuzzy_results[:3]:
print(f"Surah {result.verse.surah_number}:{result.verse.ayah_number} (similarity: {result.similarity:.3f})")
# Multi-ayah sliding window search (for text spanning multiple verses)
multi_results = qal.search_sliding_window("الرحمن علم القران خلق الانسان علمه البيان", threshold=80.0)
for match in multi_results[:3]:
print(f"{match.get_reference()}: {match.similarity:.1f}% similarity")
# Smart search (automatically selects best method)
smart_result = qal.smart_search("الرحمن الرحيم")
print(f"Used {smart_result['method']} search, found {smart_result['count']} results")
# Find repeated phrases
repeated = qal.fuzzy_search("فبأي الاء ربكما تكذبان")
print(f"Found {len(repeated)} occurrences of this repeated phrase")
# Check verse existence (O(1))
if 35 in surah:
verse = surah[35]
# Get all verses from a surah
all_verses = surah.get_all_verses()
```
### Command Line Interface (CLI)
The package includes a powerful CLI accessible via `quran-ayah-lookup` or `qal` for quick lookups and searches:
#### Get a Specific Verse
```bash
# Get verse 35 from Surah 3 (Al-Imran)
qal verse 3 35
# Show only normalized text
qal verse 3 35 --normalized
# Show only original text with diacritics
qal verse 3 35 --original
```
#### Get Surah Information
```bash
# Show surah information
qal surah 3
# Show verse count only
qal surah 3 --count
# List all verses in the surah
qal surah 3 --list
```
#### Search for Text
```bash
# Search for verses containing "الله"
qal search "الله"
# Limit results to 5
qal search "الله" --limit 5
# Search in original text (with diacritics)
qal search "بِسْمِ" --original
```
#### Fuzzy Search
```bash
# Fuzzy search with default threshold (0.7)
qal fuzzy "كذلك يجتبيك ربك ويعلمك"
# Use custom similarity threshold
qal fuzzy "بسم الله" --threshold 0.9
# Limit fuzzy search results
# Limit fuzzy search results
qal fuzzy "الله" --limit 10
```
#### Sliding Window Search (Multi-Ayah)
```bash
# Search for text spanning multiple ayahs
qal sliding-window "الرحمن علم القران خلق الانسان علمه البيان"
# Use custom similarity threshold (0.0-100.0)
qal sliding-window "بسم الله الرحمن الرحيم الحمد لله" --threshold 85.0
# Limit results
qal sliding-window "الرحمن علم القران" --limit 5
```
#### Smart Search (Automatic Method Selection)
```bash
# Let the package choose the best search method
qal smart-search "الرحمن الرحيم"
# Configure thresholds for each method
qal smart-search "الحمد لله" --fuzzy-threshold 0.8 --sliding-threshold 85.0
# Limit results
qal smart-search "بسم الله" --limit 10
```
#### List All Verses in a Surah
```bash
# List all verses in Surah 1 (Al-Fatiha)
qal list-verses 1
# List all verses in Surah 114 (An-Nas)
qal list-verses 114
```
#### Show Database Statistics
```bash
# Display Quran database statistics
qal stats
```
#### Interactive REPL Mode
Start an interactive Read-Eval-Print Loop session by running the command without any arguments:
```bash
# Start interactive REPL mode
qal
# Or use the full command
quran-ayah-lookup
```
In REPL mode, you can run commands interactively:
```
============================================================
Quran Ayah Lookup - Interactive REPL Mode
============================================================
Commands:
verse <surah> <ayah> - Get a specific verse
surah <number> - Get surah information
search <query> - Search for text
fuzzy <query> - Fuzzy search
sliding-window <query> - Multi-ayah sliding window search
smart-search <query> - Smart search (auto-selects method)
stats - Show database stats
help - Show this help
exit / quit / Ctrl+C - Exit REPL
============================================================
qal> verse 1 1
Ayah 1:1
----------------------------------------
Original: بِسۡمِ ٱللَّهِ ٱلرَّحۡمَٰنِ ٱلرَّحِيمِ
Normalized: بسم الله الرحمن الرحيم
qal> search الله
Found 2851 verse(s)
qal> stats
Total surahs: 114
Total verses: 6348
qal> exit
Goodbye!
```
#### Get Help
```bash
# Show all available commands
qal --help
# Show help for a specific command
qal verse --help
qal search --help
qal fuzzy --help
# Show version
qal --version
```
## Performance & Advanced Features
### ⚡ High-Performance Sliding Window Search
The new alignment-based sliding window algorithm delivers **207x faster** performance compared to the previous implementation:
```python
import quran_ayah_lookup as qal
# Load database (cache is enabled by default)
db = qal.load_quran_db()
# Multi-ayah search - now 207x faster!
query = "الرحمن علم القران خلق الانسان علمه البيان"
results = qal.search_sliding_window(query, threshold=80.0, max_results=5, db=db)
for result in results:
print(f"Match: Surah {result.surah_start}:{result.ayah_start} to {result.surah_end}:{result.ayah_end}")
print(f"Similarity: {result.similarity:.1f}%")
print(f"Matched text: {result.matched_text[:100]}...")
print()
```
**Performance Results:**
- **Old Algorithm**: ~11,150ms per query (11.15 seconds)
- **New Algorithm**: ~54ms per query
- **Speedup**: 207x faster! 🚀
### 💾 Performance Cache System
The cache system pre-computes corpus data for optimal speed:
```python
import quran_ayah_lookup as qal
# Cache is enabled by default
db = qal.load_quran_db() # Cache is built automatically
# Disable cache if needed (for minimal memory footprint)
qal.__enable_cache__ = False
db = qal.load_quran_db() # No cache, uses ~28% less memory
# Re-enable cache
qal.__enable_cache__ = True
db = qal.load_quran_db()
```
**Cache Performance Benefits:**
- **With Cache**: ~54ms average per sliding window query
- **Without Cache**: ~69ms average per sliding window query
- **Speedup**: ~28% faster with cache enabled
**What's Cached:**
- Full combined corpus text (720,944 chars original, 405,394 normalized)
- Pre-split word lists (82,459 original words, 77,881 normalized)
- Pre-sorted reference lists (114 surahs, 6,348 ayah tuples)
- Character-to-word offset mappings for O(log n) lookups
### 📊 Basmalah-Aware Counting
Get accurate verse counts with or without Basmalas:
```python
import quran_ayah_lookup as qal
db = qal.load_quran_db()
# Total verses including Basmalas (default)
total_with_basmalah = db.get_verse_count(include_basmalah=True)
print(f"Total verses with Basmalah: {total_with_basmalah}") # 6,348
# Total verses without Basmalas
total_without_basmalah = db.get_verse_count(include_basmalah=False)
print(f"Total verses without Basmalah: {total_without_basmalah}") # 6,236
# Get all verses (includes Basmalas)
all_verses = db.get_all_verses()
print(f"Retrieved {len(all_verses)} verses") # 6,348
# Check if a surah has a Basmala
surah = db.get_surah(1)
if surah.has_basmala():
print(f"Surah {surah.number} has a Basmala")
```
**Key Facts:**
- Total Quranic verses: **6,236** (without Basmalas)
- Total with Basmalas: **6,348** (112 Basmalas for surahs 2-114, except At-Tawbah)
- Surah 1 (Al-Fatiha): Basmala is verse 1:1
- Surah 9 (At-Tawbah): No Basmala
- Surahs 2-114 (except 9): Basmala stored separately with ayah=0
### 🎯 Absolute Indexing
Access any verse by its absolute position (0-6347):
```python
import quran_ayah_lookup as qal
db = qal.load_quran_db()
# Get verse by absolute index (O(1) lookup)
verse = db.get_verse_by_absolute_index(0) # First verse: 1:1
print(f"Verse {verse.surah}:{verse.ayah}: {verse.text_normalized}")
verse = db.get_verse_by_absolute_index(6347) # Last verse: 114:6
print(f"Verse {verse.surah}:{verse.ayah}: {verse.text_normalized}")
# Convert between absolute and (surah, ayah) coordinates
absolute_idx = db.verse_to_absolute_index(1, 1) # Returns 0
print(f"Verse 1:1 is at absolute index {absolute_idx}")
surah, ayah = db.absolute_index_to_verse(0) # Returns (1, 1)
print(f"Absolute index 0 is verse {surah}:{ayah}")
```
### 🔍 Smart Search (Automatic Method Selection)
Let the package automatically choose the best search method:
```python
import quran_ayah_lookup as qal
db = qal.load_quran_db()
# Smart search automatically selects:
# - Exact search for short queries (< 10 chars)
# - Fuzzy search for medium queries (10-50 chars)
# - Sliding window for long queries (> 50 chars)
result = qal.smart_search("الرحمن الرحيم", db=db)
print(f"Used {result['method']} search")
print(f"Found {len(result['results'])} result(s)")
```
## REST API
The package includes a REST API server that exposes all functionalities via HTTP endpoints with automatic Swagger documentation.
### Starting the API Server
```bash
# Start server (default: http://127.0.0.1:8000)
qal serve
# Custom host and port
qal serve --host 0.0.0.0 --port 8080
# Development mode with auto-reload
qal serve --reload
```
### Installation
Install with API support:
```bash
pip install "quran-ayah-lookup[api]"
```
Or install dependencies separately:
```bash
pip install fastapi uvicorn[standard]
```
### API Documentation
Once the server is running, access the interactive documentation:
- **Swagger UI**: http://127.0.0.1:8000/docs
- **ReDoc**: http://127.0.0.1:8000/redoc
### Available Endpoints
- `GET /verses/{surah}/{ayah}` - Get a specific verse
- `GET /surahs/{surah}` - Get surah information
- `GET /surahs/{surah}/verses` - Get all verses in a surah
- `GET /search?query={text}` - Search for verses
- `GET /fuzzy-search?query={text}&threshold={0.7}` - Fuzzy search
- `GET /sliding-window?query={text}&threshold={80.0}` - Multi-ayah sliding window search
- `GET /smart-search?query={text}` - Smart search (auto-selects method)
- `GET /stats` - Database statistics
- `GET /health` - Health check
### Quick API Example
```bash
# Get a verse
curl http://127.0.0.1:8000/verses/1/1
# Search (URL-encoded)
curl "http://127.0.0.1:8000/search?query=%D8%A7%D9%84%D9%84%D9%87&limit=5"
# Fuzzy search
curl "http://127.0.0.1:8000/fuzzy-search?query=%D8%A8%D8%B3%D9%85%20%D8%A7%D9%84%D9%84%D9%87&threshold=0.8"
# Sliding window search
curl "http://127.0.0.1:8000/sliding-window?query=%D8%A7%D9%84%D8%B1%D8%AD%D9%85%D9%86%20%D8%B9%D9%84%D9%85%20%D8%A7%D9%84%D9%82%D8%B1%D8%A7%D9%86&threshold=80.0"
# Smart search
curl "http://127.0.0.1:8000/smart-search?query=%D8%A7%D9%84%D8%B1%D8%AD%D9%85%D9%86%20%D8%A7%D9%84%D8%B1%D8%AD%D9%8A%D9%85"
# Get stats
curl http://127.0.0.1:8000/stats
```
Using Python:
```python
import requests
# Get verse
response = requests.get("http://127.0.0.1:8000/verses/1/1")
verse = response.json()
# Search
response = requests.get("http://127.0.0.1:8000/search",
params={"query": "الله", "limit": 5})
results = response.json()
# Fuzzy search
response = requests.get("http://127.0.0.1:8000/fuzzy-search",
params={"query": "بسم الله", "threshold": 0.8})
fuzzy_results = response.json()
# Sliding window search
response = requests.get("http://127.0.0.1:8000/sliding-window",
params={"query": "الرحمن علم القران", "threshold": 80.0})
sliding_results = response.json()
# Smart search
response = requests.get("http://127.0.0.1:8000/smart-search",
params={"query": "الرحمن الرحيم"})
smart_result = response.json()
print(f"Used {smart_result['method']} search")
```
For complete API documentation, see [docs/api.md](docs/api.md#rest-api-reference).
## Performance
### Search Performance Benchmarks
**Sliding Window Search (Multi-Ayah):**
- **Old Algorithm**: ~11,150ms per query (11.15 seconds)
- **New Algorithm**: ~54ms per query
- **Speedup**: 207x faster! 🚀
**Cache Impact:**
- **With Cache**: ~54ms average (recommended)
- **Without Cache**: ~69ms average
- **Cache Speedup**: ~28% faster
### O(1) Lookup Performance
```
O(1) lookup (1000x): 0.0006s
O(n) lookup (1000x): 0.5725s
Speedup: 956x faster! 🚀
```
### Database Structure
- **6,348 total verses** (6,236 original + 112 Basmalas)
- **114 surahs** with chapter-based organization
- **Hashmap-based storage** for O(1) access
- **Smart Basmala handling** for surahs 2-114 (except At-Tawbah)
- **Pre-computed cache** for optimal sliding window performance
## API Reference
### Core Functions
```python
# Verse lookup
verse = qal.get_verse(surah_number, ayah_number)
db[surah_number][ayah_number] # Direct O(1) access
# Surah/Chapter access
surah = qal.get_surah(surah_number)
surah[ayah_number] # O(1) verse access
len(surah) # Verse count
surah.has_basmala() # Check for Basmala
# Search and utility
results = qal.search_text(query, normalized=True)
fuzzy_results = qal.fuzzy_search(query, threshold=0.7, max_results=10)
verses = qal.get_surah_verses(surah_number)
normalized = qal.normalize_arabic_text(text)
```
### Data Models
- **`QuranVerse`**: Individual verse with original and normalized text
- **`QuranChapter`**: Surah container with O(1) verse access
- **`QuranDatabase`**: Main database with chapter organization
- **`FuzzySearchResult`**: Fuzzy search result with similarity and position data
## Requirements
### Core Requirements
- Python 3.8 or higher
- rapidfuzz >= 3.0.0
- click >= 8.0.0
### Optional (for REST API)
- fastapi >= 0.104.0
- uvicorn[standard] >= 0.24.0
Install with: `pip install "quran-ayah-lookup[api]"`
## Development
### Setting up Development Environment
1. Clone the repository:
```bash
git clone https://github.com/sayedmahmoud266/quran-ayah-lookup.git
cd quran-ayah-lookup
```
2. Initialize development environment:
```bash
make init # Initialize virtual environment
make install-deps # Install production dependencies
make install-deps-dev # Install development dependencies
```
3. Run tests:
```bash
make test # Run unit tests
make test-coverage # Run tests with coverage report
```
### Available Make Commands
Use `make help` to see all available commands:
```bash
make help # Show all available commands
make init # Initialize virtual environment
make install-deps # Install production dependencies
make install-deps-dev # Install development dependencies
make install-dev # Install package in development mode
make test # Run unit tests
make test-coverage # Run tests with coverage report
make format # Format code with black
make lint # Lint code with flake8
make typecheck # Type check with mypy
make check # Run all checks (format, lint, typecheck, test)
make build # Build the package
make clean # Clean build artifacts
make clean-all # Clean everything including virtual environment
make setup-dev # Complete development setup (init + install-deps-dev)
make publish-test # Publish to test PyPI
make publish # Publish to PyPI
```
### Quick Development Setup
For a complete development environment setup:
```bash
make setup-dev # Does: init + install-deps-dev
```
## Contributing
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
### Development Workflow
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for your changes
5. Ensure all tests pass (`pytest`)
6. Format your code (`black src/`)
7. Commit your changes (`git commit -m 'Add amazing feature'`)
8. Push to the branch (`git push origin feature/amazing-feature`)
9. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Author
- **Sayed Mahmoud** - [sayedmahmoud266](https://github.com/sayedmahmoud266)
- Email: foss-support@sayedmahmoud266.website
## Roadmap
### ✅ Completed
- [x] **O(1) Verse Lookup**: Lightning-fast `db[surah][ayah]` access
- [x] **Arabic Text Search**: Full-text search across all verses
- [x] **Fuzzy Matching**: Partial text matching with similarity scoring
- [x] **Sliding Window Search**: Multi-ayah search with 207x performance improvement
- [x] **Smart Basmala Handling**: Automatic extraction and organization
- [x] **Basmalah-Aware Counting**: Precise verse counts with/without Basmalas
- [x] **Text Normalization**: Advanced Arabic diacritics removal
- [x] **Chapter Organization**: Efficient QuranChapter structure
- [x] **Complete Database**: 6,348 verses with proper indexing
- [x] **CLI Interface**: Full-featured command-line tool with REPL mode
- [x] **REST API**: HTTP endpoints with Swagger documentation
- [x] **Performance Cache**: Pre-computed corpus for optimal speed (28% faster)
- [x] **Absolute Indexing**: O(1) access to any verse by position
- [x] **Smart Search**: Automatic method selection based on query length
### 📋 Features To Research In The Future
- [ ] Advanced search filters (surah range, verse types, date ranges)
- [ ] Query result caching and pagination
- [ ] Export functionality (JSON, CSV, Excel)
- [ ] Enhanced documentation with tutorials
- [ ] Translation support (multiple languages)
- [ ] Tafsir (commentary) support
- [ ] Web UI dashboard
## Support
If you encounter any issues or have questions, please:
1. Check the [documentation](docs/)
2. Search existing [issues](https://github.com/sayedmahmoud266/quran-ayah-lookup/issues)
3. Create a [new issue](https://github.com/sayedmahmoud266/quran-ayah-lookup/issues/new) if needed
## Acknowledgments
- **Tanzil.net**: For providing the accurate and trusted Quran text corpus
- Thanks to all contributors who help improve this package
- Special thanks to the maintainers of the RapidFuzz library
- Inspired by the need for accessible Arabic Quranic text search tools
---
_May this tool be beneficial for those seeking to engage with the Quran._ 🤲
Raw data
{
"_id": null,
"home_page": null,
"name": "quran-ayah-lookup",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Sayed Mahmoud <foss-support@sayedmahmoud266.website>",
"keywords": "quran, ayah, lookup, islamic, search, text",
"author": null,
"author_email": "Sayed Mahmoud <foss-support@sayedmahmoud266.website>",
"download_url": "https://files.pythonhosted.org/packages/80/f2/7a6d1f0920c88c99ba5af5dc3cc3c846fb8f8e3eaa46ef1df06f01a7ba85/quran_ayah_lookup-0.1.4.tar.gz",
"platform": null,
"description": "# Quran Ayah Lookup\n\n[](https://badge.fury.io/py/quran-ayah-lookup)\n[](https://pypi.org/project/quran-ayah-lookup/)\n[](https://opensource.org/licenses/MIT)\n\nA high-performance Python package for Quranic ayah lookup with **O(1) verse access** and Arabic text normalization. **Arabic only** - translations are not supported at this time.\n\n**Quran Corpus Source**: This package uses the Quran text corpus from [Tanzil.net](https://tanzil.net/), a trusted source for accurate Quranic text.\n\n## Features\n\n- \ud83d\ude80 **O(1) Performance**: Lightning-fast verse lookup (956x faster than linear search!)\n- \u26a1 **207x Faster Sliding Window**: New alignment-based algorithm (54ms vs 11s per query!)\n- \ud83d\udcd6 **Ayah Lookup**: Direct access with `db[surah][ayah]` syntax\n- \ud83d\udd0d **Arabic Text Search**: Search for ayahs using Arabic text\n- \ud83c\udfaf **Fuzzy Search**: Advanced partial text matching with similarity scoring\n- \ud83d\udd04 **Multi-Ayah Search**: Sliding window search for text spanning multiple verses\n- \ud83e\udde0 **Smart Search**: Automatic method selection for optimal results\n- \ud83d\udccf **Word-level Positioning**: Precise match locations within verses\n- \ud83c\udf9a\ufe0f **Smart Basmala Handling**: Automatic Basmala extraction and organization\n- \ud83d\udd24 **Text Normalization**: Advanced Arabic diacritics removal and Alif normalization\n- \ud83c\udfd7\ufe0f **Chapter-based Structure**: Efficient QuranChapter organization\n- \ud83d\udcbe **Performance Cache**: Pre-computed corpus and word lists for optimal speed\n- \ud83d\udcca **Basmalah-Aware Counting**: Precise verse counts with/without Basmalas\n- \ud83c\udfaf **Absolute Indexing**: O(1) access to any verse by absolute position (0-6347)\n- \ud83d\udcbb **CLI Interface**: Command-line tool with interactive REPL mode (`qal` command)\n- \ud83c\udf10 **REST API**: HTTP endpoints with Swagger documentation (`qal serve`)\n- \ud83d\udd4c **Arabic Only**: Focused on Arabic Quranic text (no translations supported)\n- \ud83d\udcda **Tanzil.net Corpus**: Uses trusted Quran text from Tanzil.net\n- \u2728 **Complete Coverage**: Full Quran with 6,348 verses including Basmalas\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install quran-ayah-lookup\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/sayedmahmoud266/quran-ayah-lookup.git\ncd quran-ayah-lookup\npip install -e .\n```\n\n## Quick Start\n\n### Python API\n\n```python\nimport quran_ayah_lookup as qal\n\n# Database loads automatically on import\n# \u2713 Quran database loaded successfully:\n# - Total verses: 6348\n# - Total surahs: 114\n# - Source: Tanzil.net\n\n# O(1) Direct verse access\nverse = qal.get_verse(3, 35) # Surah Al-Imran, Ayah 35\nprint(verse.text) # Original Arabic text with diacritics\nprint(verse.text_normalized) # Normalized text without diacritics\n\n# Even faster: Direct database access\ndb = qal.get_quran_database()\nverse = db[3][35] # O(1) lookup!\n\n# Get entire surah/chapter\nsurah = qal.get_surah(3) # Al-Imran\nbasmala = surah[0] # Basmala (ayah 0)\nfirst_ayah = surah[1] # First ayah\nprint(f\"Surah has {len(surah)} verses\")\n\n# Search Arabic text\nresults = qal.search_text(\"\u0627\u0644\u0644\u0647\")\nprint(f\"Found {len(results)} verses containing '\u0627\u0644\u0644\u0647'\")\n\n# Fuzzy search with partial matching\nfuzzy_results = qal.fuzzy_search(\"\u0643\u0630\u0644\u0643 \u064a\u062c\u062a\u0628\u064a\u0643 \u0631\u0628\u0643 \u0648\u064a\u0639\u0644\u0645\u0643\", threshold=0.8)\nfor result in fuzzy_results[:3]:\n print(f\"Surah {result.verse.surah_number}:{result.verse.ayah_number} (similarity: {result.similarity:.3f})\")\n\n# Multi-ayah sliding window search (for text spanning multiple verses)\nmulti_results = qal.search_sliding_window(\"\u0627\u0644\u0631\u062d\u0645\u0646 \u0639\u0644\u0645 \u0627\u0644\u0642\u0631\u0627\u0646 \u062e\u0644\u0642 \u0627\u0644\u0627\u0646\u0633\u0627\u0646 \u0639\u0644\u0645\u0647 \u0627\u0644\u0628\u064a\u0627\u0646\", threshold=80.0)\nfor match in multi_results[:3]:\n print(f\"{match.get_reference()}: {match.similarity:.1f}% similarity\")\n\n# Smart search (automatically selects best method)\nsmart_result = qal.smart_search(\"\u0627\u0644\u0631\u062d\u0645\u0646 \u0627\u0644\u0631\u062d\u064a\u0645\")\nprint(f\"Used {smart_result['method']} search, found {smart_result['count']} results\")\n\n# Find repeated phrases\nrepeated = qal.fuzzy_search(\"\u0641\u0628\u0623\u064a \u0627\u0644\u0627\u0621 \u0631\u0628\u0643\u0645\u0627 \u062a\u0643\u0630\u0628\u0627\u0646\")\nprint(f\"Found {len(repeated)} occurrences of this repeated phrase\")\n\n# Check verse existence (O(1))\nif 35 in surah:\n verse = surah[35]\n\n# Get all verses from a surah\nall_verses = surah.get_all_verses()\n```\n\n### Command Line Interface (CLI)\n\nThe package includes a powerful CLI accessible via `quran-ayah-lookup` or `qal` for quick lookups and searches:\n\n#### Get a Specific Verse\n\n```bash\n# Get verse 35 from Surah 3 (Al-Imran)\nqal verse 3 35\n\n# Show only normalized text\nqal verse 3 35 --normalized\n\n# Show only original text with diacritics\nqal verse 3 35 --original\n```\n\n#### Get Surah Information\n\n```bash\n# Show surah information\nqal surah 3\n\n# Show verse count only\nqal surah 3 --count\n\n# List all verses in the surah\nqal surah 3 --list\n```\n\n#### Search for Text\n\n```bash\n# Search for verses containing \"\u0627\u0644\u0644\u0647\"\nqal search \"\u0627\u0644\u0644\u0647\"\n\n# Limit results to 5\nqal search \"\u0627\u0644\u0644\u0647\" --limit 5\n\n# Search in original text (with diacritics)\nqal search \"\u0628\u0650\u0633\u0652\u0645\u0650\" --original\n```\n\n#### Fuzzy Search\n\n```bash\n# Fuzzy search with default threshold (0.7)\nqal fuzzy \"\u0643\u0630\u0644\u0643 \u064a\u062c\u062a\u0628\u064a\u0643 \u0631\u0628\u0643 \u0648\u064a\u0639\u0644\u0645\u0643\"\n\n# Use custom similarity threshold\nqal fuzzy \"\u0628\u0633\u0645 \u0627\u0644\u0644\u0647\" --threshold 0.9\n\n# Limit fuzzy search results\n# Limit fuzzy search results\nqal fuzzy \"\u0627\u0644\u0644\u0647\" --limit 10\n```\n\n#### Sliding Window Search (Multi-Ayah)\n\n```bash\n# Search for text spanning multiple ayahs\nqal sliding-window \"\u0627\u0644\u0631\u062d\u0645\u0646 \u0639\u0644\u0645 \u0627\u0644\u0642\u0631\u0627\u0646 \u062e\u0644\u0642 \u0627\u0644\u0627\u0646\u0633\u0627\u0646 \u0639\u0644\u0645\u0647 \u0627\u0644\u0628\u064a\u0627\u0646\"\n\n# Use custom similarity threshold (0.0-100.0)\nqal sliding-window \"\u0628\u0633\u0645 \u0627\u0644\u0644\u0647 \u0627\u0644\u0631\u062d\u0645\u0646 \u0627\u0644\u0631\u062d\u064a\u0645 \u0627\u0644\u062d\u0645\u062f \u0644\u0644\u0647\" --threshold 85.0\n\n# Limit results\nqal sliding-window \"\u0627\u0644\u0631\u062d\u0645\u0646 \u0639\u0644\u0645 \u0627\u0644\u0642\u0631\u0627\u0646\" --limit 5\n```\n\n#### Smart Search (Automatic Method Selection)\n\n```bash\n# Let the package choose the best search method\nqal smart-search \"\u0627\u0644\u0631\u062d\u0645\u0646 \u0627\u0644\u0631\u062d\u064a\u0645\"\n\n# Configure thresholds for each method\nqal smart-search \"\u0627\u0644\u062d\u0645\u062f \u0644\u0644\u0647\" --fuzzy-threshold 0.8 --sliding-threshold 85.0\n\n# Limit results\nqal smart-search \"\u0628\u0633\u0645 \u0627\u0644\u0644\u0647\" --limit 10\n```\n\n#### List All Verses in a Surah\n\n```bash\n# List all verses in Surah 1 (Al-Fatiha)\nqal list-verses 1\n\n# List all verses in Surah 114 (An-Nas)\nqal list-verses 114\n```\n\n#### Show Database Statistics\n\n```bash\n# Display Quran database statistics\nqal stats\n```\n\n#### Interactive REPL Mode\n\nStart an interactive Read-Eval-Print Loop session by running the command without any arguments:\n\n```bash\n# Start interactive REPL mode\nqal\n\n# Or use the full command\nquran-ayah-lookup\n```\n\nIn REPL mode, you can run commands interactively:\n\n```\n============================================================\nQuran Ayah Lookup - Interactive REPL Mode\n============================================================\nCommands:\n verse <surah> <ayah> - Get a specific verse\n surah <number> - Get surah information\n search <query> - Search for text\n fuzzy <query> - Fuzzy search\n sliding-window <query> - Multi-ayah sliding window search\n smart-search <query> - Smart search (auto-selects method)\n stats - Show database stats\n help - Show this help\n exit / quit / Ctrl+C - Exit REPL\n============================================================\n\nqal> verse 1 1\nAyah 1:1\n----------------------------------------\nOriginal: \u0628\u0650\u0633\u06e1\u0645\u0650 \u0671\u0644\u0644\u064e\u0651\u0647\u0650 \u0671\u0644\u0631\u064e\u0651\u062d\u06e1\u0645\u064e\u0670\u0646\u0650 \u0671\u0644\u0631\u064e\u0651\u062d\u0650\u064a\u0645\u0650\nNormalized: \u0628\u0633\u0645 \u0627\u0644\u0644\u0647 \u0627\u0644\u0631\u062d\u0645\u0646 \u0627\u0644\u0631\u062d\u064a\u0645\n\nqal> search \u0627\u0644\u0644\u0647\nFound 2851 verse(s)\n\nqal> stats\nTotal surahs: 114\nTotal verses: 6348\n\nqal> exit\nGoodbye!\n```\n\n#### Get Help\n\n```bash\n# Show all available commands\nqal --help\n\n# Show help for a specific command\nqal verse --help\nqal search --help\nqal fuzzy --help\n\n# Show version\nqal --version\n```\n\n## Performance & Advanced Features\n\n### \u26a1 High-Performance Sliding Window Search\n\nThe new alignment-based sliding window algorithm delivers **207x faster** performance compared to the previous implementation:\n\n```python\nimport quran_ayah_lookup as qal\n\n# Load database (cache is enabled by default)\ndb = qal.load_quran_db()\n\n# Multi-ayah search - now 207x faster!\nquery = \"\u0627\u0644\u0631\u062d\u0645\u0646 \u0639\u0644\u0645 \u0627\u0644\u0642\u0631\u0627\u0646 \u062e\u0644\u0642 \u0627\u0644\u0627\u0646\u0633\u0627\u0646 \u0639\u0644\u0645\u0647 \u0627\u0644\u0628\u064a\u0627\u0646\"\nresults = qal.search_sliding_window(query, threshold=80.0, max_results=5, db=db)\n\nfor result in results:\n print(f\"Match: Surah {result.surah_start}:{result.ayah_start} to {result.surah_end}:{result.ayah_end}\")\n print(f\"Similarity: {result.similarity:.1f}%\")\n print(f\"Matched text: {result.matched_text[:100]}...\")\n print()\n```\n\n**Performance Results:**\n\n- **Old Algorithm**: ~11,150ms per query (11.15 seconds)\n- **New Algorithm**: ~54ms per query\n- **Speedup**: 207x faster! \ud83d\ude80\n\n### \ud83d\udcbe Performance Cache System\n\nThe cache system pre-computes corpus data for optimal speed:\n\n```python\nimport quran_ayah_lookup as qal\n\n# Cache is enabled by default\ndb = qal.load_quran_db() # Cache is built automatically\n\n# Disable cache if needed (for minimal memory footprint)\nqal.__enable_cache__ = False\ndb = qal.load_quran_db() # No cache, uses ~28% less memory\n\n# Re-enable cache\nqal.__enable_cache__ = True\ndb = qal.load_quran_db()\n```\n\n**Cache Performance Benefits:**\n\n- **With Cache**: ~54ms average per sliding window query\n- **Without Cache**: ~69ms average per sliding window query\n- **Speedup**: ~28% faster with cache enabled\n\n**What's Cached:**\n\n- Full combined corpus text (720,944 chars original, 405,394 normalized)\n- Pre-split word lists (82,459 original words, 77,881 normalized)\n- Pre-sorted reference lists (114 surahs, 6,348 ayah tuples)\n- Character-to-word offset mappings for O(log n) lookups\n\n### \ud83d\udcca Basmalah-Aware Counting\n\nGet accurate verse counts with or without Basmalas:\n\n```python\nimport quran_ayah_lookup as qal\n\ndb = qal.load_quran_db()\n\n# Total verses including Basmalas (default)\ntotal_with_basmalah = db.get_verse_count(include_basmalah=True)\nprint(f\"Total verses with Basmalah: {total_with_basmalah}\") # 6,348\n\n# Total verses without Basmalas\ntotal_without_basmalah = db.get_verse_count(include_basmalah=False)\nprint(f\"Total verses without Basmalah: {total_without_basmalah}\") # 6,236\n\n# Get all verses (includes Basmalas)\nall_verses = db.get_all_verses()\nprint(f\"Retrieved {len(all_verses)} verses\") # 6,348\n\n# Check if a surah has a Basmala\nsurah = db.get_surah(1)\nif surah.has_basmala():\n print(f\"Surah {surah.number} has a Basmala\")\n```\n\n**Key Facts:**\n\n- Total Quranic verses: **6,236** (without Basmalas)\n- Total with Basmalas: **6,348** (112 Basmalas for surahs 2-114, except At-Tawbah)\n- Surah 1 (Al-Fatiha): Basmala is verse 1:1\n- Surah 9 (At-Tawbah): No Basmala\n- Surahs 2-114 (except 9): Basmala stored separately with ayah=0\n\n### \ud83c\udfaf Absolute Indexing\n\nAccess any verse by its absolute position (0-6347):\n\n```python\nimport quran_ayah_lookup as qal\n\ndb = qal.load_quran_db()\n\n# Get verse by absolute index (O(1) lookup)\nverse = db.get_verse_by_absolute_index(0) # First verse: 1:1\nprint(f\"Verse {verse.surah}:{verse.ayah}: {verse.text_normalized}\")\n\nverse = db.get_verse_by_absolute_index(6347) # Last verse: 114:6\nprint(f\"Verse {verse.surah}:{verse.ayah}: {verse.text_normalized}\")\n\n# Convert between absolute and (surah, ayah) coordinates\nabsolute_idx = db.verse_to_absolute_index(1, 1) # Returns 0\nprint(f\"Verse 1:1 is at absolute index {absolute_idx}\")\n\nsurah, ayah = db.absolute_index_to_verse(0) # Returns (1, 1)\nprint(f\"Absolute index 0 is verse {surah}:{ayah}\")\n```\n\n### \ud83d\udd0d Smart Search (Automatic Method Selection)\n\nLet the package automatically choose the best search method:\n\n```python\nimport quran_ayah_lookup as qal\n\ndb = qal.load_quran_db()\n\n# Smart search automatically selects:\n# - Exact search for short queries (< 10 chars)\n# - Fuzzy search for medium queries (10-50 chars)\n# - Sliding window for long queries (> 50 chars)\nresult = qal.smart_search(\"\u0627\u0644\u0631\u062d\u0645\u0646 \u0627\u0644\u0631\u062d\u064a\u0645\", db=db)\n\nprint(f\"Used {result['method']} search\")\nprint(f\"Found {len(result['results'])} result(s)\")\n```\n\n## REST API\n\nThe package includes a REST API server that exposes all functionalities via HTTP endpoints with automatic Swagger documentation.\n\n### Starting the API Server\n\n```bash\n# Start server (default: http://127.0.0.1:8000)\nqal serve\n\n# Custom host and port\nqal serve --host 0.0.0.0 --port 8080\n\n# Development mode with auto-reload\nqal serve --reload\n```\n\n### Installation\n\nInstall with API support:\n\n```bash\npip install \"quran-ayah-lookup[api]\"\n```\n\nOr install dependencies separately:\n\n```bash\npip install fastapi uvicorn[standard]\n```\n\n### API Documentation\n\nOnce the server is running, access the interactive documentation:\n\n- **Swagger UI**: http://127.0.0.1:8000/docs\n- **ReDoc**: http://127.0.0.1:8000/redoc\n\n### Available Endpoints\n\n- `GET /verses/{surah}/{ayah}` - Get a specific verse\n- `GET /surahs/{surah}` - Get surah information\n- `GET /surahs/{surah}/verses` - Get all verses in a surah\n- `GET /search?query={text}` - Search for verses\n- `GET /fuzzy-search?query={text}&threshold={0.7}` - Fuzzy search\n- `GET /sliding-window?query={text}&threshold={80.0}` - Multi-ayah sliding window search\n- `GET /smart-search?query={text}` - Smart search (auto-selects method)\n- `GET /stats` - Database statistics\n- `GET /health` - Health check\n\n### Quick API Example\n\n```bash\n# Get a verse\ncurl http://127.0.0.1:8000/verses/1/1\n\n# Search (URL-encoded)\ncurl \"http://127.0.0.1:8000/search?query=%D8%A7%D9%84%D9%84%D9%87&limit=5\"\n\n# Fuzzy search\ncurl \"http://127.0.0.1:8000/fuzzy-search?query=%D8%A8%D8%B3%D9%85%20%D8%A7%D9%84%D9%84%D9%87&threshold=0.8\"\n\n# Sliding window search\ncurl \"http://127.0.0.1:8000/sliding-window?query=%D8%A7%D9%84%D8%B1%D8%AD%D9%85%D9%86%20%D8%B9%D9%84%D9%85%20%D8%A7%D9%84%D9%82%D8%B1%D8%A7%D9%86&threshold=80.0\"\n\n# Smart search\ncurl \"http://127.0.0.1:8000/smart-search?query=%D8%A7%D9%84%D8%B1%D8%AD%D9%85%D9%86%20%D8%A7%D9%84%D8%B1%D8%AD%D9%8A%D9%85\"\n\n# Get stats\ncurl http://127.0.0.1:8000/stats\n```\n\nUsing Python:\n\n```python\nimport requests\n\n# Get verse\nresponse = requests.get(\"http://127.0.0.1:8000/verses/1/1\")\nverse = response.json()\n\n# Search\nresponse = requests.get(\"http://127.0.0.1:8000/search\",\n params={\"query\": \"\u0627\u0644\u0644\u0647\", \"limit\": 5})\nresults = response.json()\n\n# Fuzzy search\nresponse = requests.get(\"http://127.0.0.1:8000/fuzzy-search\",\n params={\"query\": \"\u0628\u0633\u0645 \u0627\u0644\u0644\u0647\", \"threshold\": 0.8})\nfuzzy_results = response.json()\n\n# Sliding window search\nresponse = requests.get(\"http://127.0.0.1:8000/sliding-window\",\n params={\"query\": \"\u0627\u0644\u0631\u062d\u0645\u0646 \u0639\u0644\u0645 \u0627\u0644\u0642\u0631\u0627\u0646\", \"threshold\": 80.0})\nsliding_results = response.json()\n\n# Smart search\nresponse = requests.get(\"http://127.0.0.1:8000/smart-search\",\n params={\"query\": \"\u0627\u0644\u0631\u062d\u0645\u0646 \u0627\u0644\u0631\u062d\u064a\u0645\"})\nsmart_result = response.json()\nprint(f\"Used {smart_result['method']} search\")\n```\n\nFor complete API documentation, see [docs/api.md](docs/api.md#rest-api-reference).\n\n## Performance\n\n### Search Performance Benchmarks\n\n**Sliding Window Search (Multi-Ayah):**\n\n- **Old Algorithm**: ~11,150ms per query (11.15 seconds)\n- **New Algorithm**: ~54ms per query\n- **Speedup**: 207x faster! \ud83d\ude80\n\n**Cache Impact:**\n\n- **With Cache**: ~54ms average (recommended)\n- **Without Cache**: ~69ms average\n- **Cache Speedup**: ~28% faster\n\n### O(1) Lookup Performance\n\n```\nO(1) lookup (1000x): 0.0006s\nO(n) lookup (1000x): 0.5725s\nSpeedup: 956x faster! \ud83d\ude80\n```\n\n### Database Structure\n\n- **6,348 total verses** (6,236 original + 112 Basmalas)\n- **114 surahs** with chapter-based organization\n- **Hashmap-based storage** for O(1) access\n- **Smart Basmala handling** for surahs 2-114 (except At-Tawbah)\n- **Pre-computed cache** for optimal sliding window performance\n\n## API Reference\n\n### Core Functions\n\n```python\n# Verse lookup\nverse = qal.get_verse(surah_number, ayah_number)\ndb[surah_number][ayah_number] # Direct O(1) access\n\n# Surah/Chapter access\nsurah = qal.get_surah(surah_number)\nsurah[ayah_number] # O(1) verse access\nlen(surah) # Verse count\nsurah.has_basmala() # Check for Basmala\n\n# Search and utility\nresults = qal.search_text(query, normalized=True)\nfuzzy_results = qal.fuzzy_search(query, threshold=0.7, max_results=10)\nverses = qal.get_surah_verses(surah_number)\nnormalized = qal.normalize_arabic_text(text)\n```\n\n### Data Models\n\n- **`QuranVerse`**: Individual verse with original and normalized text\n- **`QuranChapter`**: Surah container with O(1) verse access\n- **`QuranDatabase`**: Main database with chapter organization\n- **`FuzzySearchResult`**: Fuzzy search result with similarity and position data\n\n## Requirements\n\n### Core Requirements\n\n- Python 3.8 or higher\n- rapidfuzz >= 3.0.0\n- click >= 8.0.0\n\n### Optional (for REST API)\n\n- fastapi >= 0.104.0\n- uvicorn[standard] >= 0.24.0\n\nInstall with: `pip install \"quran-ayah-lookup[api]\"`\n\n## Development\n\n### Setting up Development Environment\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/sayedmahmoud266/quran-ayah-lookup.git\ncd quran-ayah-lookup\n```\n\n2. Initialize development environment:\n\n```bash\nmake init # Initialize virtual environment\nmake install-deps # Install production dependencies\nmake install-deps-dev # Install development dependencies\n```\n\n3. Run tests:\n\n```bash\nmake test # Run unit tests\nmake test-coverage # Run tests with coverage report\n```\n\n### Available Make Commands\n\nUse `make help` to see all available commands:\n\n```bash\nmake help # Show all available commands\nmake init # Initialize virtual environment\nmake install-deps # Install production dependencies\nmake install-deps-dev # Install development dependencies\nmake install-dev # Install package in development mode\nmake test # Run unit tests\nmake test-coverage # Run tests with coverage report\nmake format # Format code with black\nmake lint # Lint code with flake8\nmake typecheck # Type check with mypy\nmake check # Run all checks (format, lint, typecheck, test)\nmake build # Build the package\nmake clean # Clean build artifacts\nmake clean-all # Clean everything including virtual environment\nmake setup-dev # Complete development setup (init + install-deps-dev)\nmake publish-test # Publish to test PyPI\nmake publish # Publish to PyPI\n```\n\n### Quick Development Setup\n\nFor a complete development environment setup:\n\n```bash\nmake setup-dev # Does: init + install-deps-dev\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n### Development Workflow\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for your changes\n5. Ensure all tests pass (`pytest`)\n6. Format your code (`black src/`)\n7. Commit your changes (`git commit -m 'Add amazing feature'`)\n8. Push to the branch (`git push origin feature/amazing-feature`)\n9. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Author\n\n- **Sayed Mahmoud** - [sayedmahmoud266](https://github.com/sayedmahmoud266)\n- Email: foss-support@sayedmahmoud266.website\n\n## Roadmap\n\n### \u2705 Completed\n\n- [x] **O(1) Verse Lookup**: Lightning-fast `db[surah][ayah]` access\n- [x] **Arabic Text Search**: Full-text search across all verses\n- [x] **Fuzzy Matching**: Partial text matching with similarity scoring\n- [x] **Sliding Window Search**: Multi-ayah search with 207x performance improvement\n- [x] **Smart Basmala Handling**: Automatic extraction and organization\n- [x] **Basmalah-Aware Counting**: Precise verse counts with/without Basmalas\n- [x] **Text Normalization**: Advanced Arabic diacritics removal\n- [x] **Chapter Organization**: Efficient QuranChapter structure\n- [x] **Complete Database**: 6,348 verses with proper indexing\n- [x] **CLI Interface**: Full-featured command-line tool with REPL mode\n- [x] **REST API**: HTTP endpoints with Swagger documentation\n- [x] **Performance Cache**: Pre-computed corpus for optimal speed (28% faster)\n- [x] **Absolute Indexing**: O(1) access to any verse by position\n- [x] **Smart Search**: Automatic method selection based on query length\n\n### \ud83d\udccb Features To Research In The Future\n\n- [ ] Advanced search filters (surah range, verse types, date ranges)\n- [ ] Query result caching and pagination\n- [ ] Export functionality (JSON, CSV, Excel)\n- [ ] Enhanced documentation with tutorials\n- [ ] Translation support (multiple languages)\n- [ ] Tafsir (commentary) support\n- [ ] Web UI dashboard\n\n## Support\n\nIf you encounter any issues or have questions, please:\n\n1. Check the [documentation](docs/)\n2. Search existing [issues](https://github.com/sayedmahmoud266/quran-ayah-lookup/issues)\n3. Create a [new issue](https://github.com/sayedmahmoud266/quran-ayah-lookup/issues/new) if needed\n\n## Acknowledgments\n\n- **Tanzil.net**: For providing the accurate and trusted Quran text corpus\n- Thanks to all contributors who help improve this package\n- Special thanks to the maintainers of the RapidFuzz library\n- Inspired by the need for accessible Arabic Quranic text search tools\n\n---\n\n_May this tool be beneficial for those seeking to engage with the Quran._ \ud83e\udd32\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package for looking up Quranic ayahs by their number or Arabic text. Uses Quran corpus from Tanzil.net. Arabic only, no translations supported.",
"version": "0.1.4",
"project_urls": {
"Bug Tracker": "https://github.com/sayedmahmoud266/quran-ayah-lookup/issues",
"Documentation": "https://github.com/sayedmahmoud266/quran-ayah-lookup/blob/main/README.md",
"Homepage": "https://github.com/sayedmahmoud266/quran-ayah-lookup",
"Repository": "https://github.com/sayedmahmoud266/quran-ayah-lookup"
},
"split_keywords": [
"quran",
" ayah",
" lookup",
" islamic",
" search",
" text"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1f2f292ed5805ceab50fc2c12613369006cbad910fafbe70a50694104ed4a440",
"md5": "305553eac4c56fc6091e077194cc82e8",
"sha256": "35de813e96904e8bb6fd7e69e11cc6315ad09b35c700650dd5a9adfc13d56386"
},
"downloads": -1,
"filename": "quran_ayah_lookup-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "305553eac4c56fc6091e077194cc82e8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 338553,
"upload_time": "2025-10-27T20:34:34",
"upload_time_iso_8601": "2025-10-27T20:34:34.511950Z",
"url": "https://files.pythonhosted.org/packages/1f/2f/292ed5805ceab50fc2c12613369006cbad910fafbe70a50694104ed4a440/quran_ayah_lookup-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "80f27a6d1f0920c88c99ba5af5dc3cc3c846fb8f8e3eaa46ef1df06f01a7ba85",
"md5": "ae1b60b01b8a0dcd2afb8a91c0ed06c3",
"sha256": "bd924a5a4d215cc352df0f4208829ed4eaf4fb2fee5032c8cc1355480b0291bf"
},
"downloads": -1,
"filename": "quran_ayah_lookup-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "ae1b60b01b8a0dcd2afb8a91c0ed06c3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 375039,
"upload_time": "2025-10-27T20:34:36",
"upload_time_iso_8601": "2025-10-27T20:34:36.658619Z",
"url": "https://files.pythonhosted.org/packages/80/f2/7a6d1f0920c88c99ba5af5dc3cc3c846fb8f8e3eaa46ef1df06f01a7ba85/quran_ayah_lookup-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-27 20:34:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sayedmahmoud266",
"github_project": "quran-ayah-lookup",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "rapidfuzz",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "fastapi",
"specs": [
[
">=",
"0.104.0"
]
]
},
{
"name": "uvicorn",
"specs": [
[
">=",
"0.24.0"
]
]
}
],
"lcname": "quran-ayah-lookup"
}
JSON
