bzrlib.weave.Weave : API documentation

weave - versioned text file storage.

A Weave manages versions of line-based text files, keeping track of the originating version for each line.

To clients the "lines" of the file are represented as a list of strings. These strings will typically have terminal newline characters, but this is not required. In particular files commonly do not have a newline at the end of the file.

Texts can be identified in either of two ways:

a nonnegative index number.
a version-id string.

Typically the index number will be valid only inside this weave and the version-id is used to reference it in the larger world.

The weave is represented as a list mixing edit instructions and literal text. Each entry in _weave can be either a string (or unicode), or a tuple. If a string, it means that the given line should be output in the currently active revisions.

If a tuple, it gives a processing instruction saying in which revisions the enclosed lines are active. The tuple has the form (instruction, version).

The instruction can be '{' or '}' for an insertion block, and '[' and ']' for a deletion block respectively. The version is the integer version index. There is no replace operator, only deletes and inserts. For '}', the end of an insertion, there is no version parameter because it always closes the most recently opened insertion.

Constraints/notes:

A later version can delete lines that were introduced by any number of ancestor versions; this implies that deletion instructions can span insertion blocks without regard to the insertion block's nesting.
Similarly, deletions need not be properly nested with regard to each other, because they might have been generated by independent revisions.
Insertions are always made by inserting a new bracketed block into a single point in the previous weave. This implies they can nest but not overlap, and the nesting must always have later insertions on the inside.
It doesn't seem very useful to have an active insertion inside an inactive insertion, but it might happen.
Therefore, all instructions are always"considered"; that is passed onto and off the stack. An outer inactive block doesn't disable an inner block.
Lines are enabled if the most recent enclosing insertion is active and none of the enclosing deletions are active.
There is no point having a deletion directly inside its own insertion; you might as well just not write it. And there should be no way to get an earlier version deleting a later version.

_weave: Text of the weave; list of control instruction tuples and strings.
_parents: List of parents, indexed by version number. It is only necessary to store the minimal set of parents for each version; the parent's parents are implied.
_sha1s: List of hex SHA-1 of each version.
_names: List of symbolic names for each version. Each should be unique.
_name_map: For each name, the version number.
_weave_name: Descriptive name of this weave; typically the filename if known. Set by read_weave.

Method	__init__	Create a weave.
Method	__repr__	Undocumented
Method	copy	Return a deep copy of self.
Method	__eq__	Undocumented
Method	__ne__	Undocumented
Method	versions	See VersionedFile.versions.
Method	has_version	See VersionedFile.has_version.
Method	get_record_stream	Get a stream of records for versions.
Method	get_parent_map	See VersionedFile.get_parent_map.
Method	get_parents_with_ghosts	Return version names for parents of version_id.
Method	insert_record_stream	Insert a record stream into this versioned file.
Method	get_ancestry	See VersionedFile.get_ancestry.
Method	annotate	Return a list of (version-id, line) tuples for version_id.
Method	iter_lines_added_or_present_in_versions	See VersionedFile.iter_lines_added_or_present_in_versions().
Method	plan_merge	Return pseudo-annotation indicating how the two versions merge.
Method	get_lines	See VersionedFile.get_lines().
Method	get_sha1s	See VersionedFile.get_sha1s().
Method	num_versions	How many versions are in this weave?
Method	check	Check the versioned file for integrity.
Method	_check_write_ok	Is the versioned file marked as 'finished' ? Raise if it is.
Method	_idx_to_name	Undocumented
Method	_lookup	Convert symbolic version name to index.
Method	_check_repeated_add	Check that a duplicated add is OK.
Method	_add_lines	See VersionedFile.add_lines.
Method	_add	Add a single text on top of the weave.
Method	_inclusions	Return set of all ancestors of given version(s).
Method	_check_lines	Undocumented
Method	_check_versions	Check everything in the sequence of indexes is valid
Method	_compatible_parents	During join check that other_parents are joinable with my_parents.
Method	_walk_internal	Helper method for weave actions.
Method	_extract	Yield annotation of lines in included set.
Method	_maybe_lookup	Convert possible symbolic name to index, or pass through indexes.
Method	_imported_parents	Return list of parents in self corresponding to indexes in other.
Method	_check_version_consistent	Check if a version in consistent in this and other.
Method	_reweave	Reweave self with other - internal helper for join().
Method	_copy_weave_content	adsorb the content from otherweave.

Inherited from VersionedFile:

Static Method	check_not_reserved_id	Undocumented
Method	copy_to	Copy this versioned file to name on transport.
Method	add_lines	Add a single text on top of the versioned file.
Method	add_lines_with_ghosts	Add lines to the versioned file, allowing ghosts to be present.
Method	get_format_signature	Get a text description of the data encoding in this file.
Method	make_mpdiffs	Create multiparent diffs for specified versions.
Method	add_mpdiffs	Add mpdiffs to this VersionedFile.
Method	get_text	Return version contents as a text string.
Method	get_texts	Return the texts of listed versions as a list of strings.
Method	get_ancestry_with_ghosts	Return a list of all ancestors of given version(s). This
Method	weave_merge	Undocumented
Method	_add_lines_with_ghosts	Helper to do class specific add_lines_with_ghosts.
Method	_check_lines_not_unicode	Check that lines being added to a versioned file are not unicode.
Method	_check_lines_are_lines	Check that the lines really are full lines without inline EOL.
Method	_extract_blocks	Undocumented
Method	_get_lf_split_line_list	Undocumented

Create a weave.

Parameters get_scope A callable that returns an opaque object to be used for detecting when this weave goes out of scope (should stop answering requests or allowing mutation).

Is the versioned file marked as 'finished' ? Raise if it is.

Return a deep copy of self.

The copy can be modified without affecting the original weave.

Convert symbolic version name to index.

See VersionedFile.versions.

See VersionedFile.has_version.

Get a stream of records for versions.

Parameters	versions	The versions to include. Each version is a tuple (version,).
	ordering	Either 'unordered' or 'topological'. A topologically sorted stream has compression parents strictly before their children.
	include_delta_closure	If True then the closure across any compression parents will be included (in the opaque data).
Returns	An iterator of ContentFactory objects, each of which is only valid until the iterator is advanced.

See VersionedFile.get_parent_map.

Return version names for parents of version_id.

Will raise RevisionNotPresent if version_id is not present in the history.

Ghosts that are known about will be included in the parent list, but are not explicitly marked.

Insert a record stream into this versioned file.

Parameters	stream	A stream of records to insert.
Returns	None
See Also

Check that a duplicated add is OK.

If it is, return the (old) index; otherwise raise an exception.

See VersionedFile.add_lines.

Add a single text on top of the weave.

Returns the index number of the newly added version.

version_id: Symbolic name for this version. (Typically the revision-id of the revision that added it.) If None, a name will be allocated based on the hash. (sha1:SHAHASH)
parents: List or set of direct parent version numbers.
lines: Sequence of lines to be added in the new version.

Parameters nostore_sha See VersionedFile.add_lines.

Return set of all ancestors of given version(s).

See VersionedFile.get_ancestry.

Check everything in the sequence of indexes is valid

During join check that other_parents are joinable with my_parents.

Joinable is defined as 'is a subset of' - supersets may require regeneration of diffs, but subsets do not.

Return a list of (version-id, line) tuples for version_id.

The index indicates when the line originated in the weave.

See VersionedFile.iter_lines_added_or_present_in_versions().

Helper method for weave actions.

Return pseudo-annotation indicating how the two versions merge.

This is computed between versions a and b and their common base.

Weave lines present in none of them are skipped entirely.

Yield annotation of lines in included set.

Yields a sequence of tuples (origin, lineno, text), where origin is the origin version, lineno the index in the weave, and text the text of the line.

The set typically but not necessarily corresponds to a version.

Convert possible symbolic name to index, or pass through indexes.

NOT FOR PUBLIC USE.

See VersionedFile.get_lines().

See VersionedFile.get_sha1s().

How many versions are in this weave?

Check the versioned file for integrity.

Return list of parents in self corresponding to indexes in other.

Check if a version in consistent in this and other.

To be consistent it must have:

the same text

the same direct parents (by name, not index, and disregarding order)

If present & correct return True; if not present in self return False; if inconsistent raise error.

Reweave self with other - internal helper for join().

Parameters	other	The other weave to merge
	pb	An optional progress bar, indicating how far done we are
	msg	An optional message for the progress

adsorb the content from otherweave.

b.w.Weave(VersionedFile) : class documentation