b.m.MutableTree(tree.Tree) : class documentation

Part of bzrlib.mutabletree View In Hierarchy

Known subclasses: bzrlib.mutabletree.MutableInventoryTree, bzrlib.workingtree.WorkingTree

A MutableTree is a specialisation of Tree which is able to be mutated.

Generally speaking these mutations are only possible within a lock_write context, and will revert if the lock is broken abnormally - but this cannot be guaranteed - depending on the exact implementation of the mutable state.

The most common form of Mutable Tree is WorkingTree, see bzrlib.workingtree. For tests we also have MemoryTree which is a MutableTree whose contents are entirely in memory.

For now, we are not treating MutableTree as an interface to provide conformance tests for - rather we are testing MemoryTree specifically, and interface testing implementations of WorkingTree.

A mutable tree always has an associated Branch and ControlDir object - the branch and bzrdir attributes.

Method __init__ Undocumented
Method is_control_filename True if filename is the name of a control file in this tree.
Method add Add paths to the set of versioned paths.
Method add_reference Add a TreeReference to the tree, pointing at sub_tree
Method apply_inventory_delta Apply changes to the inventory as an atomic operation.
Method commit Undocumented
Method has_changes Quickly check that the tree contains at least one commitable change.
Method check_changed_or_out_of_date Check the tree for uncommitted changes and branch synchronization.
Method last_revision Return the revision id of the last commit performed in this tree.
Method lock_tree_write Lock the working tree for write, and the branch for read.
Method lock_write Lock the tree and its branch. This allows mutating calls to be made.
Method mkdir Create a directory in the tree. if file_id is None, one is assigned.
Method put_file_bytes_non_atomic Update the content of a file in the tree.
Method set_parent_ids Set the parents ids of the working tree.
Method set_parent_trees Set the parents of the working tree.
Method smart_add Version file_list, optionally recursing into directories.
Method _add_reference Standard add_reference implementation, for use by subclasses
Method _add Helper function for add - updates the inventory.
Method _gather_kinds Helper function for add - sets the entries of kinds.
Method _observed_sha1 Tell the tree we have observed a paths sha1.
def __init__(self, *args, **kw):
Undocumented
def is_control_filename(self, filename):
True if filename is the name of a control file in this tree.

This is true IF and ONLY IF the filename is part of the meta data that bzr controls in this tree. I.E. a random .bzr directory placed on disk will not be a control file for this tree.

ParametersfilenameA filename within the tree. This is a relative path from the root of this tree.
@needs_tree_write_lock
def add(self, files, ids=None, kinds=None):
Add paths to the set of versioned paths.

Note that the command line normally calls smart_add instead, which can automatically recurse.

This adds the files to the inventory, so that they will be recorded by the next commit.

TODO: Perhaps callback with the ids and paths as they're added.

ParametersfilesList of paths to add, relative to the base of the tree.
idsIf set, use these instead of automatically generated ids. Must be the same length as the list of files, but may contain None for ids that are to be autogenerated.
kindsOptional parameter to specify the kinds to be used for each file.
def add_reference(self, sub_tree):
Add a TreeReference to the tree, pointing at sub_tree
def _add_reference(self, sub_tree):
Standard add_reference implementation, for use by subclasses
def _add(self, files, ids, kinds):
Helper function for add - updates the inventory.
Parametersfilessequence of pathnames, relative to the tree root
idssequence of suggested ids for the files (may be None)
kindssequence of inventory kinds of the files (i.e. may contain "tree-reference")
def apply_inventory_delta(self, changes):
Apply changes to the inventory as an atomic operation.
ParameterschangesAn inventory delta to apply to the working tree's inventory.
Returns
See AlsoFor details on the changes parameter.
@needs_write_lock
def commit(self, *args, message=None, revprops=None, **kwargs):
Undocumented
def _gather_kinds(self, files, kinds):
Helper function for add - sets the entries of kinds.
@needs_read_lock
def has_changes(self, _from_tree=None):
Quickly check that the tree contains at least one commitable change.
Parameters_from_treetree to compare against to find changes (default to the basis tree and is intended to be used by tests).
ReturnsTrue if a change is found. False otherwise
@needs_read_lock
def check_changed_or_out_of_date(self, strict, opt_name, more_error, more_warning):
Check the tree for uncommitted changes and branch synchronization.

If strict is None and not set in the config files, a warning is issued. If strict is True, an error is raised. If strict is False, no checks are done and no warning is issued.

ParametersstrictTrue, False or None, searched in branch config if None.
opt_namestrict option name to search in config file.
more_errorDetails about how to avoid the check.
more_warningDetails about what is happening.
@needs_read_lock
def last_revision(self):
Return the revision id of the last commit performed in this tree.

In early tree formats the result of last_revision is the same as the branch last_revision, but that is no longer the case for modern tree formats.

last_revision returns the left most parent id, or None if there are no parents.

last_revision was deprecated as of 0.11. Please use get_parent_ids instead.

def lock_tree_write(self):
Lock the working tree for write, and the branch for read.

This is useful for operations which only need to mutate the working tree. Taking out branch write locks is a relatively expensive process and may fail if the branch is on read only media. So branch write locks should only be taken out when we are modifying branch data - such as in operations like commit, pull, uncommit and update.

def lock_write(self):
Lock the tree and its branch. This allows mutating calls to be made.

Some mutating methods will take out implicit write locks, but in general you should always obtain a write lock before calling mutating methods on a tree.

@needs_write_lock
def mkdir(self, path, file_id=None):
Create a directory in the tree. if file_id is None, one is assigned.
ParameterspathA unicode file path.
file_idAn optional file-id.
Returnsthe file id of the new directory.
def _observed_sha1(self, file_id, path, (sha1, stat_value)):
Tell the tree we have observed a paths sha1.

The intent of this function is to allow trees that have a hashcache to update the hashcache during commit. If the observed file is too new (based on the stat_value) to be safely hash-cached the tree will ignore it.

The default implementation does nothing.

Parametersfile_idThe file id
pathThe file path
sha1The sha 1 that was observed.
stat_valueA stat result for the file the sha1 was read from.
ReturnsNone
@needs_write_lock
def put_file_bytes_non_atomic(self, file_id, bytes):
Update the content of a file in the tree.

Note that the file is written in-place rather than being written to a temporary location and renamed. As a consequence, readers can potentially see the file half-written.

Parametersfile_idfile-id of the file
bytesthe new file contents
def set_parent_ids(self, revision_ids, allow_leftmost_as_ghost=False):
Set the parents ids of the working tree.
Parametersrevision_idsA list of revision_ids.
def set_parent_trees(self, parents_list, allow_leftmost_as_ghost=False):
Set the parents of the working tree.
Parametersparents_listA list of (revision_id, tree) tuples. If tree is None, then that element is treated as an unreachable parent tree - i.e. a ghost.
def smart_add(self, file_list, recurse=True, action=None, save=True):
Version file_list, optionally recursing into directories.

This is designed more towards DWIM for humans than API clarity. For the specific behaviour see the help for cmd_add().

Parametersfile_listList of zero or more paths. NB: these are interpreted relative to the process cwd, not relative to the tree. (Add and most other tree methods use tree-relative paths.)
actionA reporter to be called with the inventory, parent_ie, path and kind of the path being added. It may return a file_id if a specific one should be used.
saveSave the inventory after completing the adds. If False this provides dry-run functionality by doing the add and not saving the inventory.
ReturnsA tuple - files_added, ignored_files. files_added is the count of added files, and ignored_files is a dict mapping files that were ignored to the rule that caused them to be ignored.
API Documentation for Bazaar, generated by pydoctor at 2019-10-20 00:34:54.