# Forests of trees

exception `larch.forest.``BadKeySize`(store_key_size, wanted_key_size)

exception `larch.forest.``BadNodeSize`(store_node_size, wanted_node_size)

class `larch.forest.``Forest`(node_store)

  A collection of related B-trees.

  Trees in the same forest can share nodes. Cloned trees are always created in the same forest as the original.

  Cloning trees is very fast: only the root node is modified. Trees can be modified in place. Modifying a tree is done using copy-on-write, so modifying a clone does not modify the original (and vice versa). You can have up to 65535 clones of a tree.

  The list of trees in the forest is stored in the `trees` property as a list of trees in the order in which they were created.

  `commit`()

    Make sure all changes are stored into the node store.

    Changes made to the forest are guaranteed to be persistent only if commit is called successfully.

  `new_id`()

    Generate next node id for this forest.

    Trees should use this whenever they create new nodes. The ids generated by this method are guaranteed to be unique (as long as commits happen OK).

  `new_tree`(old=None)

    Create a new tree.

    If old is None, a completely new tree is created. Otherwise, a clone of an existing one is created.

  `remove_tree`(tree)

    Remove a tree from the forest.

exception `larch.forest.``MetadataMissingKey`(key_name)

`larch.forest.``open_forest`(allow_writes=None, key_size=None, node_size=None, codec=None, node_store=None, **kwargs)

  Create or open a forest.

  `key_size` and `node_size` are retrieved from the forest, unless given. If given, they must match exactly. If the forest does not yet exist, the sizes must be given.

  `codec` is the class to be used for the node codec, defaults to `larch.NodeCodec`. Similarly, `node_store` is the node store class, defaults to `larch.NodeStoreDisk`.

  All other keyword arguments are given the the `node_store` class initializer.