b.v.VersionedFiles(object) : class documentation

Part of bzrlib.versionedfile View In Hierarchy

Known subclasses: bzrlib.plugins.weave_fmt.repository.TextVersionedFiles, bzrlib.versionedfile._PlanMergeVersionedFile, bzrlib.versionedfile.ThunkedVersionedFiles, bzrlib.versionedfile.VersionedFilesWithFallbacks, bzrlib.versionedfile.VirtualVersionedFiles

Storage for many versioned files.

This object allows a single keyspace for accessing the history graph and contents of named bytestrings.

Currently no implementation allows the graph of different key prefixes to intersect, but the API does allow such implementations in the future.

The keyspace is expressed via simple tuples. Any instance of VersionedFiles may have a different length key-size, but that size will be constant for all texts added to or retrieved from it. For instance, bzrlib uses instances with a key-size of 2 for storing user files in a repository, with the first element the fileid, and the second the version of that file.

The use of tuples allows a single code base to support several different uses with only the mapping logic changing from instance to instance.

Instance Variables_immediate_fallback_vfsFor subclasses that support stacking, this is a list of other VersionedFiles immediately underneath this one. They may in turn each have further fallbacks.
Method add_lines Add a text to the store.
Method add_mpdiffs Add mpdiffs to this VersionedFile.
Method annotate Return a list of (version-key, line) tuples for the text of key.
Method check Check this object for integrity.
Static Method check_not_reserved_id Undocumented
Method clear_cache Clear whatever caches this VersionedFile holds.
Method get_known_graph_ancestry Get a KnownGraph instance with the ancestry of keys.
Method get_parent_map Get a map of the parents of keys.
Method get_record_stream Get a stream of records for keys.
Method get_sha1s Get the sha1's of the texts for the given keys.
Method get_missing_compression_parent_keys Return an iterable of keys of missing compression parents.
Method insert_record_stream Insert a record stream into this container.
Method iter_lines_added_or_present_in_keys Iterate over the lines in the versioned files from keys.
Method keys Return a iterable of the keys for all the contained texts.
Method make_mpdiffs Create multiparent diffs for specified keys.
Method get_annotator Undocumented
Method _add_text Add a text to the store.
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 _transitive_fallbacks Return the whole stack of fallback versionedfiles.
def add_lines(self, key, parents, lines, parent_texts=None, left_matching_blocks=None, nostore_sha=None, random_id=False, check_content=True):
Add a text to the store.

        :param key: The key tuple of the text to add. If the last element is
            None, a CHK string will be generated during the addition.
        :param parents: The parents key tuples of the text to add.
        :param lines: A list of lines. Each line must be a bytestring. And all
            of them except the last must be terminated with 
 and contain no
            other 
's. The last line may either contain no 
's or a single
            terminating 
. If the lines list does meet this constraint the add
            routine may error or may succeed - but you will be unable to read
            the data back accurately. (Checking the lines have been split
            correctly is expensive and extremely unlikely to catch bugs so it
            is not done at runtime unless check_content is True.)
        :param parent_texts: An optional dictionary containing the opaque
            representations of some or all of the parents of version_id to
            allow delta optimisations.  VERY IMPORTANT: the texts must be those
            returned by add_lines or data corruption can be caused.
        :param left_matching_blocks: a hint about which areas are common
            between the text and its left-hand-parent.  The format is
            the SequenceMatcher.get_matching_blocks format.
        :param nostore_sha: Raise ExistingContent and do not add the lines to
            the versioned file if the digest of the lines matches this.
        :param random_id: If True a random id has been selected rather than
            an id determined by some deterministic process such as a converter
            from a foreign VCS. When True the backend may choose not to check
            for uniqueness of the resulting key within the versioned file, so
            this should only be done when the result is expected to be unique
            anyway.
        :param check_content: If True, the lines supplied are verified to be
            bytestrings that are correctly formed lines.
        :return: The text sha1, the number of bytes in the text, and an opaque
                 representation of the inserted version which can be provided
                 back to future add_lines calls in the parent_texts dictionary.
        
def _add_text(self, key, parents, text, nostore_sha=None, random_id=False):
Add a text to the store.

This is a private function for use by VersionedFileCommitBuilder.

ParameterskeyThe key tuple of the text to add. If the last element is None, a CHK string will be generated during the addition.
parentsThe parents key tuples of the text to add.
textA string containing the text to be committed.
nostore_shaRaise ExistingContent and do not add the lines to the versioned file if the digest of the lines matches this.
random_idIf True a random id has been selected rather than an id determined by some deterministic process such as a converter from a foreign VCS. When True the backend may choose not to check for uniqueness of the resulting key within the versioned file, so this should only be done when the result is expected to be unique anyway.
check_contentIf True, the lines supplied are verified to be bytestrings that are correctly formed lines.
ReturnsThe text sha1, the number of bytes in the text, and an opaque representation of the inserted version which can be provided back to future _add_text calls in the parent_texts dictionary.
def add_mpdiffs(self, records):
Add mpdiffs to this VersionedFile.

Records should be iterables of version, parents, expected_sha1, mpdiff. mpdiff should be a MultiParent instance.

def annotate(self, key):
Return a list of (version-key, line) tuples for the text of key.
RaisesRevisionNotPresentIf the key is not present.
def check(self, progress_bar=None):
Check this object for integrity.
Parametersprogress_barA progress bar to output as the check progresses.
keysSpecific keys within the VersionedFiles to check. When this parameter is not None, check() becomes a generator as per get_record_stream. The difference to get_record_stream is that more or deeper checks will be performed.
ReturnsNone, or if keys was supplied a generator as per get_record_stream.
@staticmethod
def check_not_reserved_id(version_id):
Undocumented
def clear_cache(self):
Clear whatever caches this VersionedFile holds.

This is generally called after an operation has been performed, when we don't expect to be using this versioned file again soon.

def _check_lines_not_unicode(self, lines):
Check that lines being added to a versioned file are not unicode.
def _check_lines_are_lines(self, lines):
Check that the lines really are full lines without inline EOL.
def get_known_graph_ancestry(self, keys):
Get a KnownGraph instance with the ancestry of keys.
def get_parent_map(self, keys):
Get a map of the parents of keys.
ParameterskeysThe keys to look up parents for.
ReturnsA mapping from keys to parents. Absent keys are absent from the mapping.
def get_record_stream(self, keys, ordering, include_delta_closure):
Get a stream of records for keys.
ParameterskeysThe keys to include.
orderingEither 'unordered' or 'topological'. A topologically sorted stream has compression parents strictly before their children.
include_delta_closureIf True then the closure across any compression parents will be included (in the opaque data).
ReturnsAn iterator of ContentFactory objects, each of which is only valid until the iterator is advanced.
def get_sha1s(self, keys):
Get the sha1's of the texts for the given keys.
ParameterskeysThe names of the keys to lookup
Returnsa dict from key to sha1 digest. Keys of texts which are not present in the store are not present in the returned dictionary.
def get_missing_compression_parent_keys(self):
Return an iterable of keys of missing compression parents.

Check this after calling insert_record_stream to find out if there are any missing compression parents. If there are, the records that depend on them are not able to be inserted safely. The precise behaviour depends on the concrete VersionedFiles class in use.

Classes that do not support this will raise NotImplementedError.

def insert_record_stream(self, stream):
Insert a record stream into this container.
ParametersstreamA stream of records to insert.
ReturnsNone
See Also
def iter_lines_added_or_present_in_keys(self, keys, pb=None):

Iterate over the lines in the versioned files from keys.

This may return lines from other keys. Each item the returned iterator yields is a tuple of a line and a text version that that line is present in (not introduced in).

Ordering of results is in whatever order is most suitable for the underlying storage format.

If a progress bar is supplied, it may be used to indicate progress. The caller is responsible for cleaning up progress bars (because this is an iterator).

NOTES:
  • Lines are normalised by the underlying store: they will all have

    terminators.

  • Lines are returned in arbitrary order.

ReturnsAn iterator over (line, key).
def keys(self):
Return a iterable of the keys for all the contained texts.
def make_mpdiffs(self, keys):
Create multiparent diffs for specified keys.
def get_annotator(self):
Undocumented
def _extract_blocks(self, version_id, source, target):
Undocumented
def _transitive_fallbacks(self):
Return the whole stack of fallback versionedfiles.

This VersionedFiles may have a list of fallbacks, but it doesn't necessarily know about the whole stack going down, and it can't know at open time because they may change after the objects are opened.

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