API: support roots as dict in dump(), load()

for readability, maintainability. Documents
the recent changes to the JSON and Pickle interfaces.
These changes are arranged as separate commits
in order to group the changes by the filetype of
the interface being changed.

README.md

@@ -134,7 +134,7 @@ for d in bdd.pick_iter(u):
 n = bdd.count(u)
 # write to and load from JSON file
 filename = 'bdd.json'
-bdd.dump(filename, roots=[u])
+bdd.dump(filename, roots=dict(res=u))
 other_bdd = BDD()
 roots = other_bdd.load(filename)
 print(other_bdd.vars)

dd/_abc.py

@@ -241,11 +241,12 @@ def dump(
 
         @type filename: `str`
         @type filetype: `str`, e.g., `"pdf"`
-        @type roots: container of nodes
+        @type roots:
+            - `list` of nodes, or
+            - for Pickle: `dict` that maps
+              names (as `str`) to nodes
         """
 
-    # revise this method to return roots as `list` or
-    # named nodes as `dict`
     def load(self, filename, levels=True):
         """Load nodes from Pickle file `filename`.
 
@@ -255,7 +256,11 @@ def load(self, filename, levels=True):
 
         @type filename: `str`
         @return: roots of the loaded BDDs
-        @rtype: `list` of nodes
+        @rtype: depends on the contents of the file,
+            either:
+            - `dict` that maps names (as `str`)
+              to nodes, or
+            - `list` of nodes
         """
 
     @property

dd/autoref.py

@@ -240,7 +240,11 @@ def dump(self, filename, roots=None,
 
         @type filename: `str`
         @type filetype: `str`, e.g., `"pdf"`
-        @type roots: container of nodes
+        @type roots:
+            - `list` of nodes, or
+            - for JSON or Pickle:
+              `dict` that maps names (as `str`)
+              to nodes
         """
         # The method's docstring is a slight modification
         # of the docstring of the method `dd._abc.BDD.dump`.

dd/cudd.pyx

@@ -1822,7 +1822,11 @@ cdef class BDD:
 
         @type filename: `str`
         @type filetype: `str`, e.g., `"pdf"`
-        @type roots: container of nodes
+        @type roots:
+            - `list` of nodes, or
+            - for JSON:
+              `dict` that maps names (as `str`)
+              to nodes
         """
         if filetype is None:
             name = filename.lower()
@@ -1917,7 +1921,11 @@ cdef class BDD:
             where the BDD is loaded
         @type filename: `str`
         @return: roots of loaded BDDs
-        @rtype: `list` of `Function`
+        @rtype: depends on the contents of the file,
+            either:
+            - `dict` that maps names (as `str`)
+              to nodes (as `Function`), or
+            - `list` of `Function`
         """
         if filename.lower().endswith('.dddmp'):
             r = self._load_dddmp(filename)

examples/json_example.py

@@ -14,15 +14,16 @@ def dump_bdd_as_json(filename):
     bdd = _bdd.BDD()
     bdd.declare('x', 'y', 'z')
     u = bdd.add_expr(r'(x /\ y) \/ ~ z')
-    bdd.dump(filename, [u])
+    roots = dict(u=u)
+    bdd.dump(filename, roots)
     print(f'Dumped BDD: {u}')
 
 
 def load_bdd_from_json(filename):
     """Load a BDD from a JSON file."""
     bdd = _bdd.BDD()
-    u, = bdd.load(filename)
-    print(f'Loaded BDD: {u}')
+    roots = bdd.load(filename)
+    print(f'Loaded BDD: {roots}')
 
 
 if __name__ == '__main__':