Merge branch 'develop'

Author: miott

src/cisco_gnmi/client.py

@@ -342,6 +342,19 @@ def parse_xpath_to_gnmi_path(self, xpath, origin=None):
         return path
 
     def combine_configs(self, payload, last_xpath, xpath, config):
+        """Walking from end to finish 2 xpaths merge so combine them
+
+            |---last xpath config
+        ----|
+            |---this xpath config
+
+        Parameters
+        ----------
+        payload: dict of partial payload
+        last_xpath: last xpath that was processed
+        xpath: colliding xpath
+        config: dict of values associated to colliding xpath
+        """
         last_set = set(last_xpath.split('/'))
         curr_diff = set(xpath.split('/')) - last_set
         if len(curr_diff) > 1:
@@ -368,6 +381,18 @@ def combine_configs(self, payload, last_xpath, xpath, config):
         return payload
 
     def xpath_to_json(self, configs, last_xpath='', payload={}):
+        """Try to combine Xpaths/values into a common payload (recursive).
+
+        Parameters
+        ----------
+        configs: tuple of xpath/value dict
+        last_xpath: str of last xpath that was recusivly processed.
+        payload: dict being recursively built for JSON transformation.
+
+        Returns
+        -------
+        dict of combined xpath/value dict.
+        """
         for i, cfg in enumerate(configs, 1):
             xpath, config, is_key = cfg
             if last_xpath and xpath not in last_xpath:
@@ -408,6 +433,12 @@ def xpath_to_json(self, configs, last_xpath='', payload={}):
     RE_FIND_KEYS = re.compile(r'\[.*?\]')
 
     def get_payload(self, configs):
+        """Common Xpaths were detected so try to consolidate them.
+
+        Parameter
+        ---------
+        configs: tuple of xpath/value dicts
+        """
         # Number of updates are limited so try to consolidate into lists.
         xpaths_cfg = []
         first_key = set()

src/cisco_gnmi/nx.py

@@ -58,6 +58,27 @@ class NXClient(Client):
     """
 
     def xpath_to_path_elem(self, request):
+        """Helper function for Nexus clients.
+
+        Parameters
+        ---------
+        request: dict containing request namespace and nodes to be worked on.
+            namespace: dict of <prefix>: <namespace>
+            nodes: list of dict
+                  <xpath>: Xpath pointing to resource
+                  <value>: value to set resource to
+                  <edit-op>: equivelant NETCONF edit-config operation
+
+        Returns
+        -------
+        tuple: namespace_modules, message dict, origin
+            namespace_modules: dict of <prefix>: <module name>
+                Needed for future support.
+            message dict: 4 lists containing possible updates, replaces,
+                deletes, or gets derived form input nodes.
+            origin str: DME, device, or openconfig
+        """
+
         paths = []
         message = {
             'update': [],
@@ -187,6 +208,26 @@ def check_configs(self, configs):
         return configs
 
     def create_updates(self, configs, origin, json_ietf=False):
+        """Check configs, and construct "Update" messages.
+
+        Parameters
+        ----------
+        configs: dict of <xpath>: <dict val for JSON>
+        origin: str [DME, device, openconfig]
+        json_ietf: bool encoding type for Update val (default False)
+
+        Returns
+        -------
+        List of Update messages with val populated.
+
+        If a set of configs contain a common Xpath, the Update must contain
+        a consolidation of xpath/values for 2 reasons:
+
+        1. Devices may have a restriction on how many Update messages it will
+           accept at once.
+        2. Some xpath/values are required to be set in same Update because of
+           dependencies like leafrefs, mandatory settings, and if/when/musts.
+        """
         if not configs:
             return []
         configs = self.check_configs(configs)

src/cisco_gnmi/xe.py

@@ -80,6 +80,26 @@ class XEClient(Client):
     """
 
     def xpath_to_path_elem(self, request):
+        """Helper function for Cisco XE clients.
+
+        Parameters
+        ---------
+        request: dict containing request namespace and nodes to be worked on.
+            namespace: dict of <prefix>: <namespace>
+            nodes: list of dict
+                  <xpath>: Xpath pointing to resource
+                  <value>: value to set resource to
+                  <edit-op>: equivelant NETCONF edit-config operation
+
+        Returns
+        -------
+        tuple: namespace_modules, message dict, origin
+            namespace_modules: dict of <prefix>: <module name>
+                Needed for future support.
+            message dict: 4 lists containing possible updates, replaces,
+                deletes, or gets derived form input nodes.
+            origin str: openconfig if detected (XE uses rfc7951 by default)
+        """
         paths = []
         message = {
             'update': [],
@@ -201,6 +221,26 @@ def check_configs(self, configs):
         return configs
 
     def create_updates(self, configs, origin, json_ietf=True):
+        """Check configs, and construct "Update" messages.
+
+        Parameters
+        ----------
+        configs: dict of <xpath>: <dict val for JSON>
+        origin: None or 'openconfig'
+        json_ietf: bool encoding type for Update val (default True)
+
+        Returns
+        -------
+        List of Update messages with val populated.
+
+        If a set of configs contain a common Xpath, the Update must contain
+        a consolidation of xpath/values for 2 reasons:
+
+        1. Devices may have a restriction on how many Update messages it will
+           accept at once.
+        2. Some xpath/values are required to be set in same Update because of
+           dependencies like leafrefs, mandatory settings, and if/when/musts.
+        """
         if not configs:
             return None
         configs = self.check_configs(configs)