Add sphinx docs and blocks of methods, models

Author: Mateusz Woźnowski

simpay/baseModel.py

@@ -1,3 +1,4 @@
+from __future__ import annotations
 from typing import TypeVar, Generic
 from enum import Enum
 from pydantic import BaseModel
@@ -15,11 +16,33 @@ class RequestMethod(Enum):
 
 
 class ResponsePaginationLinks(BaseModel):
+    """Pagination links
+
+    :param next_page: str | None
+        Next page link
+    :param prev_page: str | None
+        Previous page link
+    """
     next_page: str | None
     prev_page: str | None
 
 
 class ResponsePagination(BaseModel):
+    """Request pagination
+
+    :param total: int
+        Total items in all pages
+    :param count: int
+        Count of items at current page
+    :param per_page: int
+        Limit of served items at one page
+    :param current_page: int
+        Current page
+    :param total_pages: int
+        Total pages at pagination
+    :param links: ResponsePaginationLinks
+        Pagination links (next page, previous page)
+    """
     total: int
     count: int
     per_page: int
@@ -29,6 +52,15 @@ class ResponsePagination(BaseModel):
 
 
 class Response(Generic[T]):
+    """Request response
+
+    :param success: bool
+        Determinate if request has been procesed successfully
+    :param data: any
+        Response body data, data can be list of items or object of item
+    :param pagination: ResponsePagination | none
+        Pagination
+    """
     success: bool = False
     data: T | None = None
     pagination: ResponsePagination | None

simpay/directbilling/models.py

@@ -1,3 +1,4 @@
+from __future__ import annotations
 from datetime import datetime
 from enum import Enum
 from pydantic import BaseModel
@@ -33,6 +34,17 @@ class DCB_Provider(Enum):
 
 
 class DCB_Service_Providers(BaseModel):
+    """DCB service available providers
+
+    :param tmobile: bool
+        Provider t-mobile available status, origin key from api's it's 't-mobile'
+    :param orange: bool
+        Type of service
+    :param play: bool
+        Name of service
+    :param plus: bool
+        Prefix of SMS
+    """
     tmobile: bool
     orange: bool
     play: bool
@@ -44,6 +56,17 @@ class Config:
 
 
 class DCB_Service_MaxValues(BaseModel):
+    """DCB service max values per single transaction
+
+    :param tmobile: str
+        Value for t-mobile provider, origin key from api's it's 't-mobile'
+    :param orange: str
+        Value for orange provider
+    :param play: str
+        Value for orange provider
+    :param plus: str
+        Value for orange provider
+    """
     tmobile: str
     orange: str
     play: str
@@ -55,12 +78,32 @@ class Config:
 
 
 class DCB_Service_Commission(BaseModel):
+    """DCB servicem stages of comission rates
+
+    :param commission_0: str
+        Commision rate from 0,01 PLN to 9,99 PLN amount of transaction
+    :param commission_9: str
+        Commision rate from 9 PLN to 24,99 PLN amount of transaction
+    :param commission_25: str
+        Commision rate from 25 PLN to max amount of transaction
+    """
     commission_0: str
     commission_9: str
     commission_25: str
 
 
 class DCB_Service_Commissions(BaseModel):
+    """DCB service comission rates
+
+    :param tmobile: DCB_Service_Commission
+        Commision rate for t-mobile provider, origin key from api's it's 't-mobile'
+    :param orange: DCB_Service_Commission
+        Commision rate for orange provider
+    :param play: DCB_Service_Commission
+        Commision rate for play provider
+    :param plus: DCB_Service_Commission
+        Commision rate for plus provider
+    """
     tmobile: DCB_Service_Commission
     orange: DCB_Service_Commission
     play: DCB_Service_Commission
@@ -72,12 +115,32 @@ class Config:
 
 
 class DCB_Service_Values(BaseModel):
+    """DCB service and transaction values
+
+    :param net: float
+        Amount net
+    :param gross: float
+        Amount gross
+    :param partner: float | None
+        Partner comission amount from transaction
+    """
     net: float
     gross: float
     partner: float | None
 
 
 class DCB_Service_CalculatedCommissions(BaseModel):
+    """DCB service calculated comissions
+
+    :param tmobile: DCB_Service_Values | None
+        Values for t-mobile provider, origin key from api's it's 't-mobile'
+    :param orange: DCB_Service_Values | None
+        Values for orange provider
+    :param play: DCB_Service_Values | None
+        Values for play provider
+    :param plus: DCB_Service_Values | None
+        Values for plus provider
+    """
     tmobile: DCB_Service_Values | None
     orange: DCB_Service_Values | None
     play: DCB_Service_Values | None
@@ -89,11 +152,39 @@ class Config:
 
 
 class DCB_Service_API(BaseModel):
+    """DCB service redirection urls
+
+    :param complete: str
+        Redirection url after complete transaction
+    :param failure: str
+        Redirection url after failure transaction
+    """
     complete: str
     failure: str
 
 
 class DCB_Service(BaseModel):
+    """DCB service
+
+    :param id: str
+        ID of DirectBilling service
+    :param name: str
+        Name of DirectBilling service
+    :param suffix: str
+        Suffix
+    :param status: DCB_Service_Status
+        Status
+    :param api: DCB_Service_API
+        API endpoints
+    :param providers: DCB_Service_Providers
+        Available providers
+    :param commissions: DCB_Service_Commissions
+        Commisions
+    :param maxValues: DCB_Service_MaxValues
+        Max values per transaction
+    :param created_at: datetime
+        Creation time of service
+    """
     id: str
     name: str
     suffix: str
@@ -106,21 +197,65 @@ class DCB_Service(BaseModel):
 
 
 class DCB_Transaction_Notify(BaseModel):
+    """DCB transaction notification states
+
+    :param is_send: str
+        Status whether notification has been sended
+    :param last_send_at: str
+        Date of last notification attempt
+    :param count: str
+        Count of notification attemps
+    """
     is_send: bool
     last_send_at: datetime
     count: int
 
 
 class DCB_Transaction_Returns(BaseModel):
+    """DCB transaction redirection urls
+
+    :param complete: str
+        URL where customer will be redirected after successful transaction
+    :param failure: str
+        URL where customer will be redirected after failure transaction
+    """
     complete: str
     failure: str
 
 
 class DCB_Transaction(BaseModel):
+    """DCB transaction
+
+    :param id: str
+        ID of DirectBilling of transaction
+    :param status: DCB_Transaction_Status
+        Status
+    :param phoneNumber: str | None
+        Phone number which transaction has been processed, original key from api it's number_from
+    :param control: str | None
+        Own custom property
+    :param value: float | None
+        Amount of transaction
+    :param value_netto: float | None
+        Amount of transaction (presented as netto value)
+    :param operator: str | None
+        Operator of transaction
+    :param returns: DCB_Transaction_Returns | None
+        Returns endpoints after successful or failure transaction
+    :param notify: DCB_Transaction_Notify | None
+        Nofication statuses
+    :param provider: int | None
+        ID of transaction provider
+    :param signature: str | None
+        Signature of transaction based on sha256
+    :param created_at: datetime | None
+        Creation date of transaction
+    :param updated_at: datetime | None
+        Update date of transaction
+    """
     id: str
     status: DCB_Transaction_Status
     phoneNumber: str | None
-    control: str | None
     value: float | None
     value_netto: float | None
     values: DCB_Service_Values | None
@@ -139,5 +274,12 @@ class Config:
 
 
 class DCB_GeneratedTransaction(BaseModel):
+    """DCB generating transaction callback
+
+    :param transactionId: str
+        Transaction ID
+    :param redirectUrl: str
+        Redirection url for transaction
+    """
     transactionId: str
     redirectUrl: str

simpay/simpay.py

@@ -1,3 +1,4 @@
+from __future__ import annotations
 from .__version__ import VERSION
 from simpay.baseModel import RequestMethod, Response
 from simpay.sms.client import SMSClient
@@ -71,15 +72,19 @@ def __init__(
         """
         self.DirectBilling: DirectBillingClient = DirectBillingClient(self)
 
-    def request(self, method: RequestMethod, uri: str, fields: dict[str, any] | None = None, headers: dict[str, any] | None = None, options: dict[str, any] | None = None) -> Response:
-        """Base client of SimPay
+    def request(self, method: RequestMethod, uri: str, fields: dict[str, any] | None = None, headers: dict[str, any] | None = None, options: dict[str, any] | None = None) -> dict:
+        """HTTP request builder
 
         :param method: RequestMethod
             HTTP request method (GET, POST, ...)
-        :param api_password: str
-            API password from account details
-        :param timeout: int
-            Timeout of HTTP request, default its 5 seconds
+        :param uri: str
+            API endpoint uri without base url
+        :param fields: dict[str, any]
+            HTTP POST fields (converted into JSON body content type)
+        :param headers: dict[str, any]
+            HTTP request headers
+        :param options: dict[str, any]
+            HTTP request builder options like pagination page, per page items
 
         :return Response body
         :rtype dict
@@ -96,7 +101,23 @@ def request(self, method: RequestMethod, uri: str, fields: dict[str, any] | None
                 raise ClientException(response.status_code)
         return response.json()
 
-    def requestAllPages(self, method: RequestMethod, uri: str, fields: dict[str, any] | None = None, headers: dict[str, any] | None = None, options: dict[str, any] | None = None) -> object:
+    def requestAllPages(self, method: RequestMethod, uri: str, fields: dict[str, any] | None = None, headers: dict[str, any] | None = None, options: dict[str, any] | None = None) -> list:
+        """HTTP request builder with auto fetch pagination all pages
+
+        :param method: RequestMethod
+            HTTP request method (GET, POST, ...)
+        :param uri: str
+            API endpoint uri without base url
+        :param fields: dict[str, any]
+            HTTP POST fields (converted into JSON body content type)
+        :param headers: dict[str, any]
+            HTTP request headers
+        :param options: dict[str, any]
+            HTTP request builder options like pagination page, per page items
+
+        :return Response body items
+        :rtype list
+        """
         response = self.request(method, uri, fields, headers, options)
         responseData = []
         if response['success']: