deen-api-client 1.0.0__tar.gz

deen_api_client-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Imaniro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deen_api_client-1.0.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: deen-api-client
+Version: 1.0.0
+Summary: Python client for Deen API from Imaniro.com - Islamic resources API
+Home-page: https://github.com/imaniro-tech/deen-api-python-client
+Author: Imaniro pvt ltd
+Author-email: info@imaniro.com
+Project-URL: Documentation, https://github.com/imaniro-tech/deen-api-python-client
+Project-URL: Source, https://github.com/imaniro-tech/deen-api-python-client
+Project-URL: Tracker, https://github.com/imaniro-tech/deen-api-python-client/issues
+Keywords: islamic,api,hadith,quran,dua,muslim
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Requires-Dist: dataclasses>=0.6; python_version < "3.7"
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0.0; extra == "dev"
+Requires-Dist: requests-mock>=1.9.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0.0; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Deen API Python Client
+
+A Python client for the Deen API, providing easy access to Islamic resources including Hadith, Quran verses, and Duas.
+
+## Installation
+
+```bash
+pip install deen-api-client
+```
+
+# Quick Start
+
+```python
+from deen_api import ImaniroDeenAPIClient
+
+# Initialize client with your API key
+client = ImaniroDeenAPIClient(api_key="sk_12345")
+
+# Get hadiths from Sahih al-Bukhari
+hadiths = client.get_hadiths(book="Sahih al-Bukhari", max_limits=5)
+
+for hadith in hadiths:
+    print(f"Book: {hadith.book}")
+    print(f"Chapter: {hadith.chapter}")
+    print(f"Text: {hadith.text}")
+    print(f"Translation: {hadith.translation}")
+    print("---")
+
+# Get Quran verses
+verses = client.get_quran_verses(surah="Al-Fatiha", max_limits=3)
+
+# Get Duas
+duas = client.get_duas(category="morning", max_limits=5)
+```
+
+# Features
+
+- Hadith Access: Retrieve hadiths from various books
+
+- Quran Verses: Access Quranic verses with translations(under development)
+
+- Islamic Duas: Get supplications for various occasions(under development)
+
+- Error Handling: Comprehensive exception handling
+
+# Error Handling
+
+The client provides specific exception types:
+
+```python
+from deen_api import AuthenticationError, RateLimitError, NotFoundError
+
+try:
+    hadiths = client.get_hadiths(book="Sahih al-Bukhari")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError:
+    print("Rate limit exceeded")
+except NotFoundError:
+    print("Resource not found")
+```
+
+## Example Usage Files
+
+### `examples/hadith_example.py`
+
+```python
+from deen_api import ImaniroDeenAPIClient
+
+def hadith_example():
+    client = ImaniroDeenAPIClient(api_key="sk_12345")
+
+    try:
+        # Get hadiths from Sahih al-Bukhari
+        hadiths = client.get_hadiths(book="Sahih al-Bukhari", max_limits=3)
+
+        print("Hadiths from Sahih al-Bukhari:")
+        for i, hadith in enumerate(hadiths, 1):
+            print(f"\n{i}. {hadith.hadith}")
+            print(f"Translation: {hadith.translation}")
+            print("-" * 50)
+
+    except Exception as e:
+        print(f"Error: {e}")
+
+if __name__ == "__main__":
+    hadith_example()
+```

deen_api_client-1.0.0/README.md

@@ -0,0 +1,88 @@
+# Deen API Python Client
+
+A Python client for the Deen API, providing easy access to Islamic resources including Hadith, Quran verses, and Duas.
+
+## Installation
+
+```bash
+pip install deen-api-client
+```
+
+# Quick Start
+
+```python
+from deen_api import ImaniroDeenAPIClient
+
+# Initialize client with your API key
+client = ImaniroDeenAPIClient(api_key="sk_12345")
+
+# Get hadiths from Sahih al-Bukhari
+hadiths = client.get_hadiths(book="Sahih al-Bukhari", max_limits=5)
+
+for hadith in hadiths:
+    print(f"Book: {hadith.book}")
+    print(f"Chapter: {hadith.chapter}")
+    print(f"Text: {hadith.text}")
+    print(f"Translation: {hadith.translation}")
+    print("---")
+
+# Get Quran verses
+verses = client.get_quran_verses(surah="Al-Fatiha", max_limits=3)
+
+# Get Duas
+duas = client.get_duas(category="morning", max_limits=5)
+```
+
+# Features
+
+- Hadith Access: Retrieve hadiths from various books
+
+- Quran Verses: Access Quranic verses with translations(under development)
+
+- Islamic Duas: Get supplications for various occasions(under development)
+
+- Error Handling: Comprehensive exception handling
+
+# Error Handling
+
+The client provides specific exception types:
+
+```python
+from deen_api import AuthenticationError, RateLimitError, NotFoundError
+
+try:
+    hadiths = client.get_hadiths(book="Sahih al-Bukhari")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError:
+    print("Rate limit exceeded")
+except NotFoundError:
+    print("Resource not found")
+```
+
+## Example Usage Files
+
+### `examples/hadith_example.py`
+
+```python
+from deen_api import ImaniroDeenAPIClient
+
+def hadith_example():
+    client = ImaniroDeenAPIClient(api_key="sk_12345")
+
+    try:
+        # Get hadiths from Sahih al-Bukhari
+        hadiths = client.get_hadiths(book="Sahih al-Bukhari", max_limits=3)
+
+        print("Hadiths from Sahih al-Bukhari:")
+        for i, hadith in enumerate(hadiths, 1):
+            print(f"\n{i}. {hadith.hadith}")
+            print(f"Translation: {hadith.translation}")
+            print("-" * 50)
+
+    except Exception as e:
+        print(f"Error: {e}")
+
+if __name__ == "__main__":
+    hadith_example()
+```

deen_api_client-1.0.0/deen_api/__init__.py

@@ -0,0 +1,15 @@
+from .client import ImaniroDeenAPIClient
+from .models import Hadith, APIResponse
+from .exceptions import DeenAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError
+
+__version__ = "1.0.0"
+__all__ = [
+    'ImaniroDeenAPIClient',
+    'Hadith',
+    'APIResponse',
+    'DeenAPIError',
+    'AuthenticationError',
+    'RateLimitError',
+    'NotFoundError',
+    'ServerError'
+]

deen_api_client-1.0.0/deen_api/client.py

@@ -0,0 +1,75 @@
+import requests
+from typing import List, Optional, Dict, Any
+from .models import Hadith, APIResponse
+from .exceptions import *
+
+class ImaniroDeenAPIClient:
+    def __init__(self, api_key: str, base_url: str = "https://deen-api.imaniro.com/api/v1"):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip('/')
+        self.session = requests.Session()
+        self.session.headers.update({
+            'Content-Type': 'application/json',
+            'X-API-Key': self.api_key
+        })
+    
+    def _handle_response(self, response: requests.Response) -> Dict[str, Any]:
+        """Handle API response and raise appropriate exceptions"""
+        if response.status_code == 401:
+            raise AuthenticationError("Invalid API key")
+        elif response.status_code == 404:
+            raise NotFoundError("Resource not found")
+        elif response.status_code == 429:
+            raise RateLimitError("Rate limit exceeded")
+        elif response.status_code >= 500:
+            raise ServerError("Server error occurred")
+        elif response.status_code != 200:
+            raise DeenAPIError(f"API error: {response.status_code} - {response.text}")
+        
+        return response.json()
+    
+    def _make_request(self, endpoint: str, params: Optional[Dict] = None) -> APIResponse:
+        """Make API request and return parsed response"""
+        url = f"{self.base_url}/{endpoint}"
+        
+        try:
+            response = self.session.post(url, json=params or {})
+            data = self._handle_response(response)
+            return APIResponse.from_dict(data)
+        except requests.exceptions.RequestException as e:
+            raise DeenAPIError(f"Request failed: {str(e)}")  
+ 
+    def get_hadiths(self, book: str = '', 
+                    max_limits: int = 1, 
+                    number:str = '', 
+                    language:str = 'en', 
+                    authenticity:str = '', 
+                    keywords: List[str] = [],
+                    topics: List[str] = [],
+                    narrator:str = '',
+                    **kwargs) -> List[Hadith]:
+        """
+        Get hadiths from specified book
+        
+        Args:
+            book: Name of the hadith book (e.g., "Sahih al-Bukhari")
+            max_limits: Maximum number of hadiths to return
+            **kwargs: Additional parameters for the API
+        
+        Returns:
+            List of Hadith objects
+        """
+        params = {
+            "book": book,
+            "number" : number,
+            "narrator": narrator,
+            "language": language,
+            "authenticity": authenticity,
+            "keywords": keywords,
+            "topics": topics,
+            "maxLimits": max_limits,
+            **kwargs
+        }
+        
+        response = self._make_request("hadiths", params)
+        return [Hadith.from_dict(item) for item in response.data]

deen_api_client-1.0.0/deen_api/exceptions.py

@@ -0,0 +1,19 @@
+class DeenAPIError(Exception):
+    """Base exception for Deen API client"""
+    pass
+
+class AuthenticationError(DeenAPIError):
+    """Raised when API key is invalid or missing"""
+    pass
+
+class RateLimitError(DeenAPIError):
+    """Raised when rate limit is exceeded"""
+    pass
+
+class NotFoundError(DeenAPIError):
+    """Raised when resource is not found"""
+    pass
+
+class ServerError(DeenAPIError):
+    """Raised when server returns 5xx error"""
+    pass

deen_api_client-1.0.0/deen_api/models.py

@@ -0,0 +1,46 @@
+from typing import List, Optional, Dict, Any
+from dataclasses import dataclass
+
+@dataclass
+class Hadith:
+    attribution: str
+    authenticity: str
+    category: str
+    context: str
+    explanation: str
+    hadith: str
+    narratedBy: str
+    book: str
+    number: str
+    translation: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'Hadith':
+        return cls(
+                attribution = data.get('attribution', ''),
+                authenticity = data.get('authenticity', ''),
+                category = data.get('category', ''),
+                context = data.get('context', ''),
+                explanation = data.get('explanation', ''),
+                hadith = data.get('hadith', ''),
+                narratedBy = data.get('narratedBy', ''),
+                book=data.get('book', ''),
+                number = data.get('number', ''),
+                translation=data.get('translation', '')
+        )
+
+@dataclass
+class APIResponse:
+    success: bool
+    data: List[Any]
+    message: str
+    count: int
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'APIResponse':
+        return cls(
+            success=data.get('success', False),
+            data=data.get('data', []),
+            message=data.get('message', ''),
+            count=data.get('count', 0)
+        )

deen_api_client-1.0.0/deen_api_client.egg-info/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: deen-api-client
+Version: 1.0.0
+Summary: Python client for Deen API from Imaniro.com - Islamic resources API
+Home-page: https://github.com/imaniro-tech/deen-api-python-client
+Author: Imaniro pvt ltd
+Author-email: info@imaniro.com
+Project-URL: Documentation, https://github.com/imaniro-tech/deen-api-python-client
+Project-URL: Source, https://github.com/imaniro-tech/deen-api-python-client
+Project-URL: Tracker, https://github.com/imaniro-tech/deen-api-python-client/issues
+Keywords: islamic,api,hadith,quran,dua,muslim
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Requires-Dist: dataclasses>=0.6; python_version < "3.7"
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0.0; extra == "dev"
+Requires-Dist: requests-mock>=1.9.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0.0; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Deen API Python Client
+
+A Python client for the Deen API, providing easy access to Islamic resources including Hadith, Quran verses, and Duas.
+
+## Installation
+
+```bash
+pip install deen-api-client
+```
+
+# Quick Start
+
+```python
+from deen_api import ImaniroDeenAPIClient
+
+# Initialize client with your API key
+client = ImaniroDeenAPIClient(api_key="sk_12345")
+
+# Get hadiths from Sahih al-Bukhari
+hadiths = client.get_hadiths(book="Sahih al-Bukhari", max_limits=5)
+
+for hadith in hadiths:
+    print(f"Book: {hadith.book}")
+    print(f"Chapter: {hadith.chapter}")
+    print(f"Text: {hadith.text}")
+    print(f"Translation: {hadith.translation}")
+    print("---")
+
+# Get Quran verses
+verses = client.get_quran_verses(surah="Al-Fatiha", max_limits=3)
+
+# Get Duas
+duas = client.get_duas(category="morning", max_limits=5)
+```
+
+# Features
+
+- Hadith Access: Retrieve hadiths from various books
+
+- Quran Verses: Access Quranic verses with translations(under development)
+
+- Islamic Duas: Get supplications for various occasions(under development)
+
+- Error Handling: Comprehensive exception handling
+
+# Error Handling
+
+The client provides specific exception types:
+
+```python
+from deen_api import AuthenticationError, RateLimitError, NotFoundError
+
+try:
+    hadiths = client.get_hadiths(book="Sahih al-Bukhari")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError:
+    print("Rate limit exceeded")
+except NotFoundError:
+    print("Resource not found")
+```
+
+## Example Usage Files
+
+### `examples/hadith_example.py`
+
+```python
+from deen_api import ImaniroDeenAPIClient
+
+def hadith_example():
+    client = ImaniroDeenAPIClient(api_key="sk_12345")
+
+    try:
+        # Get hadiths from Sahih al-Bukhari
+        hadiths = client.get_hadiths(book="Sahih al-Bukhari", max_limits=3)
+
+        print("Hadiths from Sahih al-Bukhari:")
+        for i, hadith in enumerate(hadiths, 1):
+            print(f"\n{i}. {hadith.hadith}")
+            print(f"Translation: {hadith.translation}")
+            print("-" * 50)
+
+    except Exception as e:
+        print(f"Error: {e}")
+
+if __name__ == "__main__":
+    hadith_example()
+```

deen_api_client-1.0.0/deen_api_client.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+setup.py
+deen_api/__init__.py
+deen_api/client.py
+deen_api/exceptions.py
+deen_api/models.py
+deen_api_client.egg-info/PKG-INFO
+deen_api_client.egg-info/SOURCES.txt
+deen_api_client.egg-info/dependency_links.txt
+deen_api_client.egg-info/requires.txt
+deen_api_client.egg-info/top_level.txt
+examples/__init__.py
+examples/hadith_example.py
+tests/__init__.py
+tests/test_client.py

deen_api_client-1.0.0/deen_api_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

deen_api_client-1.0.0/deen_api_client.egg-info/requires.txt

@@ -0,0 +1,9 @@
+requests>=2.25.0
+
+[:python_version < "3.7"]
+dataclasses>=0.6
+
+[dev]
+pytest>=6.0.0
+requests-mock>=1.9.0
+pytest-cov>=2.0.0

deen_api_client-1.0.0/deen_api_client.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+deen_api
+examples
+tests

deen_api_client-1.0.0/examples/hadith_example.py

@@ -0,0 +1,20 @@
+from deen_api import ImaniroDeenAPIClient
+
+def hadith_example():
+    client = ImaniroDeenAPIClient(api_key="sk_12345")
+    
+    try:
+        # Get hadiths from Sahih al-Bukhari
+        hadiths = client.get_hadiths(book="Sahih al-Bukhari", max_limits=3)
+        
+        print("Hadiths from Sahih al-Bukhari:")
+        for i, hadith in enumerate(hadiths, 1):
+            print(f"\n{i}. {hadith.hadith}")
+            print(f"Translation: {hadith.translation}")
+            print("-" * 50)
+            
+    except Exception as e:
+        print(f"Error: {e}")
+
+if __name__ == "__main__":
+    hadith_example()

deen_api_client-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

deen_api_client-1.0.0/setup.py

@@ -0,0 +1,47 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+with open("requirements.txt", "r", encoding="utf-8") as fh:
+    requirements = [line.strip() for line in fh if line.strip() and not line.startswith("#")]
+
+setup(
+    name="deen-api-client",
+    version="1.0.0",
+    author="Imaniro pvt ltd",
+    author_email="info@imaniro.com",
+    description="Python client for Deen API from Imaniro.com - Islamic resources API",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/imaniro-tech/deen-api-python-client",
+    packages=find_packages(),
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+    ],
+    python_requires=">=3.7",
+    install_requires=requirements,
+    extras_require={
+        "dev": [
+            "pytest>=6.0.0",
+            "requests-mock>=1.9.0",
+            "pytest-cov>=2.0.0",
+        ]
+    },
+    keywords="islamic, api, hadith, quran, dua, muslim",
+    project_urls={
+        "Documentation": "https://github.com/imaniro-tech/deen-api-python-client",
+        "Source": "https://github.com/imaniro-tech/deen-api-python-client",
+        "Tracker": "https://github.com/imaniro-tech/deen-api-python-client/issues",
+    },
+)

deen_api_client-1.0.0/tests/test_client.py

@@ -0,0 +1,47 @@
+import pytest
+import requests_mock
+from deen_api import ImaniroDeenAPIClient, Hadith
+from deen_api.exceptions import AuthenticationError, NotFoundError
+
+class TestDeenAPIClient:
+    def setup_method(self):
+        self.api_key = "test_key"
+        self.client = ImaniroDeenAPIClient(api_key=self.api_key)
+        self.base_url = "https://deen-api.imaniro.com/api/v1"
+    
+    def test_authentication_error(self):
+        with requests_mock.Mocker() as m:
+            m.post(f"{self.base_url}/hadiths", status_code=401)
+            
+            with pytest.raises(AuthenticationError):
+                self.client.get_hadiths(book="Sahih al-Bukhari")
+    
+    def test_get_hadiths_success(self):
+        mock_response = {
+            "success": True,
+            "data": [
+                {
+                    "book": "Sahih al-Bukhari",
+                    "number": "1",
+                    "narratedBy": "Abu Huraira",
+                    "translation": "Hadith translation...",
+                    "attribution": "Marfu",
+                    "authenticity": "sahih",
+                    "category": "Prayer",
+                    "context": "Hadith Context...",
+                    "explanation": "hadith Explanation...",
+                    "hadith": "الكَعْبَةَ وَأُسَامَةُ"
+                }
+            ],
+            "message": "Success",
+            "count": 1
+        }
+        
+        with requests_mock.Mocker() as m:
+            m.post(f"{self.base_url}/hadiths", json=mock_response)
+            
+            hadiths = self.client.get_hadiths(book="Sahih al-Bukhari")
+            
+            assert len(hadiths) == 1
+            assert isinstance(hadiths[0], Hadith)
+            assert hadiths[0].book == "Sahih al-Bukhari"