Quran Ayah Lookup

Overview

Quran Ayah Lookup is a high-performance Python package designed for efficient Quranic ayah lookup with O(1) verse access and advanced Arabic text normalization. This package focuses exclusively on Arabic Quranic text, providing developers and researchers with lightning-fast access to the complete Quran corpus.

The package uses the trusted Quran text corpus from Tanzil.net, ensuring accuracy and authenticity. With 6,348 verses including Basmalas, it provides complete coverage of the Quran with specialized handling for repeated phrases and advanced search capabilities.

Key Features

• 🚀 O(1) Performance: Lightning-fast verse lookup (956x faster than linear search!)
• 📖 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
• 🔄 Repeated Phrases: Find all occurrences of repeated Quranic phrases
• 📏 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
• 🕌 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

Technical Implementation

Architecture Overview

The package implements a hashmap-based database structure for O(1) verse access, with specialized data models for Quran verses, chapters, and search results. It uses the RapidFuzz library for high-performance fuzzy string matching.

Backend

• Python 3.8+ with type hints and modern Python features
• RapidFuzz for fuzzy string matching and similarity scoring
• Hashmap-based storage for constant-time verse lookups
• Chapter-based organization with efficient data structures
• Text normalization using advanced Arabic processing techniques

Data Structure

• 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

Infrastructure/DevOps

• PyPI distribution with automated publishing
• Comprehensive testing with pytest and coverage reporting
• Code quality tools: Black for formatting, Flake8 for linting, MyPy for type checking
• Make-based build system for development workflow automation

Challenges & Solutions

1. Performance Optimization: Achieving O(1) lookup performance for 6,348 verses

   • Solution: Implemented hashmap-based storage with direct indexing, resulting in 956x speedup over linear search

2. Arabic Text Processing: Handling complex Arabic diacritics and normalization

   • Solution: Developed advanced text normalization algorithms for diacritics removal and Alif variants

3. Basmala Handling: Proper organization of Basmalas across different surahs

   • Solution: Smart detection and indexing system that automatically handles Basmala placement

4. Fuzzy Search Accuracy: Implementing reliable partial text matching for Arabic

   • Solution: Integrated RapidFuzz library with custom similarity thresholds and word-level positioning

Performance Optimizations

• O(1) Lookup Performance: 956x faster than linear search
• Hashmap-based Storage: Constant-time access to any verse
• Lazy Loading: Efficient memory usage with on-demand data access
• Optimized Search Algorithms: Fast fuzzy matching with configurable thresholds
• Minimal Dependencies: Only RapidFuzz as external dependency for performance

Security Features

• Trusted Data Source: Uses verified Quran text from Tanzil.net
• Input Validation: Proper validation of surah and ayah numbers
• No Network Dependencies: Local database with no external API calls
• Type Safety: Full type hints and static type checking

What I Learned

• Advanced Python performance optimization techniques
• Arabic text processing and normalization algorithms
• Building efficient data structures for large datasets
• Python package development and PyPI publishing
• Implementing fuzzy search algorithms for non-Latin scripts
• Creating comprehensive testing suites for data packages

Future Plans

• Advanced search with filters (surah range, verse types)
• Performance optimizations and caching improvements
• CLI interface for command-line usage
• Web API endpoint support
• Export functionality (JSON, CSV)
• Enhanced documentation and examples
• Future consideration: Translation support (not currently planned)

---

May this tool be beneficial for those seeking to engage with the Quran. 🤲