Adding docs using sphinx

This one is for source code documentation. So going forward will try to document each thing. Its good point of learning and will help others.

core/__init__.py

@@ -1,21 +1,33 @@
-import json
-
 from core.resources import UserDomain, UserAgent
 
-from core.recon.domain_available import DomainAvailable as domain_availability
-from core.recon.dns_history import DnsHistory as domain_host_history
+from core.recon.domain_available import DomainAvailable as DomainAvailability
+from core.recon.dns_history import DnsHistory as DomainHostHistory
 from core.parser import ColorPrint
-from core.recon.services.dnslg import DnsLG as DnsInformation
-
-
-def index_in_list(a_list, index):
+from core.recon.dnslg import DnsLG as DomainDnsInformation
+
+
+def index_in_list(a_list: list, index: int):
+    '''
+    This function is to check if some index exists inside a list.
+    :param a_list: List of items
+    :type a_list: list
+    :param index: index pointer which needs be checked on list
+    :type index: int
+    :return: True / False
+    :rtype: bool
+    '''
     return index < len(a_list)
 
 
-def print_table(table_data):
-    if isinstance(table_data, dict):
-        table_data = table_data["records"]
-        print(table_data)
+def print_table(table_data: list):
+    '''
+    We use this function to create table for printing information on console / terminal. We will be calculating
+    column's information, separator and designing layout. After calculation this function will print information
+    on terminal.
+    :param table_data: table data in shape of list
+    :type table_data: list
+    '''
+
     sep_index = []
     for row in table_data:
         l_row = len(row)
@@ -55,7 +67,15 @@ def print_table(table_data):
         print(output_line)
 
 
-def dict_to_table(dict_data):
+def dict_to_table(dict_data: dict):
+    '''
+    This function converts dictionary data into list. This function is normally used to prepare data before printing
+    on console/ terminal.
+    :param dict_data: dictionary based data from different sources
+    :type dict_data: dict
+    :return: list based data is returned to caller
+    :rtype: list
+    '''
     table_data = []
     t_keys = []
     for row in dict_data:
@@ -68,12 +88,22 @@ def dict_to_table(dict_data):
     return table_data
 
 
-def ProcessRequest():
-    domain = UserDomain.DOMAIN
+def process_request():
+    '''
+    This function is responsible for calling all the configured module and services in project. Following services are
+    called by the function,
+    1. DomainAvailability
+    2. DomainHostHistory
+    3. DomainDnsInformation
+
+    Function later calls printing function to display all content
+
+    '''
+    domain = UserDomain.domain
 
     ColorPrint.print_bold("Printing Results for domain %s" % domain)
 
-    is_domain_available = domain_availability(domain)
+    is_domain_available = DomainAvailability(str(domain))
     response = is_domain_available.domain_available
     if isinstance(response, bool):
         if response:
@@ -83,10 +113,10 @@ def ProcessRequest():
     else:
         _info = "unable to find result."
 
-    ColorPrint.print_info("\nDomain Availability Result for %s : %s\n" % (domain, _info))
+    ColorPrint.print_info("Domain Availability Result for %s : %s" % (domain, _info))
 
-    dns_history = domain_host_history(domain)
-    __domain_history = json.loads(dns_history.domain_history)
+    dns_history = DomainHostHistory(str(domain))
+    __domain_history = dns_history.domain_history()
 
     if __domain_history:
         ColorPrint.print_info("DNS History Records")
@@ -107,17 +137,19 @@ def ProcessRequest():
             )
         print_table(table_data)
 
-    dns_information = DnsInformation(domain)
-    dns_records = dns_information.get_report()
+    dns_information = DomainDnsInformation(str(domain))
+    dns_records = dns_information.download_report()
 
     for dns_record in dns_records:
-        record = dns_records[dns_record]
-        print("")
-        ColorPrint.print_info(record["title"])
-
-        records = record["records"]
+        try:
+            record = dns_records[dns_record]
+            ColorPrint.print_info(record["title"])
 
-        print_table(dict_to_table(records))
+            records = record["records"]
+            print_table(dict_to_table(records))
+        except TypeError:
+            # @TODO: Check which kind of records are failing while converting into table and printing process
+            pass
 
 
-__all__ = ["UserDomain", "UserAgent", "ProcessRequest", "DnsInformation"]
+__all__ = ["UserDomain", "UserAgent", "process_request", "DomainHostHistory"]

core/parser/__init__.py

@@ -4,21 +4,46 @@
 
 
 class UrlParser:
+    """
+    Class addresses cosmetic settings for an url. Different online services requires different shape of url so
+    this class generally contains different function which beautify url/domain according to its requirement.
+    """
 
     def __init__(self):
+        """
+        Setting url value to None
+        """
         self.__url = None
 
     @property
-    def url(self):
+    def url(self) -> str:
+        """
+        it returns url which was set before
+        :return: domain / url
+        :rtype: str
+        """
+
         return self.__url
 
     @url.setter
-    def url(self, u_url):
+    def url(self, u_url: str) -> None:
+        """
+        setter for url
+        :param u_url: url as input of function
+        :type u_url: str
+        """
         self.__url = u_url
 
     @property
-    def root_url(self):
+    def root_url(self) -> str:
+        """
+        This property function extracts root domain from given url
+
+        :return: domain e.g. www.google.com
+        :rtype: str
+        """
         url = self.__url
+
         if str(url).startswith("https://"):
             url = str(url).replace("https://", "")
         if str(url).startswith("http://"):
@@ -34,19 +59,33 @@ def root_url(self):
         url = url.split("/")
         if len(url) > 1:
             return url[0]
-        return url
+        return url[0]
 
 
 url_parser = UrlParser()
 
 
-def domain_for_md(domain):
+def domain_for_md(domain: str) -> str:
+    """
+    This function prepares domain for domain availability checking service.
+    :param domain: takes input in any shape of urls e.g. http://www.example.com, https://www.example.com:8080
+    :type domain: str
+    :return: root of domain e.g. www.example.com
+    :rtype: str
+    """
     url_parser.url = domain
     domain = url_parser.root_url
     return domain
 
 
-def domain_for_history(domain):
+def domain_for_history(domain: str) -> str:
+    """
+    This function prepares domain for domain history checking service.
+    :param domain: takes input in any shape of urls e.g. http://www.example.com, https://www.example.com:8080
+    :type domain: str
+    :return: simplified  domain e.g. example.com
+    :rtype: str
+    """
     url_parser.url = domain
     domain = url_parser.root_url
     if domain.startswith("www."):
@@ -55,26 +94,75 @@ def domain_for_history(domain):
 
 
 class ColorPrint:
+    """
+    This class provides support for color printing text in console.
+    """
 
     @staticmethod
-    def print_fail(message, end='\n'):
+    def print_fail(message: str, end: str = '\n') -> None:
+        """
+        Print text in red color in console
+        :param message: message which needs to be printed on console.
+        :type message: str
+        :param end: new line
+        :type end: str
+        :return: None
+        :rtype: None
+        """
         sys.stderr.write('\x1b[1;31m' + message.strip() + '\x1b[0m' + end)
 
     @staticmethod
-    def print_pass(message, end='\n'):
+    def print_pass(message: str, end: str = '\n') -> None:
+        """
+        Print text in green color in console
+        :param message: message which needs to be printed on console.
+        :type message: str
+        :param end: new line
+        :type end: str
+        :return: None
+        :rtype: None
+        """
+
         sys.stdout.write('\x1b[1;32m' + message.strip() + '\x1b[0m' + end)
 
     @staticmethod
-    def print_warn(message, end='\n'):
+    def print_warn(message: str, end: str = '\n') -> None:
+        """
+         Print text in warning color in console
+        :param message: message which needs to be printed on console.
+        :type message: str
+        :param end: new line
+        :type end: str
+        :return: None
+        :rtype: None
+        """
         sys.stderr.write('\x1b[1;33m' + message.strip() + '\x1b[0m' + end)
 
     @staticmethod
-    def print_info(message, end='\n'):
-        sys.stdout.write('\x1b[1;34m' + message.strip() + '\x1b[0m' + end)
+    def print_info(message: str, end: str = '\n') -> None:
+        """
+         Print text in green color in console
+        :param message: message which needs to be printed on console.
+        :type message: str
+        :param end: new line
+        :type end: str
+        :return: None
+        :rtype: None
+        """
+        sys.stdout.write('\x1b[1;34m' + "\n" + message.strip() + "\n" + '\x1b[0m' + end)
 
     @staticmethod
-    def print_bold(message, end='\n'):
+    def print_bold(message: str, end: str = '\n') -> None:
+        """
+         Print text in bold format in console
+        :param message: message which needs to be printed on console.
+        :type message: str
+        :param end: new line
+        :type end: str
+        :return: None
+        :rtype: None
+        """
         sys.stdout.write('\x1b[1;37m' + message.strip() + '\x1b[0m' + end)
 
 
-__all__ = ["HistoryWebParser", "domain_for_history", "ColorPrint"]
+__all__ = ["HistoryWebParser", "domain_for_history", "ColorPrint", "domain_for_md"]

core/parser/html_parser.py

@@ -1,14 +1,30 @@
-import json
 import re
 
+from typing import Tuple
+
 
 class DnsHistoryParser:
+    """
+    Custom parser written for extracting data from html.
+    """
 
-    def __init__(self, html_content):
+    def __init__(self, html_content: str):
+        """
+        initiating function with some html content data
+        :param html_content: html data
+        :type html_content: str
+        """
         self.__html = html_content
 
     @staticmethod
-    def __ext_table_data__(web_content):
+    def __ext_table_data__(web_content: str) -> Tuple[list, int]:
+        """
+        This function extracts tables from html content, it creates a list and append all extracted tables in it.
+        :param web_content: string based html content
+        :type web_content:  str
+        :return html_tables, max_table_length: list of extracted tables, number of tables in table list
+        :rtype html_tables, max_table_length: list, int
+        """
         web_content = str(web_content)
         html_tables = []
         max_table_length = 0
@@ -40,8 +56,12 @@ def __ext_table_data__(web_content):
             found_tables = re.search(html_table_regex, web_content, re.DOTALL)
         return html_tables, max_table_length
 
-    @property
-    def report(self):
+    def parse(self) -> list:
+        """
+        This functions invokes parsing of html content
+        :return: historical records against website
+        :rtype: object
+        """
         extracted_html_tables, max_len = self.__ext_table_data__(self.__html)
         history_data = []
         if len(extracted_html_tables) > 0:
@@ -83,8 +103,7 @@ def report(self):
                                 "month_year": str(extract_row_record[2]).lower().rstrip().strip(),
                                 "zone_date": str(extract_row_record[3]).lower().rstrip().strip(),
                                 "transaction": str(extract_row_record[4]).lower().rstrip().strip(),
-
                             }
                             history_data.append(host_record)
 
-        return json.dumps(history_data)
+        return history_data