Merge pull request #13 from WilliamOtieno/develop

finalized docs

Author: WilliamOtieno

README.md

@@ -1,18 +1,14 @@
 ### python-flutterwave
+
 - This lib aims to be the middleman between `Flutterwave API` and a python backend. Ergo, it directly makes the API requests to FW and returns the necessary info to the backend.
+
 - One should thoroughly go through the [official docs here](https://developer.flutterwave.com/reference/introduction) in order to have a meaningful insight on how to use the params provided by the functions in the lib.
+
 - The lib will also follow the same project structure as the official docs for ease of use and consistency.
 
 - NB: Set `FW_SECRET_KEY` environnment variable obtained from the dashboard.
-  ## Quick Example.
 
-  ```python
-  from python_flutterwave.charge import initiate_apple_pay_charge, validate_charge
+- Full package documentation can be accessed from [here](https://python-flutterwave.readthedocs.io/en/latest/)
 
-  details = initiate_apple_pay_charge(tx_ref="your_unique_ref", amount=20, email="johndoe@example.com", currency="USD")
-  print(details)
-  validation_details = validate_charge(flw_ref="qwerty", otp="123456")
-  print(validation_details)
-  ```
 
-- More contributors needed, refer to [the contribution gude](/CONTRIBUTING.md)
+- More contributors needed, refer to [the contribution gude](/CONTRIBUTING.md)

docs/.DS_Store

@@ -21,6 +21,8 @@
 
 extensions = ["sphinx.ext.todo", "sphinx.ext.viewcode", "sphinx.ext.autodoc"]
 
+autodoc_decorators = True
+
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 

docs/conf.py

@@ -20,7 +20,9 @@ def initiate_bank_charge(
 
     Args:
         tx_ref (int): This is a unique reference peculiar to the transaction being carried out.
+
         amount (int): This is the amount to be charged for the transaction.
+        
         email (str): The customer's email address.
 
     Returns: 
@@ -53,7 +55,9 @@ def initiate_nigeria_bank_charge(
 
     Args:
         tx_ref (int): This is a unique reference peculiar to the transaction being carried out.
+        
         amount (int): This is the amount to be charged for the transaction.
+        
         email (str): The customer's email address.
 
     Returns: 
@@ -84,9 +88,13 @@ def initiate_uk_eu_bank_charge(
 
     Args:
         tx_ref (int): Unique reference peculiar to the transaction.
+        
         amount (int): Amount to be charged for the transaction.
+        
         email (str): The customer's email address.
+        
         phone_number (str): Phone number linked to the customer's bank account or mobile money account
+        
         is_token_io (int):
 
     Returns: 
@@ -123,9 +131,13 @@ def initiate_ach_bank_charge(
 
     Args:
         tx_ref (int): Unique reference peculiar to the transaction.
+        
         amount (int): Amount to be charged for the transaction.
+        
         email (str): The customer's email address.
+        
         phone_number (str): Phone number linked to the customer's bank account or mobile money account
+        
         currency (str): Currency to charge in. Expected values are ZAR for ZA ACH and USD for US ACH.
 
     Returns: 

python_flutterwave/charge/bank.py

@@ -24,11 +24,17 @@ def initiate_card_charge(
     
     Args:
         tx_ref (int): This is a unique reference peculiar to the transaction being carried out.
+
         amount (int): This is the amount to be charged for the transaction.
+
         email (str): The customer's email address.
+
         card_number (int): The customer's card.
+
         cvv (int): Card CVV.
+
         expiry_month (int): Card expiry month
+
         expiry_year (int): Card expiry year
 
     Returns: 

python_flutterwave/charge/card.py

@@ -18,8 +18,11 @@ def initiate_mpesa_charge(
     
     Args:
         tx_ref (int): Unique reference peculiar to the transaction.
+        
         amount (int): Amount to be charged for the transaction.
+        
         email (str): The customer's email address.
+        
         phone_number (str): Phone number linked to the customer's bank account or mobile money account
 
     Returns: 
@@ -52,9 +55,13 @@ def initiate_ghana_mobile_charge(
     
     Args:
         tx_ref (int): Unique reference peculiar to the transaction.
+        
         amount (int): Amount to be charged for the transaction.
+        
         email (str): The customer's email address.
+        
         phone_number (str): Phone number linked to the customer's bank account or mobile money account
+        
         network (str): Mobile money network provider (MTN, VODAFONE, TIGO)
 
     Returns: 
@@ -91,8 +98,11 @@ def initiate_uganda_mobile_charge(
     
     Args:
         tx_ref (int): Unique reference peculiar to the transaction.
+        
         amount (int): Amount to be charged for the transaction.
+        
         email (str): The customer's email address.
+        
         phone_number (str): Phone number linked to the customer's bank account or mobile money account
 
     Returns: 
@@ -130,10 +140,15 @@ def initiate_franco_mobile_charge(
     
     Args:
         tx_ref (int): Unique reference peculiar to the transaction.
+        
         amount (int): Amount to be charged for the transaction.
+        
         email (str): The customer's email address.
+        
         phone_number (str): Phone number linked to the customer's bank account or mobile money account
+        
         currency (str): Currency to charge in. 
+        
         franco_country_code (str): Country code (BF, CI, CM, SN)
 
     Returns: 
@@ -170,8 +185,11 @@ def initiate_tanzania_mobile_charge(
     
     Args:
         tx_ref (int): Unique reference peculiar to the transaction.
+        
         amount (int): Amount to be charged for the transaction.
+        
         email (str): The customer's email address.
+        
         phone_number (str): Phone number linked to the customer's bank account or mobile money account
 
     Returns: 
@@ -204,9 +222,13 @@ def initiate_rwanda_mobile_charge(
     
     Args:
         tx_ref (int): Unique reference peculiar to the transaction.
+        
         amount (int): Amount to be charged for the transaction.
+        
         email (str): The customer's email address.
+        
         phone_number (str): Phone number linked to the customer's bank account or mobile money account
+        
         order_id (str): Unique ref for the mobilemoney transaction to be provided by the merchant
 
     Returns: 
@@ -243,8 +265,11 @@ def initiate_zambia_mobile_charge(
     
     Args:
         tx_ref (int): Unique reference peculiar to the transaction.
+        
         amount (int): Amount to be charged for the transaction.
+        
         email (str): The customer's email address.
+        
         phone_number (str): Phone number linked to the customer's bank account or mobile money account
 
     Returns: 
@@ -281,9 +306,13 @@ def initiate_ussd_charge(
 
     Args:
         tx_ref (int): Unique reference peculiar to the transaction.
+        
         amount (int): Amount to be charged for the transaction.
+        
         email (str): The customer's email address.
+        
         account_bank (str): Bank numeric code. It can be gotten from the banks endpoint.
+        
         phone_number (str): Phone number linked to the customer's bank account or mobile money account
 
     Returns: 
@@ -320,8 +349,11 @@ def initiate_apple_pay_charge(
     
     Args:
         tx_ref (int): Unique reference peculiar to the transaction.
+        
         amount (int): Amount to be charged for the transaction.
+        
         email (str): The customer's email address.
+        
         currency (str): Currency to charge in. 
 
     Returns: 
@@ -356,8 +388,11 @@ def initiate_google_pay_charge(
     
     Args:
         tx_ref (int): Unique reference peculiar to the transaction.
+        
         amount (int): Amount to be charged for the transaction.
+        
         email (str): The customer's email address.
+        
         currency (str): Currency to charge in. 
 
     Returns: 
@@ -391,7 +426,9 @@ def initiate_enaira_charge(
     
     Args:
         tx_ref (int): This is a unique reference peculiar to the transaction being carried out.
+        
         amount (int): This is the amount to be charged for the transaction.
+        
         email (str): The customer's email address.
 
     Returns: 
@@ -424,7 +461,9 @@ def initiate_fawry_pay_charge(
     
     Args:
         tx_ref (int): This is a unique reference peculiar to the transaction being carried out.
+        
         amount (int): This is the amount to be charged for the transaction.
+        
         email (str): The customer's email address.
 
     Returns: 
@@ -459,9 +498,13 @@ def initiate_paypal_charge(
     
     Args:
         tx_ref (int): Unique reference peculiar to the transaction.
+        
         amount (int): Amount to be charged for the transaction.
+        
         email (str): The customer's email address.
+        
         currency (str): Currency to charge in.
+    
     Returns: 
         dict: Response Details
     """

python_flutterwave/charge/mobile.py

@@ -13,6 +13,7 @@ def validate_charge(otp: str, flw_ref: str) -> dict:
     
     Args:
         flw_ref (str): Reference returned in the initiate charge call as `data.flw_ref`
+        
         otp (str): Random number of at least 6 characters sent to customers phone number.
 
     Returns: 

python_flutterwave/charge/validation.py

@@ -1,12 +1,15 @@
 import os
 import requests
+from functools import wraps
 from .exceptions import TokenException, FlutterwaveAPIException
 
 
 token = os.environ.get("FW_SECRET_KEY")
 
 
 def require_token(func):
+    """Ascertain existence of the auth token"""
+    @wraps(func)
     def wrapper(*args, **kwargs):
         if token == "" or token is None:
             raise TokenException(token=token, message="Authentication token absent")
@@ -16,6 +19,8 @@ def wrapper(*args, **kwargs):
 
 
 def handle_api_exceptions(func):
+    """Raise exceptions whenever necessary"""
+    @wraps(func)
     @require_token
     def wrapper(*args, **kwargs):
         try:

python_flutterwave/decorators.py

@@ -17,9 +17,13 @@ def initiate_tokenized_charge(
    	
     Args:
         tx_ref (int): Unique reference peculiar to the transaction.
+        
         amount (int): Amount to be charged for the transaction.
+        
         email (str): The customer's email address.
+        
         currency (str): Currency to be used
+        
         token (str): Card token returned from the transaction verification endpoint as data.card.token
 
     Returns: 
@@ -58,6 +62,7 @@ def initiate_bulk_tokenized_charges(
 
     Args:
         retry_strategy: RetryStrategy
+        
         bulk_data: list[ChargeData]
     
     Returns:
@@ -141,8 +146,11 @@ def update_card_token(email: str, full_name: str, phone_number: str, token: str)
    	
     Args:
         email (str): The customer's email address.
+        
         full_name (str): The customer's email address.
+        
         phone_number (str): Customer's phone number.
+        
         token (str): Card token returned from the transaction verification endpoint as data.card.token
 
     Returns: