islamic-content-sdk 1.0.0__tar.gz

islamic_content_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,483 @@
+Metadata-Version: 2.1
+Name: islamic-content-sdk
+Version: 1.0.0
+Summary: An integrated and easy-to-use software library to fetch authentic Islamic content (Holy Quran and Hadith) in multiple languages.
+Home-page: https://github.com/2yousefreda/islamic-content-sdk-npm
+Author: The Association for Multi-lingual Islamic Content
+Author-email: info@islamiccontent.sa
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: ISC License (ISCL)
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+
+# Islamic Content SDK (Python)
+
+An integrated and easy-to-use software library for Python developers to fetch authentic Islamic content (The Holy Qur'an and Hadith) in multiple languages directly from official sources.
+
+This project is developed for [The Association for Multi-lingual Islamic Content](https://islamiccontent.sa/).
+
+---
+
+## Services Overview
+
+This SDK aggregates content from multiple major multi-lingual Islamic platforms:
+
+- **QuranEnc (`quranenc`)**: Quran Translations, suras, verses, and audios.
+- **HadeethEnc (`hadeethenc`)**: Hadith collections, category trees, and grades.
+- **IslamHouse (`islamhouse`)**: Multi-lingual books, articles, audios, fatwas, and author details.
+- **Risalat Al-Haramain (`risalatAlHaramain`)**: Platform content, Fatwas, Quran recitations, and Hadiths.
+- **Bayan Al Islam (`bayanAlIslam`)**: Educational booklets and resources tailored for Muslims and Non-Muslims.
+- **Al Montaka (`alMontaka`)**: Structured lookups, categories, content filters, and community comments.
+
+---
+
+## Installation
+
+Install the package via pip:
+
+```bash
+pip install islamic-content-sdk
+```
+
+## Usage
+
+### Initializing the SDK
+
+```python
+from islamic_content_sdk import IslamicContentSdk
+
+sdk = IslamicContentSdk()
+```
+
+---
+
+## Detailed Service Methods Reference
+
+Below is a complete guide on how to interact with every single method and option available in the SDK.
+
+### Quran Source (QuranEnc API)
+
+**API Documentation Link:** [QuranEnc API](https://quranenc.com/en/home/api/)
+
+```python
+# 1. Get available translations list on the platform
+translations = sdk.quranenc.translationList({
+    "language": "es",      # Optional: Filter list by language code
+    "localization": "ar"   # Optional: Localize names in the response
+})
+
+# 2. Translate an entire sura (Al-Fatiha in Spanish)
+sura = sdk.quranenc.translationSura("spanish_montada_eu", 1)
+
+# 3. Translate a specific verse (Ayah 1 of Sura 1)
+aya = sdk.quranenc.translationAya("spanish_montada_eu", 1, 1)
+
+# 4. Get the audio MP3 file details for a specific verse
+audio = sdk.quranenc.ayaAudio("chinese_suliman", 1, 1)
+# Returns: {"status": 200, "file_url": "...", "content_type": "audio/mpeg"}
+
+# 5. Submit translation feedback/note (POST request)
+note_response = sdk.quranenc.addNote({
+    "sura": 1,
+    "aya": 1,
+    "name": "QA Tester",
+    "email": "qa@example.com",
+    "note": "Test note from SDK automated test suite",
+    "translation_key": "spanish_montada_eu",
+    "source": "sdk_test",
+    "version": "1.0.0",
+    "suggested_translation": "Suggested text" # Optional
+})
+```
+
+---
+
+### Hadith Source (HadeethEnc API)
+
+**API Documentation Link:** [HadeethEnc API](https://documenter.getpostman.com/view/5211979/TVev3j7q#intro)
+
+```python
+# 1. Get available languages in the encyclopedia
+languages = sdk.hadeethenc.languages()
+
+# 2. Get all categories of Hadith translated in a specific language
+categories = sdk.hadeethenc.categories("en")
+
+# 3. Get main (root) categories of Hadith in English
+root_categories = sdk.hadeethenc.rootCategories("en")
+
+# 4. List Hadiths under a category with pagination
+hadiths = sdk.hadeethenc.hadithsList({
+    "language": "en",
+    "categoryId": 1,  # Optional: Category ID
+    "page": 1,        # Optional: Page number
+    "perPage": 20     # Optional: Number of items per page
+})
+
+# 5. Get full explanation, translations, and grade of a specific Hadith by ID
+hadith = sdk.hadeethenc.hadithDetails({
+    "id": 2962,
+    "language": "ar"
+})
+```
+
+---
+
+### IslamHouse Source (IslamHouse v3 API)
+
+**API Documentation Link:** [IslamHouse API Docs](https://documenter.getpostman.com/view/7929737/TzkyMfPc)
+
+```python
+# ==========================================
+# 1. Categories & Types (categoriesAndTypes)
+# ==========================================
+
+# Core material types (videos, books, fatwas, etc.)
+types = sdk.islamhouse.categoriesAndTypes.allTypes("ar", "ar") # siteLang, contentLang
+
+# Get all categories in the database
+all_categories = sdk.islamhouse.categoriesAndTypes.allCategories("ar")
+
+# Complete category hierarchy tree
+tree = sdk.islamhouse.categoriesAndTypes.categoriesTree("ar")
+
+# Subcategories of a category with content lang localization
+child_cats = sdk.islamhouse.categoriesAndTypes.childCategories(1, "ar", "ar") # categoryId, siteLang, contentLang
+
+# Basic details of a category by ID
+single_category = sdk.islamhouse.categoriesAndTypes.singleCategoryBasic(1, "ar")
+
+# Subcategories with nested children
+sub_categories = sdk.islamhouse.categoriesAndTypes.subCategories(1, "ar")
+
+# Available material types under a specific category ID
+category_types = sdk.islamhouse.categoriesAndTypes.categoryTypes(1, "ar", "ar")
+
+# Available languages for materials within a category ID
+category_langs = sdk.islamhouse.categoriesAndTypes.categoryLanguages(1, "ar", "ar") # id, slang, language
+
+# ==========================================
+# 2. Items Listings (items)
+# ==========================================
+
+# List materials by type (e.g. "books", "videos", "audios") and language
+items = sdk.islamhouse.items.listItems("books", "ar", "ar", 1, 25) # type, siteLang, slang, page, limit
+
+# List materials published by a specific author ID
+author_items = sdk.islamhouse.items.authorItems(1, "ar", "ar", "ar", 1, 20) # authorId, slang, siteLang, contentLang, page, limit
+
+# List materials categorized under a category ID
+cat_items = sdk.islamhouse.items.categoryItems(1, "ar", "ar", "ar", 1, 20) # categoryId, slang, siteLang, contentLang, page, limit
+
+# List latest items by period (e.g., "week", "month")
+latest_items = sdk.islamhouse.items.latestItems("week", "ar", "ar", "ar", 1, 25) # period, slang, siteLang, contentLang, page, limit
+
+# Highlighted featured items on the homepage
+highlights = sdk.islamhouse.items.highlightedItems("ar", "ar") # siteLang, contentLang
+
+# Get the total count of items available for a specific type
+items_count = sdk.islamhouse.items.itemsCount("books", "ar", "ar") # type, siteLang, contentLang
+
+# ==========================================
+# 3. Single Item Details (item)
+# ==========================================
+
+# Details, metadata, and description of a single item
+item_details = sdk.islamhouse.item.details(228065, "ar")
+
+# List downloadable media/PDF attachments for an item
+attachments = sdk.islamhouse.item.attachments(228065)
+
+# Category tree path leading to this item
+item_tree = sdk.islamhouse.item.tree(228065, "ar")
+
+# Translation card details of the item
+item_card_trans = sdk.islamhouse.item.cardTranslations(228065, "ar")
+
+# Other translation languages available for this item
+translations = sdk.islamhouse.item.translations(228065, "ar")
+
+# ==========================================
+# 4. Authors and Publishers (authors)
+# ==========================================
+
+# List authors/sources with filter and sort parameters
+authors = sdk.islamhouse.authors.list({
+    "kind": "author",     # Optional: "showall" | "author" | "source"
+    "locale": "ar",       # Optional: "showall" | language code
+    "sort": "countdesc",  # Optional
+    "page": 1,            # Optional
+    "perPage": 10         # Optional
+})
+
+# Specific author details by ID
+author_details = sdk.islamhouse.authors.details(1, "ar")
+
+# Translation card details of an author
+author_card = sdk.islamhouse.authors.cardTranslations(1, "ar")
+
+# Material types available for an author
+author_types = sdk.islamhouse.authors.availableTypes(1, "ar", "ar")
+
+# Languages available for an author
+author_langs = sdk.islamhouse.authors.availableLocales(1, "ar", "ar")
+
+# ==========================================
+# 5. Languages & Terms (languages)
+# ==========================================
+
+# Details of all supported languages on the platform
+lang_keys = sdk.islamhouse.languages.keys()
+
+# Interface translation terms for localization
+terms = sdk.islamhouse.languages.terms("ar")
+
+# Available languages relative to another
+avail_langs = sdk.islamhouse.languages.availableLanguages("ar", "ar")
+
+# ==========================================
+# 6. Holy Quran Recitations (quran)
+# ==========================================
+
+# Quran recitation categories (reciters, sections)
+quran_categories = sdk.islamhouse.quran.categories("ar")
+
+# Basic details of a Quran category
+quran_category = sdk.islamhouse.quran.singleCategory(1, "ar")
+
+# Details about a specific reciter
+reciter_details = sdk.islamhouse.quran.authorDetails(1, "ar")
+
+# Recitations list of a specific reciter
+recitations = sdk.islamhouse.quran.authorRecitations(1, "ar")
+
+# Detailed info of a specific Quran Surah
+sura_details = sdk.islamhouse.quran.suraDetails(1, "ar")
+
+# Audio recordings of a specific Surah by various reciters
+sura_recitations = sdk.islamhouse.quran.suraRecitations(1, "ar")
+
+# Details of a specific Quran recitation by ID
+recitation = sdk.islamhouse.quran.recitationDetails(228065, "ar")
+```
+
+---
+
+### Risalat Al-Haramain Source (Risalat Al-Haramain API)
+
+**API Documentation Link:** [Risalat Al-Haramain API](https://risala.prh.gov.sa/en/Api/content)
+
+```python
+# ==========================================
+# 1. Platform Contents (contents)
+# ==========================================
+
+# Get full content of the platform in a specific language
+full_contents = sdk.risalatAlHaramain.contents.getFullContents({
+    "language": "en", # Optional: URL language path (default: "en")
+    "lang": "en"     # Optional: Query parameter language (default: "en")
+})
+
+# Retrieve contents with optional parameters
+contents = sdk.risalatAlHaramain.contents.getContents({
+    "language": "en",
+    "lang": "en"
+})
+
+# Get detailed content of a single item
+single_content = sdk.risalatAlHaramain.contents.singleContent(1, "en")
+
+# Quick search items by name
+name_search_result = sdk.risalatAlHaramain.contents.nameSearch("حصن", "ar")
+
+# Check available translation languages for an item
+risala_avail_langs = sdk.risalatAlHaramain.contents.availableLanguages(1, "ar")
+
+# Get translation of a content item into a target language
+content_translation = sdk.risalatAlHaramain.contents.contentTranslation(1, "en", "ar") # id, targetLanguage, language
+
+# ==========================================
+# 2. Islamic Content Modules (islamicContent)
+# ==========================================
+
+# Get Fatwas
+fatwas = sdk.risalatAlHaramain.islamicContent.fatwas({
+    "language": "en",    # Optional
+    "lang": "ar",        # Optional
+    "isFeatured": 1      # Optional: 0 or 1
+})
+
+# Get featured Hadiths
+hadeeths = sdk.risalatAlHaramain.islamicContent.hadeeths({
+    "language": "en",
+    "lang": "ar",
+    "isFeatured": 1
+})
+
+# Get featured Quran recitations
+quran_content = sdk.risalatAlHaramain.islamicContent.quran({
+    "language": "en",
+    "lang": "ar",
+    "isFeatured": 1
+})
+
+# ==========================================
+# 3. Platform Search (search)
+# ==========================================
+
+# Keyword text search across platform content
+search_result = sdk.risalatAlHaramain.search.contents("حصن", "en")
+
+# ==========================================
+# 4. Lookups & Meta (lookups)
+# ==========================================
+
+# Get available languages
+risala_langs = sdk.risalatAlHaramain.lookups.languages("en")
+
+# Get available content types
+content_types = sdk.risalatAlHaramain.lookups.contentTypes("en")
+```
+
+---
+
+### Bayan Al Islam Source (Bayan Al Islam API)
+
+**Postman Resources:** [Collection](https://byenah.com/download-request?name=Bayan%20Al%20Islam.postman_collection.json) | [Environment](https://byenah.com/download-request?name=Bayan%20al%20islam%20env.postman_environment.json)
+
+```python
+# 1. Get list of available languages
+bayan_langs = sdk.bayanAlIslam.languagesList("ar")
+
+# 2. Get content list tailored for Muslims
+muslim_list = sdk.bayanAlIslam.muslimList("en")
+
+# 3. Get content list tailored for Non-Muslims
+non_muslim_list = sdk.bayanAlIslam.nonMuslimList("en")
+
+# 4. Get details of a specific content item by ID
+content_details = sdk.bayanAlIslam.singleContent(22184, "en")
+
+# 5. Get languages list paginated and filtered by name
+paginated_langs = sdk.bayanAlIslam.paginatedLanguages({
+    "name": "English", # Optional
+    "page": 1,         # Optional
+    "language": "en"   # Optional
+})
+
+# 6. Get recent contents (Muslim/Non-Muslim updates)
+recent = sdk.bayanAlIslam.recentContents({
+    "lang": "ar",
+    "init": True,
+    "ids": [22184], # Optional: content IDs list
+    "language": "en" # Optional
+})
+
+# 7. Get website lookup variables
+lookups = sdk.bayanAlIslam.lookups("en")
+
+# 8. Search materials by title/name
+search_result = sdk.bayanAlIslam.nameSearch("حصن", "ar")
+
+# 9. Check available translation languages for a content ID
+avail_langs = sdk.bayanAlIslam.availableLanguages(22184, "ar")
+
+# 10. Get specific translation of a content item
+translation = sdk.bayanAlIslam.contentTranslation(22184, "en", "ar") # id, targetLanguage, language
+
+# 11. Get translations for media or PDF attachments of a content item
+attachments_trans = sdk.bayanAlIslam.attachmentsTranslation(22184, "en", "ar") # id, targetLanguage, language
+```
+
+---
+
+### Al Montaka Source (Al Montaka API)
+
+**API Documentation Link:** [Al Montaka API](https://documenter.getpostman.com/view/5211979/2s8YzMZ6Fu)
+
+```python
+# ==========================================
+# 1. Content and Comments (contents)
+# ==========================================
+
+# Get all comments for a specific content ID
+comments = sdk.alMontaka.contents.comments(1)
+
+# Add a new comment to a specific content item
+new_comment = sdk.alMontaka.contents.addComment(1, "Test comment")
+
+# Get filtered content by category IDs
+filtered_content = sdk.alMontaka.contents.content([1, 2])
+
+# ==========================================
+# 2. Site Lookups and Filters (lookups)
+# ==========================================
+
+# Get target age groups
+age_groups = sdk.alMontaka.lookups.ageGroups()
+
+# Get categories matching language and name filter
+categories = sdk.alMontaka.lookups.categories({
+    "languageId": 1,
+    "nameCont": "General"
+})
+
+# Get publishing entities matching language and name filter
+entities = sdk.alMontaka.lookups.entities({
+    "languageId": 1,
+    "nameCont": "Dar"
+})
+
+# Get expertise/scientific levels matching filter
+expert_levels = sdk.alMontaka.lookups.expertLevels({
+    "languageId": 1,
+    "nameCont": "Level"
+})
+
+# Get ideologies matching filter
+ideologies = sdk.alMontaka.lookups.ideologies({
+    "languageId": 1,
+    "nameCont": "Sunnah",
+    "parentId": 0
+})
+
+# Get available languages
+languages = sdk.alMontaka.lookups.languages()
+
+# Get/search scholars, narrators, or personalities
+persons = sdk.alMontaka.lookups.persons({
+    "nameCont": "Muhammad", # Optional
+    "page": 1              # Optional
+})
+
+# Get website sections matching filter
+sections = sdk.alMontaka.lookups.sections({
+    "languageId": 1,
+    "nameCont": "Section"
+})
+
+# Get tags matching filter
+tags = sdk.alMontaka.lookups.tags({
+    "languageId": 1,
+    "nameCont": "Tag"
+})
+
+# Get targeted groups of audience
+targeted_groups = sdk.alMontaka.lookups.targetedGroups()
+
+# Get integrated YouTube channels list
+youtube_channels = sdk.alMontaka.lookups.youtubeChannels()
+```
+
+---
+
+## Donation & Support
+
+You can support the projects and efforts of The Association for Multi-lingual Islamic Content through the following official channels:
+
+- [Support Projects (Wakfy)](https://islamiccontent.org/Wakfy)
+- [Bank Accounts](https://islamiccontent.org/Accounts)
+- [Association Store](https://store.islamiccontent.sa/)
+- [Annual Operational Support (الدعم التشغيلي السنوي للجمعية)](https://store.islamiccontent.sa/%D8%A7%D9%84%D9%85%D8%B5%D8%B1%D9%88%D9%81%D8%A7%D8%AA-%D8%A7%D9%84%D8%AA%D8%B4%D8%BA%D9%8A%D9%84%D9%8A%D8%A9-%D8%A7%D9%84%D8%B3%D9%86%D9%88%D9%8A%D8%A9-%D9%84%D9%84%D8%AC%D9%85%D8%B9%D9%8A-%D8%A9/p1950956689)