add asdf.blocks to documentation

Author: braingram

asdf/_asdf.py

@@ -15,8 +15,8 @@
 from . import _version as version
 from . import constants, generic_io, lazy_nodes, reference, schema, treeutil, util, versioning, yamlutil
 from ._block.manager import Manager as BlockManager
-from ._block.viewer import BlockViewer
 from ._helpers import validate_version
+from .blocks import BlockViewer
 from .config import config_context, get_config
 from .exceptions import (
     AsdfManifestURIMismatchWarning,
@@ -141,7 +141,7 @@ def __init__(
         self._closed = False
         self._external_asdf_by_uri = {}
         self._blocks = BlockManager(uri=uri, lazy_load=lazy_load, memmap=memmap)
-        self.blocks = BlockViewer(self._blocks)
+        self._blocks_view = BlockViewer(self._blocks)
         if tree is None:
             # Bypassing the tree property here, to avoid validating
             # an empty tree.
@@ -546,8 +546,6 @@ def open_external(self, uri, **kwargs):
     def tree(self):
         """
         Get/set the tree of data in the ASDF file.
-
-        When set, the tree will be validated against the ASDF schema.
         """
         if self._closed:
             msg = "Cannot access data from closed ASDF file"
@@ -558,6 +556,13 @@ def tree(self):
     def tree(self, tree):
         self._tree = AsdfObject(tree)
 
+    @property
+    def blocks(self):
+        """
+        A `asdf.blocks.BlockViewer` with read-only access to ASDF blocks loaded from the ASDF file.
+        """
+        return self._blocks_view
+
     def keys(self):
         return self.tree.keys()
 

asdf/_block/viewer.py renamed to asdf/blocks.py

@@ -5,25 +5,43 @@
 
 from asdf.constants import BLOCK_FLAG_STREAMED
 
+__all__ = ["BlockView", "BlockViewer"]
+
 
 class BlockView:
+    """
+    A read-only view of an ASDF block.
+    """
+
     def __init__(self, read_block):
         self._read_block = read_block
 
     @property
     def header(self):
+        """
+        MappingProxy: A read-only mapping of ASDF block header contents.
+        """
         return MappingProxyType(self._read_block.header)
 
     @property
     def offset(self):
+        """
+        int: The offset (in bytes) of the ASDF block from the start of the file.
+        """
         return self._read_block.offset
 
     @property
     def data_offset(self):
+        """
+        int: The offset (in bytes) of the ASDF block data from the start of the file.
+        """
         return self._read_block.data_offset
 
     @property
     def loaded(self):
+        """
+        bool: True if the ASDF block data has been loaded (and cached).
+        """
         return self._read_block._cached_data is not None
 
     def load(self, out=None):
@@ -44,6 +62,10 @@ def _info(self):
 
 
 class BlockViewer(Sequence):
+    """
+    A read-only sequence of `BlockView` objects.
+    """
+
     def __init__(self, manager):
         self._manager = manager
 
@@ -78,4 +100,7 @@ def bold(s):
         return lines
 
     def info(self):
+        """
+        Print a rendering of these blocks to stdout.
+        """
         print("\n".join(self._info()))

docs/asdf/user_api/asdf_blocks.rst

@@ -0,0 +1,8 @@
+******************
+asdf.blocks Module
+******************
+
+.. currentmodule:: asdf
+
+.. automodapi:: asdf.blocks
+    :no-inheritance-diagram:

docs/asdf/user_api/index.rst

@@ -9,9 +9,11 @@ User API
     :hidden:
 
     asdf_package.rst
+    asdf_blocks.rst
     asdf_search.rst
     asdf_config.rst
 
 * :doc:`asdf Package <asdf_package>`
+* :doc:`asdf.blocks Module <asdf_blocks>`
 * :doc:`asdf.search Module <asdf_search>`
 * :doc:`asdf.config Module <asdf_config>`