this repo has no description
doc edits
+17
-4
+14
-2
docs/overview.rst
+14
-2
docs/overview.rst
···
37
37
38
38
An MST is comprised of one or more Nodes. :py:mod:`atmst` represents Nodes using :meth:`~atmst.mst.node.MSTNode`, an immutable dataclass.
39
39
40
-
Nodes are ultimately stored in a BlockStore, serialised as `DAG-CBOR <https://ipld.io/docs/codecs/known/dag-cbor/>`_, and the :meth:`~atmst.mst.node_store.NodeStore` class facilitates this. A NodeStore also maintains an LRU cache, mapping CIDs to MSTNode objects, to reduce the impact of BlockStore read latency, hash verification, and deserialisation overheads.
40
+
Nodes are stored in a BlockStore, serialised as `DAG-CBOR <https://ipld.io/docs/codecs/known/dag-cbor/>`_, and the :meth:`~atmst.mst.node_store.NodeStore` class handles this transparently. A NodeStore internally maintains an LRU cache, mapping CIDs to MSTNode objects, to reduce the impacts of BlockStore read latency, hash verification, and deserialisation overheads.
41
41
42
-
The :meth:`~atmst.mst.node_wrangler.NodeWrangler` class facilitates modifications to MSTs, and the :meth:`~atmst.mst.node_walker.NodeWalker` class facilitates access to MSTs, which the :meth:`~atmst.mst.diff.mst_diff` method makes use of.
42
+
The :meth:`~atmst.mst.node_wrangler.NodeWrangler` class facilitates modifications to MSTs, via the :meth:`~atmst.mst.node_wrangler.NodeWrangler.put_record` and :meth:`~atmst.mst.node_wrangler.NodeWrangler.delete_record` methods. These methods each return a CID reference to the new MST root, with any newly created Nodes tracked internally using a :meth:`~atmst.mst.node_store.NodeStore`.
43
+
44
+
For reading MSTs, the :meth:`~atmst.mst.node_walker.NodeWalker` class acts as a "cursor" for walking the tree from a given starting point (usually the root), including convenience methods for accessing records by key.
45
+
46
+
The :meth:`~atmst.mst.diff.mst_diff` method makes use of :meth:`~atmst.mst.node_walker.NodeWalker` internally.
47
+
48
+
=======
49
+
Recipes
50
+
=======
51
+
52
+
For some examples of how all these components fit together, check out the source of `cartool.py <https://github.com/DavidBuchanan314/atmst/blob/main/src/atmst/cartool.py>`_.
53
+
54
+
TODO: Improve this part of the docs!
+3
-2
src/atmst/mst/diff.py
+3
-2
src/atmst/mst/diff.py
···
75
75
76
76
def mst_diff(ns: NodeStore, root_a: CID, root_b: CID) -> Tuple[Set[CID], Set[CID]]: # created, deleted
77
77
"""
78
-
Given two MST root node CIDs, efficiently compute the difference between them, represented as
79
-
two sets holding the created and deleted MST nodes respectively (referenced by CIDs).
78
+
XXX: This implementation is not yet ready for prime-time!
79
+
80
+
Given two MST root node CIDs, efficiently compute the difference between the two trees. The result is two sets, holding the created and deleted MST nodes respectively (referenced by CIDs).
80
81
"""
81
82
created = set() # MST nodes in b but not in a
82
83
deleted = set() # MST nodes in a but not in b