added a bunch of docstrings and comments for things

hyperglass/__init__.py

@@ -1 +1 @@
-#!/usr/bin/env python3
+name = "hyperglass"

hyperglass/command/construct.py

@@ -9,7 +9,7 @@ from netaddr import IPNetwork, IPAddress, IPSet
 # Project Imports
 from hyperglass import configuration
 
-
+# Configuration Imports
 code = configuration.codes()
 g = configuration.general()
 

hyperglass/command/execute.py

@@ -16,6 +16,10 @@ from hyperglass.command import construct
 
 
 class ipcheck:
+    """Checks input IPv4 or IPv6 address against host & CIDR regex patters,
+    returns dictionary of discovered attributes. Used for input validation in
+    command.execute module."""
+
     def __init__(self):
         self.ipv4_host = "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)?$"
         self.ipv4_cidr = "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\/(3[0-2]|2[0-9]|1[0-9]|[0-9])?$"
@@ -37,7 +41,7 @@ class ipcheck:
 
 
 class params:
-    """Sends input parameters to construct module for use by execution functions"""
+    """Sends input parameters to command.construct module for use by execution functions"""
 
     class http:
         def __init__(self):
@@ -58,6 +62,7 @@ class params:
             return vars(self)
 
         def nm_host(self):
+            """Defines netmiko end-host dictionary"""
             c = configuration.credential(d.credential)
             attr = {
                 "host": self.router,
@@ -69,6 +74,7 @@ class params:
             return attr
 
         def nm_proxy(self):
+            """Defines netmiko SSH proxy dictionary"""
             p = configuration.proxy(d.proxy)
             attr = {
                 "host": p.address,
@@ -81,6 +87,8 @@ class params:
 
 
 class connect:
+    """Performs the actual connection to the end device"""
+
     class restapi:
         def frr():
             """Sends HTTP POST to router running the hyperglass-frr API"""
@@ -200,16 +208,18 @@ def execute(lg_data):
     # Checks if device type is on the requires_ipv6_cidr list
     requires_ipv6_cidr = configuration.requires_ipv6_cidr(d.type)
 
-    # Check blacklist list for prefixes/IPs and return an error upon a match
     if lg_cmd in ["bgp_route", "ping", "traceroute"]:
         blacklist = IPSet(configuration.blacklist())
         msg = general.msg_error_notallowed.format(i=lg_ipprefix)
+        # Check blacklist list for prefixes/IPs, return error upon a match
         if IPNetwork(lg_ipprefix).ip in blacklist:
             return (msg, code.warning, lg_data)
+        # Check if device requires IPv6 queries to be in CIDR format, return error if True
         if lg_cmd == "bgp_route" and IPNetwork(lg_ipprefix).version == 6:
             if requires_ipv6_cidr == True and ipc["type"] == "host":
                 msg = general.msg_error_ipv6cidr.format(d=d.display_name)
                 return (msg, code.warning, lg_data)
+        # Check if input prefix is in CIDR format, and if command is ping/traceroute, return error if True
         if lg_cmd in ["ping", "traceroute"] and ipc["type"] == "cidr":
             return (msg, code.warning, lg_data)
 
@@ -231,7 +241,7 @@ def execute(lg_data):
                 m=general.max_prefix_length_ipv6, i=IPNetwork(lg_ipprefix)
             )
             return (msg, code.warning, lg_data)
-
+    # Sends validated data to target execution library and returns output
     if d.type == "frr":
         http = params().http()
         try:

hyperglass/command/parse.py

@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 def parse(output, type, cmd):
     """Splits Cisco IOS BGP output by AFI, returns only IPv4 & IPv6 output for protocol-agnostic commands (Community & AS_PATH Lookups)"""
     try:

hyperglass/configuration/__init__.py

@@ -9,17 +9,21 @@ import hyperglass
 # Project Directories
 dir = os.path.dirname(os.path.abspath(__file__))
 hyperglass_root = os.path.dirname(hyperglass.__file__)
+
 # TOML Imports
 configuration = toml.load(os.path.join(dir, "configuration.toml"))
 devices = toml.load(os.path.join(dir, "devices.toml"))
 
 
 def blacklist():
+    """Returns list of subnets/IPs defined in blacklist.toml"""
     b = toml.load(os.path.join(dir, "blacklist.toml"))
     return b["blacklist"]
 
 
 def requires_ipv6_cidr(nos):
+    """Returns boolean for input NOS association with the NOS list defined
+    in requires_ipv6_cidr.toml"""
     r = toml.load(os.path.join(dir, "requires_ipv6_cidr.toml"))
     nos_list = r["requires_ipv6_cidr"]
     if nos in nos_list:
@@ -30,7 +34,8 @@ def requires_ipv6_cidr(nos):
 
 def networks():
     """Returns dictionary of ASNs as keys, list of associated locations as values.
-    Used for populating the /routers/<asn> Flask route."""
+    Imported as a Jinja2 variable on the main page that populates the network/ASN
+    select class."""
     asn_dict = {}
     rl = devices["router"]
     for r in rl.values():
@@ -43,6 +48,11 @@ def networks():
 
 
 def networks_list():
+    """Returns a dictionary of ASNs as keys, list of associated locations,
+    router hostnames, and router display names as keys. Used by Flask to
+    populate the /routers/<asn> route, which is ingested by a JS Ajax call
+    to populate the list of locations associated with the selected network/ASN
+    on the main page."""
     networks_dict = {}
     rl = devices["router"]
     for r in rl.values():
@@ -53,7 +63,6 @@ def networks_list():
                     location=r["location"],
                     hostname=r["name"],
                     display_name=r["display_name"],
-                    requires_ipv6_cidr=requires_ipv6_cidr(r["type"]),
                 )
             )
         else:
@@ -62,14 +71,13 @@ def networks_list():
                     location=r["location"],
                     hostname=r["name"],
                     display_name=r["display_name"],
-                    requires_ipv6_cidr=requires_ipv6_cidr(r["type"]),
                 )
             ]
     return networks_dict
 
 
 class codes:
-    """Class for easy calling & recalling of http success/error codes"""
+    """Reusable status code attributes"""
 
     def __init__(self):
         # 200 OK: renders standard display text
@@ -81,6 +89,8 @@ class codes:
 
 
 class command:
+    """Associates input NOS with matched commands defined in commands.toml"""
+
     def __init__(self, nos):
         c = toml.load(os.path.join(dir, "commands.toml"))
         self.dual = c[nos][0]["dual"]
@@ -92,6 +102,9 @@ class command:
 
 
 class credential:
+    """Associates input credential key name with configured credential username &
+    password in devices.toml."""
+
     def __init__(self, cred):
         c_list = devices["credential"]
         self.username = c_list[cred]["username"]
@@ -102,7 +115,7 @@ class credential:
 
 
 class device:
-    """Class to define & export all device variables"""
+    """Associates input device key name with configured device attributes in devices.toml"""
 
     def __init__(self, device):
         d = devices["router"][device]
@@ -123,6 +136,8 @@ class device:
 
 
 class proxy:
+    """Associates input proxy key name with configured proxy attributes in devices.toml"""
+
     def __init__(self, proxy):
         p = devices["proxy"][proxy]
         self.address = p["address"]
@@ -133,7 +148,7 @@ class proxy:
 
 
 class general:
-    """Class to define and export config variables and export default values if undefined"""
+    """Exports general config variables and sets default values if undefined"""
 
     def __init__(self):
         g = configuration["general"][0]
@@ -183,7 +198,7 @@ class general:
 
 
 class branding:
-    """Class to define and export branding variables and export default values if undefined"""
+    """Exports branding config variables and sets default values if undefined"""
 
     def __init__(self):
         b = configuration["branding"][0]

hyperglass/hyperglass.py

@@ -1,5 +1,3 @@
-#!/usr/bin/env python3
-
 # Module Imports
 import os
 import sys

hyperglass/render/__init__.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+# Module Imports
 import os
 import sass
 import jinja2
@@ -7,31 +7,35 @@ from logzero import logger
 from markdown2 import Markdown
 from flask import render_template
 
+# Project Imports
 import hyperglass
 from hyperglass import configuration
 
+# Module Directories
 dir = os.path.dirname(os.path.abspath(__file__))
 hyperglass_root = os.path.dirname(hyperglass.__file__)
 file_loader = jinja2.FileSystemLoader(dir)
 env = jinja2.Environment(loader=file_loader)
 
+# Configuration Imports
 branding = configuration.branding()
 general = configuration.general()
 networks = configuration.networks()
 
 
-# Functions for rendering Jinja2 templates & importing variables
-
-
 class html:
-    def renderTemplate(t):
+    """Performs HTML rendering actions"""
 
-        # Converts templates/footer.md from Markdown to HTML
+    def renderTemplate(t):
+        """Renders Jinja2 HTML templates"""
+
+        # Convert templates/footer.md from Markdown to HTML
         md = Markdown()
         footer_template = env.get_template("templates/footer.md")
         footer_jinja = footer_template.render(
             site_title=branding.site_title, org_name=general.org_name
         )
+        # Render template based on input template name
         if t == "index":
             template = env.get_template("templates/index.html")
         elif t == "429":
@@ -90,9 +94,14 @@ class html:
 
 
 class css:
+    """Performs CSS/Sass rendering actions"""
+
     def renderTemplate():
+        """Renders Jinja2 template to Sass file, then compiles Sass as CSS"""
+
         scss_file = os.path.join(hyperglass_root, "static/sass/hyperglass.scss")
         css_file = os.path.join(hyperglass_root, "static/css/hyperglass.css")
+        # Renders Jinja2 template as Sass file
         try:
             template = env.get_template("templates/hyperglass.scss")
             rendered_output = template.render(
@@ -114,6 +123,7 @@ class css:
         except:
             logger.error("Error rendering Jinja2 template.")
             raise TypeError("Error rendering Jinja2 template.")
+        # Compiles Sass to CSS
         try:
             generated_sass = sass.compile(filename=scss_file)
             with open(css_file, "w") as css_output: