:py:mod:`pygsti.protocols.treenode`
===================================

.. py:module:: pygsti.protocols.treenode

.. autoapi-nested-parse::

   The TreeNode class






Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   pygsti.protocols.treenode.TreeNode




.. py:class:: TreeNode(possible_child_name_dirs, child_values=None)


   Bases: :py:obj:`object`

   A base class for representing an object that lives "at" a filesystem directory.

   Parameters
   ----------
   possible_child_name_dirs : dict
       A dictionary with string keys and values that maps possible child names
       (keys of this `TreeNode`) to directory names (where those keys are stored).

   child_values : dict, optional
       A dictionary of child values (may be other `TreeNode` objects).

   .. py:method:: from_dir(dirname, parent=None, name=None)
      :classmethod:
      :abstractmethod:

      Load a :class:`TreeNode` from the data rooted at `dirname`.

      Parameters
      ----------
      dirname : str or Path
          The directory path to load from.

      parent : TreeNode, optional
          This node's parent node, if it's already loaded.

      name : immutable, optional
          The name of this node, usually a string or tuple.  Almost always the key
          within `parent` that refers to the loaded node (this can be different
          from the directory name).


   .. py:method:: keys()

      An iterator over the keys (child names) of this tree node.


   .. py:method:: items()

      An iterator over the `(child_name, child_node)` pairs of this node.


   .. py:method:: underlying_tree_paths()

      Dictionary paths leading to data objects/nodes beneath this one.

      Returns
      -------
      list
          A list of tuples, each specifying the tree traversal to a child node.
          The first tuple is the empty tuple, referring to *this* (root) node.


   .. py:method:: view(keys_to_keep)

      Get a "view" of this tree node that only has a subset of this node's children.

      Parameters
      ----------
      keys_to_keep : iterable
          A sequence of key names to keep.

      Returns
      -------
      TreeNode


   .. py:method:: prune_tree(paths, paths_are_sorted=False)

      Prune the tree rooted here to include only the given paths, discarding all other leaves & branches.

      Parameters
      ----------
      paths : list
          A list of tuples specifying the paths to keep.

      paths_are_sorted : bool, optional
          Whether `paths` is sorted (lexographically).  Setting this to `True` will save
          a little time.

      Returns
      -------
      TreeNode
          A view of this node and its descendants where unwanted children have been removed.


   .. py:method:: write(dirname, parent=None)
      :abstractmethod:

      Write this tree node to a directory.

      Parameters
      ----------
      dirname : str or Path
          Directory to write to.

      parent : TreeNode, optional
          This node's parent.

      Returns
      -------
      None