added documention and README.md and CONTRIBUTING.md

Author: Aazerra

CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing to YourPackageName
+
+Thank you for considering contributing to **YourPackageName**! Contributions are what make open-source software great, and your help is highly appreciated.
+
+## How to Contribute
+
+### 1. Report Issues
+
+If you encounter a bug, have a question, or want to suggest a feature:
+- Check the [issues page](https://github.com/zohal/python-zohal-sdk/issues) to see if it has already been reported.
+- If not, open a new issue with the following details:
+  - **Title**: A concise description of the issue.
+  - **Description**: Steps to reproduce the issue or the details of the feature request.
+  - **Environment**: Include Python version, OS, and any other relevant information.
+
+### 2. Submit Code Changes
+
+#### Fork the Repository
+1. Go to the [repository](https://github.com/zohal/python-zohal-sdk) and fork it.
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/your_username/your_fork.git
+   cd your_fork
+   ```
+
+#### Create a Branch
+Create a new branch for your changes:
+```bash
+git checkout -b feature/your-feature-name
+```
+
+#### Make Changes
+- Follow the project's coding style (adhering to [PEP 8](https://www.python.org/dev/peps/pep-0008/)).
+- Write clear and concise commit messages. Use present tense, e.g., "Add feature X."
+
+#### Run Tests
+Ensure your changes do not break existing functionality by running the test suite:
+```bash
+pytest
+```
+If you add a new feature, include relevant tests.
+
+#### Push Changes
+Push your changes to your forked repository:
+```bash
+git push origin feature/your-feature-name
+```
+
+#### Open a Pull Request
+1. Go to the original repository and click "New Pull Request."
+2. Select your branch and provide a clear description of your changes.
+
+
+## Development Environment
+
+To set up a local development environment:
+1. Clone the repository.
+2. Install dependencies:
+   ```bash
+   poetry install
+   ```
+3. Run tests to confirm everything is working:
+   ```bash
+   pytest
+   ```
+
+## Thank You
+
+Thank you for taking the time to contribute! Your efforts make this project better for everyone.

README.md

@@ -0,0 +1,40 @@
+# zohal-sdk
+[![PyPi Package Version](https://img.shields.io/pypi/v/zohal-sdk.svg)](https://pypi.python.org/pypi/zohal-sdk)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/zohal-sdk.svg)](https://pypi.python.org/pypi/zohal-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![PyPi status](https://img.shields.io/pypi/status/zohal-sdk.svg?style=flat-square)](https://pypi.python.org/pypi/zohal-sdk)
+
+## Overview
+
+zohal-sdk is a Python SDK for interfacing with [zohal.io](https://zohal.io). It simplifies the process of interacting with the API by providing clean, Pythonic abstractions for all key functionalities.
+
+## Installation
+
+Install the SDK using pip:
+
+```bash
+pip install zohal-sdk
+```
+## Getting Started
+
+Here's a quick example to get you started:
+```python
+from zohal_sdk import Client
+
+# Initialize the client
+client = Client(token="your_api_key")
+
+# Example usage
+response = client.shahkar(mobile="your mobile number", national_code="your national code")
+print(response)
+```
+For detailed usage, check the documentation.
+Documentation
+
+## Documentation
+
+Full documentation is available at [Documentation]().
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

zohal_sdk/client.py

@@ -1,10 +1,9 @@
 """ Zohal RestAPI Client """
 from typing import Union
-import io
 from .types import RequestData
 import logging
 
-from requests import Session
+from requests import Session, Response
 from requests.exceptions import (Timeout, HTTPError as RHTTPError,
                                  JSONDecodeError)
 
@@ -15,6 +14,12 @@
 
 
 class Client(InquiryMixin):
+    """
+    Client class for zohal API
+
+    :param token: Token of Zohal API, should be obatined from zohal.io
+    :raises ValueError: if token is not specified
+    """
 
     def __init__(self, token: str):
         if token is None:
@@ -28,7 +33,7 @@ def request(self,
                 url: str,
                 data: Union[RequestData, dict, None] = None,
                 files=None,
-                method: str = "GET"):
+                method: str = "GET") -> Response:
         logger.debug(f"request to {url=} with {method=}")
         try:
             kwargs = {"url": url, "method": method}

zohal_sdk/exceptions.py

@@ -3,12 +3,21 @@
 
 
 class TimeoutError(Timeout):
+    """
+    Raises when api request has been timeout.
+        """
     pass
 
 
 class HTTPError(RHTTPError):
+    """
+    Any HTTPError happen during requests gonna be instance of this error.
+    """
     pass
 
 
 class ZohalError(Exception):
+    """
+    Internal Error or Any Error that came from zohal api.
+    """
     pass

zohal_sdk/services/inquiry.py

@@ -1,3 +1,5 @@
+"""InquiryMixin is a mixin for client to add inquiry requests"""
+
 from typing import Optional, Union
 import io
 
@@ -34,6 +36,16 @@ def national_identity_inquiry(
             national_code: str,
             birth_date: str,
             gender: Optional[bool] = None) -> ResponseData[NationalIdentity]:
+        """
+        National Identity inquiry service
+        inquiry national_code with birth_date to see if its valid or not.
+
+        :param national_code: National code
+        :param birth_date: birth date in YYYY/MM/DD format
+        :param gender: if its true its gonna return gender otherwise it doesnt
+        :returns: national identity data
+        :rtype: ResponseData<NationalIdentity>
+        """
         data = NationalIdentityInqueryRequest(national_code=national_code,
                                               birth_date=birth_date,
                                               gender=gender)
@@ -45,6 +57,15 @@ def national_identity_inquiry(
 
     def shahkar(self, national_code: str,
                 mobile: str) -> ResponseData[Shahkar]:
+        """
+        Shahkar
+        inquiry mobile number with national_code to see if its valid or not.
+
+        :param mobile: mobile number
+        :param national_code: national_code
+        :returns: true if its matched.
+        :rtype: ResponseData<Shahkar>
+        """
         data = ShahkarRequest(national_code=national_code, mobile=mobile)
         response = self.request(make_url(self.service_name, "shahkar"),
                                 data,
@@ -53,17 +74,37 @@ def shahkar(self, national_code: str,
 
     def national_card_ocr(self, national_card_back: Union[io.FileIO, str],
                           national_card_front: Union[io.FileIO, str]):
+        """
+        National card ocr
+        uses OCR on national card to return data of national card and photo of person from national card
+
+        :param national_card_front: front of national card
+        :param national_card_back: back of national card
+        :returns: National card data.
+        :rtype: ResponseData<NationalCard>
+        """
         response = self.request(make_url(self.service_name,
                                          "national_card_ocr"),
                                 files={
                                     "national_card_back": national_card_back,
                                     "national_card_front": national_card_front,
-                                }, method="POST")
+                                },
+                                method="POST")
         return ResponseData.serialize(NationalCard, response)
 
     def check_card_with_national_code(
             self, national_code: str, birth_date: str,
             card_number: str) -> ResponseData[Matched]:
+        """
+        Check Card with National Code
+        inquiry card number with national code to see if its matches or not
+
+        :param national_code: national code
+        :param card_number: card number
+        :param birth_date: birth date
+        :returns: if matches returns true.
+        :rtype: ResponseData<Matched>
+        """
         data = CheckCardWithNationalCodeRequest(national_code=national_code,
                                                 birth_date=birth_date,
                                                 card_number=card_number)
@@ -74,13 +115,29 @@ def check_card_with_national_code(
         return ResponseData.serialize(Matched, response)
 
     def card_to_iban(self, card_number: str) -> ResponseData[IBan]:
+        """
+        Card to IBan
+        uses card_number to return IBan
+
+        :param card_number: card number
+        :returns: if its successful returns iban.
+        :rtype: ResponseData<IBan>
+        """
         data = CardToIBANRequest(card_number=card_number)
         response = self.request(make_url(self.service_name, "card_to_iban"),
                                 data,
                                 method="POST")
         return ResponseData.serialize(IBan, response)
 
     def card_to_account(self, card_number: str) -> ResponseData[BankAccount]:
+        """
+        Card to Account
+        uses card_number to return account
+
+        :param card_number: card number
+        :returns: if its successful returns account.
+        :rtype: ResponseData<BankAccount>
+        """
         data = CardToAccountRequest(card_number=card_number)
         response = self.request(make_url(self.service_name, "card_to_account"),
                                 data,
@@ -89,46 +146,99 @@ def card_to_account(self, card_number: str) -> ResponseData[BankAccount]:
 
     def iban(self,
              iban: str,
-             separated: Optional[bool] = None) -> ResponseData:
+             separated: Optional[bool] = None) -> ResponseData[IBANInquiry]:
+        """
+        IBan inquiry
+        Inquiry to check iban is valid or not
+
+        :param iban: iban
+        :param separated: if its true returning name as separated
+        :returns: if its successful returns iban.
+        :rtype: ResponseData<IBANInquiry>
+        """
         data = IBANRequest(iban=iban, separated=separated)
         response = self.request(make_url(self.service_name, "iban"),
                                 data,
                                 method="POST")
         return ResponseData.serialize(IBANInquiry, response)
 
     def card_inquiry(self, card_number) -> ResponseData:
+        """
+        card inquiry
+        Inquiry to check card is valid or not
+
+        :param card_number: card number
+        :returns: if its successful returns Card.
+        :rtype: ResponseData<Card>
+        """
         data = CardInquiryRequest(card_number=card_number)
         response = self.request(make_url(self.service_name, "card_inquiry"),
                                 data,
                                 method="POST")
         return ResponseData.serialize(Card, response)
 
     def check_card_with_name(self, card_number: str,
-                             name: str) -> ResponseData:
+                             name: str) -> ResponseData[Matched]:
+        """
+        check card with name
+        Inquiry to check card with name it matches or not
+
+        :param card_number: card number
+        :param name: name
+        :returns: if it matches returns true.
+        :rtype: ResponseData<Matched>
+        """
         data = CheckCardWithNameRequest(card_number=card_number, name=name)
         response = self.request(make_url(self.service_name,
                                          "check_card_with_name"),
                                 data,
                                 method="POST")
         return ResponseData.serialize(Matched, response)
 
-    def check_iban_with_name(self, iban: str, name: str) -> ResponseData:
+    def check_iban_with_name(self, iban: str,
+                             name: str) -> ResponseData[Matched]:
+        """
+        check iban with name
+        Inquiry to check iban with name it matches or not
+
+        :param iban: Iban
+        :param name: name
+        :returns: if it matches returns true.
+        :rtype: ResponseData<Matched>
+        """
         data = CheckIBANWithNameRequest(IBAN=iban, name=name)
         response = self.request(make_url(self.service_name,
                                          "check_iban_with_name"),
                                 data,
                                 method="POST")
         return ResponseData.serialize(Matched, response)
 
-    def postal_code_inquiry(self, postal_code: str) -> ResponseData:
+    def postal_code_inquiry(self,
+                            postal_code: str) -> ResponseData[PostalCode]:
+        """
+        postal code inquiry
+        Inquiry to retrive postal code data
+
+        :param postal_code: Postal code
+        :returns: if its ok returns data of that postal_code.
+        :rtype: ResponseData<PostalCode>
+        """
         data = PostalCodeInquiry(postal_code=postal_code)
         response = self.request(make_url(self.service_name,
                                          "postal_code_inquiry"),
                                 data,
                                 method="POST")
         return ResponseData.serialize(PostalCode, response)
 
-    def persian_to_finglish(self, persian_text: str) -> ResponseData:
+    def persian_to_finglish(self, persian_text: str) -> ResponseData[Finglish]:
+        """
+        persian to finglish
+        transform persian text to finglish text
+
+        :param persian_text: Persian text
+        :returns: if its successful returns finglish text.
+        :rtype: ResponseData<Finglish>
+        """
         data = PersianToFinglishRequest(persian_text=persian_text)
         response = self.request(make_url(self.service_name,
                                          "persian_to_finglish"),
@@ -138,6 +248,15 @@ def persian_to_finglish(self, persian_text: str) -> ResponseData:
 
     def account_to_iban(self, bank_account: str,
                         bank_code: BankCode) -> ResponseData[IBan]:
+        """
+        account to iban
+        Inquiry to retrive iban from bank_account
+
+        :param bank_account: account number
+        :param bank_code: BankCode
+        :returns: returns Iban data.
+        :rtype: ResponseData<IBan>
+        """
         data = AccountToIBANRequest(bank_account=bank_account,
                                     bank_code=bank_code)
         response = self.request(make_url(self.service_name, "account_to_iban"),