b.t.TreeTransform(DiskTreeTransform) : class documentation

Part of bzrlib.transform View In Hierarchy

Represent a tree transformation.

This object is designed to support incremental generation of the transform, in any order.

However, it gives optimum performance when parent directories are created before their contents. The transform is then able to put child files directly in their parent directory, avoiding later renames.

It is easy to produce malformed transforms, but they are generally harmless. Attempting to apply a malformed transform will cause an exception to be raised before any modifications are made to the tree.

Many kinds of malformed transforms can be corrected with the resolve_conflicts function. The remaining ones indicate programming error, such as trying to create a file with no path.

Two sets of file creation methods are supplied. Convenience methods are:
  • new_file
  • new_directory
  • new_symlink
These are composed of the low-level methods:
  • create_path
  • create_file or create_directory or create_symlink
  • version_file
  • set_executability

Transform/Transaction ids

trans_ids are temporary ids assigned to all files involved in a transform. It's possible, even common, that not all files in the Tree have trans_ids.

trans_ids are used because filenames and file_ids are not good enough identifiers; filenames change, and not all files have file_ids. File-ids are also associated with trans-ids, so that moving a file moves its file-id.

trans_ids are only valid for the TreeTransform that generated them.

Limbo

Limbo is a temporary directory use to hold new versions of files. Files are added to limbo by create_file, create_directory, create_symlink, and their convenience variants (new_*). Files may be removed from limbo using cancel_creation. Files are renamed from limbo into their final location as part of TreeTransform.apply

Limbo must be cleaned up, by either calling TreeTransform.apply or calling TreeTransform.finalize.

Files are placed into limbo inside their parent directories, where possible. This reduces subsequent renames, and makes operations involving lots of files faster. This optimization is only possible if the parent directory is created before creating any of its children, so avoid creating children before parents, where possible.

Pending-deletion

This temporary directory is used by _FileMover for storing files that are about to be deleted. In case of rollback, the files will be restored. FileMover does not delete files until it is sure that a rollback will not happen.

Method __init__ Note: a tree_write lock is taken on the tree.
Method canonical_path Get the canonical tree-relative path
Method tree_kind Determine the file kind in the working tree.
Method iter_tree_children Iterate through the entry's tree children, if any
Method apply Apply all changes to the inventory and filesystem.
Method _set_mode Set the mode of new file contents.
Method _generate_limbo_path Generate a limbo path using the final path if possible.
Method _generate_inventory_delta Generate an inventory delta for the current transform.
Method _apply_removals Perform tree operations that remove directory/inventory names.
Method _apply_insertions Perform tree operations that insert directory/inventory names.
Method _apply_observed_sha1s After we have finished renaming everything, update observed sha1s

Inherited from DiskTreeTransform:

Method finalize Release the working tree lock, if held, clean up limbo dir.
Method adjust_path Change the path that is assigned to a transaction id.
Method create_file Schedule creation of a new file.
Method create_hardlink Schedule creation of a hard link
Method create_directory Schedule creation of a new directory.
Method create_symlink Schedule creation of a new symbolic link.
Method cancel_creation Cancel the creation of new file contents.
Method new_orphan Schedule an item to be orphaned.
Method _limbo_name Generate the limbo name of a file
Method _rename_in_limbo Fix limbo names so that the right final path is produced.
Method _limbo_descendants Return the set of trans_ids whose limbo paths descend from this.
Method _read_file_chunks Undocumented
Method _read_symlink_target Undocumented
Method _set_mtime All files that are created get the same mtime.

Inherited from TreeTransformBase (via DiskTreeTransform):

Method __enter__ Support Context Manager API.
Method __exit__ Support Context Manager API.
Method create_path Assign a transaction id to a new path
Method adjust_root_path Emulate moving the root by moving all children, instead.
Method fixup_new_roots Reinterpret requests to change the root directory
Method trans_id_tree_file_id Determine the transaction id of a working tree file.
Method trans_id_file_id Determine or set the transaction id associated with a file ID.
Method trans_id_tree_path Determine (and maybe set) the transaction ID for a tree path.
Method get_tree_parent Determine id of the parent in the tree.
Method delete_contents Schedule the contents of a path entry for deletion
Method cancel_deletion Cancel a scheduled deletion
Method unversion_file Schedule a path entry to become unversioned
Method delete_versioned Delete and unversion a versioned file
Method set_executability Schedule setting of the 'execute' bit
Method set_tree_reference Set the reference associated with a directory
Method version_file Schedule a file to become versioned.
Method cancel_versioning Undo a previous versioning of a file
Method new_paths Determine the paths of all new and changed files.
Method final_kind Determine the final file kind, after any changes applied.
Method tree_file_id Determine the file id associated with the trans_id in the tree
Method final_file_id Determine the file id after any changes are applied, or None.
Method inactive_file_id Return the inactive file_id associated with a transaction id.
Method final_parent Determine the parent file_id, after any changes are applied.
Method final_name Determine the final filename, after all changes are applied.
Method by_parent Return a map of parent: children for known parents.
Method path_changed Return True if a trans_id's path has changed.
Method new_contents Undocumented
Method find_conflicts Find any violations of inventory or filesystem invariants
Method has_named_child Undocumented
Method new_file Convenience method to create files.
Method new_directory Convenience method to create directories.
Method new_symlink Convenience method to create symbolic link.
Method iter_changes Produce output in the same format as Tree.iter_changes.
Method get_preview_tree Return a tree representing the result of the transform.
Method commit Commit the result of this TreeTransform to a branch.
Method serialize Serialize this TreeTransform.
Method deserialize Deserialize a stored TreeTransform.
Method __get_root Undocumented
Method _assign_id Produce a new tranform id
Method _inventory_altered Determine which trans_ids need new Inventory entries.
Method _check_malformed Undocumented
Method _add_tree_children Add all the children of all active parents to the known paths.
Method _has_named_child Does a parent already have a name child.
Method _available_backup_name Find an available backup name.
Method _parent_loops No entry should be its own ancestor
Method _unversioned_parents If parent directories are versioned, children must be versioned.
Method _improper_versioning Cannot version a file with no contents, or a bad type.
Method _executability_conflicts Check for bad executability changes.
Method _overwrite_conflicts Check for overwrites (not permitted on Win32)
Method _duplicate_entries No directory may have two entries with the same name.
Method _duplicate_ids Each inventory id may only be used once
Method _parent_type_conflicts Children must have a directory parent
Method _set_executability Set the executability of versioned files
Method _new_entry Helper function to create a new filesystem entry.
Method _get_potential_orphans Find the potential orphans in a directory.
Method _affected_ids Return the set of transform ids affected by the transform
Method _get_file_id_maps Return mapping of file_ids to trans_ids in the to and from states
Method _from_file_data Get data about a file in the from (tree) state
Method _to_file_data Get data about a file in the to (target) state
Method _text_parent Undocumented
Method _get_parents_texts Get texts for compression parents of this file.
Method _get_parents_lines Get lines for compression parents of this file.
def __init__(self, tree, pb=None):
Note: a tree_write lock is taken on the tree.

Use TreeTransform.finalize() to release the lock (can be omitted if TreeTransform.apply() called).

def canonical_path(self, path):
Get the canonical tree-relative path
def tree_kind(self, trans_id):
Determine the file kind in the working tree.
ReturnsThe file kind or None if the file does not exist
def _set_mode(self, trans_id, mode_id, typefunc):
Set the mode of new file contents. The mode_id is the existing file to get the mode from (often the same as trans_id). The operation is only performed if there's a mode match according to typefunc.
def iter_tree_children(self, parent_id):
Iterate through the entry's tree children, if any
def _generate_limbo_path(self, trans_id):
Generate a limbo path using the final path if possible.

This optimizes the performance of applying the tree transform by avoiding renames. These renames can be avoided only when the parent directory is already scheduled for creation.

If the final path cannot be used, falls back to using the trans_id as the relpath.

def apply(self, no_conflicts=False, precomputed_delta=None, _mover=None):
Apply all changes to the inventory and filesystem.

If filesystem or inventory conflicts are present, MalformedTransform will be thrown.

If apply succeeds, finalize is not necessary.

Parametersno_conflictsif True, the caller guarantees there are no conflicts, so no check is made.
precomputed_deltaAn inventory delta to use instead of calculating one.
_moverSupply an alternate FileMover, for testing
def _generate_inventory_delta(self):
Generate an inventory delta for the current transform.
def _apply_removals(self, mover):
Perform tree operations that remove directory/inventory names.

That is, delete files that are to be deleted, and put any files that need renaming into limbo. This must be done in strict child-to-parent order.

If inventory_delta is None, no inventory delta generation is performed.

def _apply_insertions(self, mover):
Perform tree operations that insert directory/inventory names.

That is, create any files that need to be created, and restore from limbo any files that needed renaming. This must be done in strict parent-to-child order.

If inventory_delta is None, no inventory delta is calculated, and no list of modified paths is returned.

def _apply_observed_sha1s(self):
After we have finished renaming everything, update observed sha1s

This has to be done after self._tree.apply_inventory_delta, otherwise it doesn't know anything about the files we are updating. Also, we want to do this as late as possible, so that most entries end up cached.

API Documentation for Bazaar, generated by pydoctor at 2022-06-16 00:25:16.