add lazy_nodes to docs

asdf/_asdf.py

@@ -1588,7 +1588,9 @@ def open_asdf(
     lazy_tree : bool, optional
         When `True` the ASDF tree will not be converted to custom objects
         when the file is loaded. Instead, objects will be "lazily" converted
-        only when they are accessed.
+        only when they are accessed. Note that the tree will not contain dict
+        and list instances for containers and instead return instances of classes
+        defined in `asdf.lazy_nodes`.
 
     custom_schema : str, optional
         Path to a custom schema file that will be used for a secondary

asdf/config.py

@@ -446,7 +446,8 @@ def lazy_tree(self):
         """
         Get configuration that controls if ASDF tree contents
         are lazily converted to custom objects or if all custom
-        objects are created when the file is opened.
+        objects are created when the file is opened. See the
+        ``lazy_tree` argument for `asdf.open`.
 
         Returns
         -------

asdf/lazy_nodes.py

@@ -1,3 +1,7 @@
+"""
+Objects that act like dict, list, OrderedDict but allow
+lazy conversion of tagged ASDF tree nodes to custom objects.
+"""
 import collections
 import inspect
 import warnings
@@ -52,7 +56,13 @@ def _convert(value, af_ref):
         obj = converter.from_yaml_tree(data, tag, sctx)
 
         if isinstance(obj, GeneratorType):
-            # TODO we can't quite do this for every instance
+            # We can't quite do this for every instance (hence the
+            # isgeneratorfunction check above). However it appears
+            # to work for most instances (it was only failing for
+            # the FractionWithInverse test which is covered by the
+            # above code). The code here should only be hit if the
+            # Converter.from_yaml_tree calls another function which
+            # is a generator.
             generator = obj
             obj = next(generator)
             for _ in generator:
@@ -71,10 +81,17 @@ def __init__(self, data=None, af_ref=None):
 
     @property
     def tagged(self):
+        """
+        Return the tagged tree backing this node
+        """
         return self.data
 
 
 class AsdfListNode(AsdfNode, collections.UserList):
+    """
+    An `AsdfNode` subclass that acts like a ``list``.
+    """
+
     def __init__(self, data=None, af_ref=None):
         if data is None:
             data = []
@@ -83,6 +100,8 @@ def __init__(self, data=None, af_ref=None):
 
     @property
     def __class__(self):
+        # this is necessary to allow this class to pass
+        # an isinstance(list) check without inheriting from list.
         return list
 
     def __copy__(self):
@@ -140,9 +159,11 @@ def __getitem__(self, key):
         return value
 
 
-# dict is required here so TaggedDict doesn't convert this to a dict
-# and so that json.dumps will work for this node TODO add test
 class AsdfDictNode(AsdfNode, collections.UserDict):
+    """
+    An `AsdfNode` subclass that acts like a ``dict``.
+    """
+
     def __init__(self, data=None, af_ref=None):
         if data is None:
             data = {}
@@ -151,6 +172,8 @@ def __init__(self, data=None, af_ref=None):
 
     @property
     def __class__(self):
+        # this is necessary to allow this class to pass
+        # an isinstance(dict) check without inheriting from dict.
         return dict
 
     def __copy__(self):
@@ -206,6 +229,10 @@ def __getitem__(self, key):
 
 
 class AsdfOrderedDictNode(AsdfDictNode):
+    """
+    An `AsdfNode` subclass that acts like a ``collections.OrderedDict``.
+    """
+
     def __init__(self, data=None, af_ref=None):
         if data is None:
             data = collections.OrderedDict()

docs/asdf/developer_api.rst

@@ -32,3 +32,5 @@ to create their own custom ASDF types and extensions.
     :no-inheritance-diagram:
 
 .. automodapi:: asdf.testing.helpers
+
+.. automodapi:: asdf.lazy_nodes