b.t.Tree(object) : class documentation

Part of bzrlib.tree View In Hierarchy

Known subclasses: bzrlib.bundle.bundle_data.BundleTree, bzrlib.filter_tree.ContentFilterTree, bzrlib.revisiontree.RevisionTree, bzrlib.tree.InventoryTree

Abstract file tree.

There are several subclasses:

Trees can be compared, etc, regardless of whether they are working trees or versioned trees.

Method has_versioned_directories Whether this tree can contain explicitly versioned directories.
Method changes_from Return a TreeDelta of the changes from other to this tree.
Method iter_changes See InterTree.iter_changes
Method conflicts Get a list of the conflicts in the tree.
Method extras For trees that can have unversioned files, return all such paths.
Method get_parent_ids Get the parent ids for this tree.
Method has_filename True if the tree has given filename.
Method has_id Undocumented
Method __contains__ Undocumented
Method has_or_had_id Undocumented
Method is_ignored Check whether the filename is ignored by this tree.
Method all_file_ids Iterate through all file ids, including ids for missing files.
Method id2path Return the path for a file id.
Method iter_entries_by_dir Walk the tree in 'by_dir' order.
Method list_files List all files in this tree.
Method iter_references Undocumented
Method kind Undocumented
Method stored_kind File kind stored for this file_id.
Method path_content_summary Get a summary of the information about path.
Method get_reference_revision Undocumented
Method get_file Return a file object for the file file_id in the tree.
Method get_file_with_stat Get a file handle and stat object for file_id.
Method get_file_text Return the byte content of a file.
Method get_file_lines Return the content of a file, as lines.
Method get_file_verifier Return a verifier for a file.
Method get_file_sha1 Return the SHA1 file for a file.
Method get_file_mtime Return the modification time for a file.
Method get_file_size Return the size of a file in bytes.
Method get_file_by_path Undocumented
Method is_executable Check if a file is executable.
Method iter_files_bytes Iterate through file contents.
Method get_symlink_target Get the target for a given file_id.
Method get_root_id Return the file_id for the root of this tree.
Method annotate_iter Return an iterator of revision_id, line tuples.
Method plan_file_merge Generate a merge plan based on annotations.
Method plan_file_lca_merge Generate a merge plan based lca-newness.
Method path2id Return the id for path in this tree.
Method paths2ids Return all the ids that can be reached by walking from paths.
Method iter_children Undocumented
Method lock_read Lock this tree for multiple read only operations.
Method revision_tree Obtain a revision tree for the revision revision_id.
Method unknowns What files are present in this tree and unknown.
Method unlock Undocumented
Method filter_unversioned_files Filter out paths that are versioned.
Method walkdirs Walk the contents of this tree from path down.
Method supports_content_filtering Undocumented
Method iter_search_rules Find the preferences for filenames in a tree.
Method _comparison_data Return a tuple of kind, executable, stat_value for a file.
Method _file_size Undocumented
Method _get_plan_merge_data Undocumented
Method _iter_parent_trees Iterate through parent trees, defaulting to Tree.revision_tree.
Method _get_file_revision Ensure that file_id, tree_revision is in vf to plan the merge.
Method _check_retrieved Undocumented
Method _content_filter_stack The stack of content filters for a path if filtering is supported.
Method _content_filter_stack_provider A function that returns a stack of ContentFilters.
Method _get_rules_searcher Get the RulesSearcher for this tree given the default one.
def has_versioned_directories(self):
Whether this tree can contain explicitly versioned directories.

This defaults to True, but some implementations may want to override it.

def changes_from(self, other, want_unchanged=False, specific_files=None, extra_trees=None, require_versioned=False, include_root=False, want_unversioned=False):
Return a TreeDelta of the changes from other to this tree.

The comparison will be performed by an InterTree object looked up on self and other.

ParametersotherA tree to compare with.
specific_filesAn optional list of file paths to restrict the comparison to. When mapping filenames to ids, all matches in all trees (including optional extra_trees) are used, and all children of matched directories are included.
want_unchangedAn optional boolean requesting the inclusion of unchanged entries in the result.
extra_treesAn optional list of additional trees to use when mapping the contents of specific_files (paths) to file_ids.
require_versionedAn optional boolean (defaults to False). When supplied and True all the 'specific_files' must be versioned, or a PathsNotVersionedError will be thrown.
want_unversionedScan for unversioned paths.
def iter_changes(self, from_tree, include_unchanged=False, specific_files=None, pb=None, extra_trees=None, require_versioned=True, want_unversioned=False):
See InterTree.iter_changes
def conflicts(self):
Get a list of the conflicts in the tree.

Each conflict is an instance of bzrlib.conflicts.Conflict.

def extras(self):
For trees that can have unversioned files, return all such paths.
def get_parent_ids(self):
Get the parent ids for this tree.

:return: a list of parent ids. [] is returned to indicate
a tree with no parents.
:raises: BzrError if the parents are not known.
def has_filename(self, filename):
True if the tree has given filename.
def has_id(self, file_id):
Undocumented
@deprecated_method(deprecated_in((2, 4, 0)))
def __contains__(self, file_id):
Undocumented
def has_or_had_id(self, file_id):
Undocumented
def is_ignored(self, filename):
Check whether the filename is ignored by this tree.
ParametersfilenameThe relative filename within the tree.
ReturnsTrue if the filename is ignored.
def all_file_ids(self):
Iterate through all file ids, including ids for missing files.
def id2path(self, file_id):
Return the path for a file id.
RaisesNoSuchId
def iter_entries_by_dir(self, specific_file_ids=None, yield_parents=False):

Walk the tree in 'by_dir' order.

This will yield each entry in the tree as a (path, entry) tuple. The order that they are yielded is:

Directories are walked in a depth-first lexicographical order, however, whenever a directory is reached, all of its direct child nodes are yielded in lexicographical order before yielding the grandchildren.

For example, in the tree:

a/
  b/
    c
  d/
    e
f/
  g

The yield order (ignoring root) would be:

a, f, a/b, a/d, a/b/c, a/d/e, f/g
Parametersyield_parentsIf True, yield the parents from the root leading down to specific_file_ids that have been requested. This has no impact if specific_file_ids is None.
def list_files(self, include_root=False, from_dir=None, recursive=True):
List all files in this tree.
Parametersinclude_rootWhether to include the entry for the tree root
from_dirDirectory under which to list files
recursiveWhether to list files recursively
Returnsiterator over tuples of (path, versioned, kind, file_id, inventory entry)
def iter_references(self):
Undocumented
def kind(self, file_id):
Undocumented
def stored_kind(self, file_id):
File kind stored for this file_id.

May not match kind on disk for working trees. Always available for versioned files, even when the file itself is missing.

def path_content_summary(self, path):
Get a summary of the information about path.

All the attributes returned are for the canonical form, not the
convenient form (if content filters are in use.)

:param path: A relative path within the tree.
:return: A tuple containing kind, size, exec, sha1-or-link.
    Kind is always present (see tree.kind()).
    size is present if kind is file and the size of the 
        canonical form can be cheaply determined, None otherwise.
    exec is None unless kind is file and the platform supports the 'x'
        bit.
    sha1-or-link is the link target if kind is symlink, or the sha1 if
        it can be obtained without reading the file.
def get_reference_revision(self, file_id, path=None):
Undocumented
def _comparison_data(self, entry, path):
Return a tuple of kind, executable, stat_value for a file.

entry may be None if there is no inventory entry for the file, but path must always be supplied.

kind is None if there is no file present (even if an inventory id is present). executable is False for non-file entries.

def _file_size(self, entry, stat_value):
Undocumented
def get_file(self, file_id, path=None):
Return a file object for the file file_id in the tree.

If both file_id and path are defined, it is implementation defined as to which one is used.

def get_file_with_stat(self, file_id, path=None):
Get a file handle and stat object for file_id.

The default implementation returns (self.get_file, None) for backwards compatibility.

Parametersfile_idThe file id to read.
pathThe path of the file, if it is known.
ReturnsA tuple (file_handle, stat_value_or_None). If the tree has no stat facility, or need for a stat cache feedback during commit, it may return None for the second element of the tuple.
def get_file_text(self, file_id, path=None):
Return the byte content of a file.

If both file_id and path are supplied, an implementation may use either one.

Parametersfile_idThe file_id of the file.
pathThe path of the file.
ReturnsA single byte string for the whole file.
def get_file_lines(self, file_id, path=None):
Return the content of a file, as lines.

If both file_id and path are supplied, an implementation may use either one.

Parametersfile_idThe file_id of the file.
pathThe path of the file.
def get_file_verifier(self, file_id, path=None, stat_value=None):
Return a verifier for a file.

The default implementation returns a sha1.

Parametersfile_idThe handle for this file.
pathThe path that this file can be found at. These must point to the same object.
stat_valueOptional stat value for the object
ReturnsTuple with verifier name and verifier data
def get_file_sha1(self, file_id, path=None, stat_value=None):
Return the SHA1 file for a file.
Parametersfile_idThe handle for this file.
pathThe path that this file can be found at. These must point to the same object.
stat_valueOptional stat value for the object
Notecallers should use get_file_verifier instead where possible, as the underlying repository implementation may have quicker access to a non-sha1 verifier.
def get_file_mtime(self, file_id, path=None):
Return the modification time for a file.
Parametersfile_idThe handle for this file.
pathThe path that this file can be found at. These must point to the same object.
def get_file_size(self, file_id):
Return the size of a file in bytes.

This applies only to regular files. If invoked on directories or symlinks, it will return None. :param file_id: The file-id of the file

def get_file_by_path(self, path):
Undocumented
def is_executable(self, file_id, path=None):
Check if a file is executable.
Parametersfile_idThe handle for this file.
pathThe path that this file can be found at. These must point to the same object.
def iter_files_bytes(self, desired_files):
Iterate through file contents.

Files will not necessarily be returned in the order they occur in desired_files. No specific order is guaranteed.

Yields pairs of identifier, bytes_iterator. identifier is an opaque value supplied by the caller as part of desired_files. It should uniquely identify the file version in the caller's context. (Examples: an index number or a TreeTransform trans_id.)

bytes_iterator is an iterable of bytestrings for the file. The kind of iterable and length of the bytestrings are unspecified, but for this implementation, it is a tuple containing a single bytestring with the complete text of the file.

Parametersdesired_filesa list of (file_id, identifier) pairs
def get_symlink_target(self, file_id, path=None):
Get the target for a given file_id.

It is assumed that the caller already knows that file_id is referencing a symlink. :param file_id: Handle for the symlink entry. :param path: The path of the file. If both file_id and path are supplied, an implementation may use either one. :return: The path the symlink points to.

def get_root_id(self):
Return the file_id for the root of this tree.
def annotate_iter(self, file_id, default_revision=_mod_revision.CURRENT_REVISION):
Return an iterator of revision_id, line tuples.

For working trees (and mutable trees in general), the special
revision_id 'current:' will be used for lines that are new in this
tree, e.g. uncommitted changes.
:param file_id: The file to produce an annotated version from
:param default_revision: For lines that don't match a basis, mark them
    with this revision id. Not all implementations will make use of
    this value.
def _get_plan_merge_data(self, file_id, other, base):
Undocumented
def plan_file_merge(self, file_id, other, base=None):
Generate a merge plan based on annotations.

If the file contains uncommitted changes in this tree, they will be attributed to the 'current:' pseudo-revision. If the file contains uncommitted changes in the other tree, they will be assigned to the 'other:' pseudo-revision.

def plan_file_lca_merge(self, file_id, other, base=None):
Generate a merge plan based lca-newness.

If the file contains uncommitted changes in this tree, they will be attributed to the 'current:' pseudo-revision. If the file contains uncommitted changes in the other tree, they will be assigned to the 'other:' pseudo-revision.

def _iter_parent_trees(self):
Iterate through parent trees, defaulting to Tree.revision_tree.
def _get_file_revision(self, file_id, vf, tree_revision):
Ensure that file_id, tree_revision is in vf to plan the merge.
def _check_retrieved(self, ie, f):
Undocumented
def path2id(self, path):
Return the id for path in this tree.
def paths2ids(self, paths, trees=, require_versioned=True):
Return all the ids that can be reached by walking from paths.

Each path is looked up in this tree and any extras provided in trees, and this is repeated recursively: the children in an extra tree of a directory that has been renamed under a provided path in this tree are all returned, even if none exist under a provided path in this tree, and vice versa.

ParameterspathsAn iterable of paths to start converting to ids from. Alternatively, if paths is None, no ids should be calculated and None will be returned. This is offered to make calling the api unconditional for code that might take a list of files.
treesAdditional trees to consider.
require_versionedIf False, do not raise NotVersionedError if an element of paths is not versioned in this tree and all of trees.
def iter_children(self, file_id):
Undocumented
def lock_read(self):
Lock this tree for multiple read only operations.
ReturnsA bzrlib.lock.LogicalLockResult.
def revision_tree(self, revision_id):
Obtain a revision tree for the revision revision_id.

The intention of this method is to allow access to possibly cached tree data. Implementors of this method should raise NoSuchRevision if the tree is not locally available, even if they could obtain the tree via a repository or some other means. Callers are responsible for finding the ultimate source for a revision tree.

Parametersrevision_idThe revision_id of the requested tree.
ReturnsA Tree.
RaisesNoSuchRevision if the tree cannot be obtained.
def unknowns(self):
What files are present in this tree and unknown.
Returnsan iterator over the unknown files.
def unlock(self):
Undocumented
def filter_unversioned_files(self, paths):
Filter out paths that are versioned.
Returnsset of paths.
def walkdirs(self, prefix=''):
Walk the contents of this tree from path down.

This yields all the data about the contents of a directory at a time.
After each directory has been yielded, if the caller has mutated the
list to exclude some directories, they are then not descended into.

The data yielded is of the form:
((directory-relpath, directory-path-from-root, directory-fileid),
[(relpath, basename, kind, lstat, path_from_tree_root, file_id,
  versioned_kind), ...]),
 - directory-relpath is the containing dirs relpath from prefix
 - directory-path-from-root is the containing dirs path from /
 - directory-fileid is the id of the directory if it is versioned.
 - relpath is the relative path within the subtree being walked.
 - basename is the basename
 - kind is the kind of the file now. If unknonwn then the file is not
   present within the tree - but it may be recorded as versioned. See
   versioned_kind.
 - lstat is the stat data *if* the file was statted.
 - path_from_tree_root is the path from the root of the tree.
 - file_id is the file_id if the entry is versioned.
 - versioned_kind is the kind of the file as last recorded in the
   versioning system. If 'unknown' the file is not versioned.
One of 'kind' and 'versioned_kind' must not be 'unknown'.

:param prefix: Start walking from prefix within the tree rather than
at the root. This allows one to walk a subtree but get paths that are
relative to a tree rooted higher up.
:return: an iterator over the directory data.
def supports_content_filtering(self):
Undocumented
def _content_filter_stack(self, path=None, file_id=None):
The stack of content filters for a path if filtering is supported.

Readers will be applied in first-to-last order. Writers will be applied in last-to-first order. Either the path or the file-id needs to be provided.

Parameterspathpath relative to the root of the tree or None if unknown
file_idfile_id or None if unknown
Returnsthe list of filters - [] if there are none
def _content_filter_stack_provider(self):
A function that returns a stack of ContentFilters.

The function takes a path (relative to the top of the tree) and a file-id as parameters.

ReturnsNone if content filtering is not supported by this tree.
def iter_search_rules(self, path_names, pref_names=None, _default_searcher=None):
Find the preferences for filenames in a tree.
Parameterspath_namesan iterable of paths to find attributes for. Paths are given relative to the root of the tree.
pref_namesthe list of preferences to lookup - None for all
_default_searcherprivate parameter to assist testing - don't use
Returnsan iterator of tuple sequences, one per path-name. See _RulesSearcher.get_items for details on the tuple sequence.
def _get_rules_searcher(self, default_searcher):
Get the RulesSearcher for this tree given the default one.
API Documentation for Bazaar, generated by pydoctor at 2019-11-22 00:59:21.