Improved Engine usage docs.

Author: pp-mo

lib/iris/fileformats/_nc_load_rules/engine.py

@@ -17,38 +17,47 @@
 API of a Pyke.knowlege_base, so that we can list its case-specific facts, as
 used in :meth:`iris.fileformats.netcdf._actions_activation_stats`.
 
+TODO: get rid of redundact fact-database identifier arguments.
+
 """
 from .actions import run_actions
 
 
-class FactList:
-    def __init__(self):
-        self.case_specific_facts = []
-
-
 class FactEntity:
-    # To support:
     """
-    kb_facts = engine.get_kb(_PYKE_FACT_BASE)
+    An object with property 'entity_lists', which is a dictionary of 'FactList's.
 
-    for key in kb_facts.entity_lists.keys():
-        for arg in kb_facts.entity_lists[key].case_specific_facts:
-            print("\t%s%s" % (key, arg))
+    A Factlist, in turn, is an object with property 'case_specific_facts',
+    which is a list of tuples of strings
+    (each of which is a 'fact' of the named class).
+
+    To support the debug code :
+        kb_facts = engine.get_kb(_PYKE_FACT_BASE)
+        for key in kb_facts.entity_lists.keys():
+            for arg in kb_facts.entity_lists[key].case_specific_facts:
+                print("\t%s%s" % (key, arg))
 
     """
 
     def __init__(self):
         self.entity_lists = {}
 
+    class _FactList:
+        # Just "an object with a 'case_specific_facts' property" (which is a list).
+        def __init__(self):
+            self.case_specific_facts = []
+
     def add_fact(self, fact_name, args):
+        # Add a fact "fact_name(*args)".
         if fact_name not in self.entity_lists:
-            self.entity_lists[fact_name] = FactList()
+            self.entity_lists[fact_name] = self._FactList()
         fact_list = self.entity_lists[fact_name]
         fact_list.case_specific_facts.append(tuple(args))
 
-    def sect_facts(self, entity_name):
-        if entity_name in self.entity_lists:
-            facts = self.entity_lists.get(entity_name).case_specific_facts
+    def sect_facts(self, fact_name):
+        # Lookup all facts "fact_name(*args)" for a given fact_name.
+        if fact_name in self.entity_lists:
+            facts = self.entity_lists.get(fact_name).case_specific_facts
         else:
             facts = []
         return facts
@@ -61,6 +70,11 @@ class Engine:
     Provides just enough API so that the existing code in
     :mod:`iris.fileformats.netcdf` can interface with our new rules functions.
 
+    A list of possible fact-arglists is store, for each of a set of fact-names
+    (which are strings).
+    Each fact-argslist is represented by a tuple of values
+    -- at present, in practice, those are all strings too.
+
     """
 
     def __init__(self):
@@ -79,7 +93,7 @@ def activate(self):
         set by engine.cf_var (the variable name).
 
         The rules operation itself is coded elsewhere,
-        in :mod:`iris.fileformats.netcdf._nc_load_rules.rules`.
+        in :mod:`iris.fileformats.netcdf._nc_load_rules.actions`.
 
         """
         run_actions(self)
@@ -98,6 +112,8 @@ def add_case_specific_fact(self, fact_name, fact_arglist):
 
         Roughly, self.facts.entity_lists[fact_name].append(fact_arglist).
 
+        NOTE: 'kb_name' is no longer used.
+
         """
         self.facts.add_fact(fact_name, fact_arglist)