1
# Copyright (C) 2005 by Canonical Ltd
4
# Johan Rydberg <jrydberg@gnu.org>
6
# This program is free software; you can redistribute it and/or modify
7
# it under the terms of the GNU General Public License as published by
8
# the Free Software Foundation; either version 2 of the License, or
9
# (at your option) any later version.
11
# This program is distributed in the hope that it will be useful,
12
# but WITHOUT ANY WARRANTY; without even the implied warranty of
13
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14
# GNU General Public License for more details.
16
# You should have received a copy of the GNU General Public License
17
# along with this program; if not, write to the Free Software
18
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20
# Remaing to do is to figure out if get_graph should return a simple
21
# map, or a graph object of some kind.
24
"""Versioned text file storage api."""
27
from copy import deepcopy
28
from unittest import TestSuite
31
import bzrlib.errors as errors
32
from bzrlib.inter import InterObject
33
from bzrlib.symbol_versioning import *
34
from bzrlib.transport.memory import MemoryTransport
35
from bzrlib.tsort import topo_sort
39
class VersionedFile(object):
40
"""Versioned text file storage.
42
A versioned file manages versions of line-based text files,
43
keeping track of the originating version for each line.
45
To clients the "lines" of the file are represented as a list of
46
strings. These strings will typically have terminal newline
47
characters, but this is not required. In particular files commonly
48
do not have a newline at the end of the file.
50
Texts are identified by a version-id string.
53
def __init__(self, access_mode):
55
self._access_mode = access_mode
57
def copy_to(self, name, transport):
58
"""Copy this versioned file to name on transport."""
59
raise NotImplementedError(self.copy_to)
61
@deprecated_method(zero_eight)
63
"""Return a list of all the versions in this versioned file.
65
Please use versionedfile.versions() now.
67
return self.versions()
70
"""Return a unsorted list of versions."""
71
raise NotImplementedError(self.versions)
73
def has_ghost(self, version_id):
74
"""Returns whether version is present as a ghost."""
75
raise NotImplementedError(self.has_ghost)
77
def has_version(self, version_id):
78
"""Returns whether version is present."""
79
raise NotImplementedError(self.has_version)
81
def add_delta(self, version_id, parents, delta_parent, sha1, noeol, delta):
82
"""Add a text to the versioned file via a pregenerated delta.
84
:param version_id: The version id being added.
85
:param parents: The parents of the version_id.
86
:param delta_parent: The parent this delta was created against.
87
:param sha1: The sha1 of the full text.
88
:param delta: The delta instructions. See get_delta for details.
90
self._check_write_ok()
91
if self.has_version(version_id):
92
raise errors.RevisionAlreadyPresent(version_id, self)
93
return self._add_delta(version_id, parents, delta_parent, sha1, noeol, delta)
95
def _add_delta(self, version_id, parents, delta_parent, sha1, noeol, delta):
96
"""Class specific routine to add a delta.
98
This generic version simply applies the delta to the delta_parent and
101
# strip annotation from delta
103
for start, stop, delta_len, delta_lines in delta:
104
new_delta.append((start, stop, delta_len, [text for origin, text in delta_lines]))
105
if delta_parent is not None:
106
parent_full = self.get_lines(delta_parent)
109
new_full = self._apply_delta(parent_full, new_delta)
110
# its impossible to have noeol on an empty file
111
if noeol and new_full[-1][-1] == '\n':
112
new_full[-1] = new_full[-1][:-1]
113
self.add_lines(version_id, parents, new_full)
115
def add_lines(self, version_id, parents, lines, parent_texts=None):
116
"""Add a single text on top of the versioned file.
118
Must raise RevisionAlreadyPresent if the new version is
119
already present in file history.
121
Must raise RevisionNotPresent if any of the given parents are
122
not present in file history.
123
:param parent_texts: An optional dictionary containing the opaque
124
representations of some or all of the parents of
125
version_id to allow delta optimisations.
126
VERY IMPORTANT: the texts must be those returned
127
by add_lines or data corruption can be caused.
128
:return: An opaque representation of the inserted version which can be
129
provided back to future add_lines calls in the parent_texts
132
self._check_write_ok()
133
return self._add_lines(version_id, parents, lines, parent_texts)
135
def _add_lines(self, version_id, parents, lines, parent_texts):
136
"""Helper to do the class specific add_lines."""
137
raise NotImplementedError(self.add_lines)
139
def add_lines_with_ghosts(self, version_id, parents, lines,
141
"""Add lines to the versioned file, allowing ghosts to be present.
143
This takes the same parameters as add_lines.
145
self._check_write_ok()
146
return self._add_lines_with_ghosts(version_id, parents, lines,
149
def _add_lines_with_ghosts(self, version_id, parents, lines, parent_texts):
150
"""Helper to do class specific add_lines_with_ghosts."""
151
raise NotImplementedError(self.add_lines_with_ghosts)
153
def check(self, progress_bar=None):
154
"""Check the versioned file for integrity."""
155
raise NotImplementedError(self.check)
157
def _check_lines_not_unicode(self, lines):
158
"""Check that lines being added to a versioned file are not unicode."""
160
if line.__class__ is not str:
161
raise errors.BzrBadParameterUnicode("lines")
163
def _check_lines_are_lines(self, lines):
164
"""Check that the lines really are full lines without inline EOL."""
166
if '\n' in line[:-1]:
167
raise errors.BzrBadParameterContainsNewline("lines")
169
def _check_write_ok(self):
170
"""Is the versioned file marked as 'finished' ? Raise if it is."""
172
raise errors.OutSideTransaction()
173
if self._access_mode != 'w':
174
raise errors.ReadOnlyObjectDirtiedError(self)
176
def clear_cache(self):
177
"""Remove any data cached in the versioned file object."""
179
def clone_text(self, new_version_id, old_version_id, parents):
180
"""Add an identical text to old_version_id as new_version_id.
182
Must raise RevisionNotPresent if the old version or any of the
183
parents are not present in file history.
185
Must raise RevisionAlreadyPresent if the new version is
186
already present in file history."""
187
self._check_write_ok()
188
return self._clone_text(new_version_id, old_version_id, parents)
190
def _clone_text(self, new_version_id, old_version_id, parents):
191
"""Helper function to do the _clone_text work."""
192
raise NotImplementedError(self.clone_text)
194
def create_empty(self, name, transport, mode=None):
195
"""Create a new versioned file of this exact type.
197
:param name: the file name
198
:param transport: the transport
199
:param mode: optional file mode.
201
raise NotImplementedError(self.create_empty)
203
def fix_parents(self, version, new_parents):
204
"""Fix the parents list for version.
206
This is done by appending a new version to the index
207
with identical data except for the parents list.
208
the parents list must be a superset of the current
211
self._check_write_ok()
212
return self._fix_parents(version, new_parents)
214
def _fix_parents(self, version, new_parents):
215
"""Helper for fix_parents."""
216
raise NotImplementedError(self.fix_parents)
218
def get_delta(self, version):
219
"""Get a delta for constructing version from some other version.
221
:return: (delta_parent, sha1, noeol, delta)
222
Where delta_parent is a version id or None to indicate no parent.
224
raise NotImplementedError(self.get_delta)
226
def get_deltas(self, versions):
227
"""Get multiple deltas at once for constructing versions.
229
:return: dict(version_id:(delta_parent, sha1, noeol, delta))
230
Where delta_parent is a version id or None to indicate no parent, and
231
version_id is the version_id created by that delta.
234
for version in versions:
235
result[version] = self.get_delta(version)
238
def get_sha1(self, version_id):
239
"""Get the stored sha1 sum for the given revision.
241
:param name: The name of the version to lookup
243
raise NotImplementedError(self.get_sha1)
245
def get_suffixes(self):
246
"""Return the file suffixes associated with this versioned file."""
247
raise NotImplementedError(self.get_suffixes)
249
def get_text(self, version_id):
250
"""Return version contents as a text string.
252
Raises RevisionNotPresent if version is not present in
255
return ''.join(self.get_lines(version_id))
256
get_string = get_text
258
def get_lines(self, version_id):
259
"""Return version contents as a sequence of lines.
261
Raises RevisionNotPresent if version is not present in
264
raise NotImplementedError(self.get_lines)
266
def get_ancestry(self, version_ids):
267
"""Return a list of all ancestors of given version(s). This
268
will not include the null revision.
270
Must raise RevisionNotPresent if any of the given versions are
271
not present in file history."""
272
if isinstance(version_ids, basestring):
273
version_ids = [version_ids]
274
raise NotImplementedError(self.get_ancestry)
276
def get_ancestry_with_ghosts(self, version_ids):
277
"""Return a list of all ancestors of given version(s). This
278
will not include the null revision.
280
Must raise RevisionNotPresent if any of the given versions are
281
not present in file history.
283
Ghosts that are known about will be included in ancestry list,
284
but are not explicitly marked.
286
raise NotImplementedError(self.get_ancestry_with_ghosts)
289
"""Return a graph for the entire versioned file.
291
Ghosts are not listed or referenced in the graph.
294
for version in self.versions():
295
result[version] = self.get_parents(version)
298
def get_graph_with_ghosts(self):
299
"""Return a graph for the entire versioned file.
301
Ghosts are referenced in parents list but are not
304
raise NotImplementedError(self.get_graph_with_ghosts)
306
@deprecated_method(zero_eight)
307
def parent_names(self, version):
308
"""Return version names for parents of a version.
310
See get_parents for the current api.
312
return self.get_parents(version)
314
def get_parents(self, version_id):
315
"""Return version names for parents of a version.
317
Must raise RevisionNotPresent if version is not present in
320
raise NotImplementedError(self.get_parents)
322
def get_parents_with_ghosts(self, version_id):
323
"""Return version names for parents of version_id.
325
Will raise RevisionNotPresent if version_id is not present
328
Ghosts that are known about will be included in the parent list,
329
but are not explicitly marked.
331
raise NotImplementedError(self.get_parents_with_ghosts)
333
def annotate_iter(self, version_id):
334
"""Yield list of (version-id, line) pairs for the specified
337
Must raise RevisionNotPresent if any of the given versions are
338
not present in file history.
340
raise NotImplementedError(self.annotate_iter)
342
def annotate(self, version_id):
343
return list(self.annotate_iter(version_id))
345
def _apply_delta(self, lines, delta):
346
"""Apply delta to lines."""
349
for start, end, count, delta_lines in delta:
350
lines[offset+start:offset+end] = delta_lines
351
offset = offset + (start - end) + count
354
def join(self, other, pb=None, msg=None, version_ids=None,
355
ignore_missing=False):
356
"""Integrate versions from other into this versioned file.
358
If version_ids is None all versions from other should be
359
incorporated into this versioned file.
361
Must raise RevisionNotPresent if any of the specified versions
362
are not present in the other files history unless ignore_missing
363
is supplied when they are silently skipped.
365
self._check_write_ok()
366
return InterVersionedFile.get(other, self).join(
372
def iter_lines_added_or_present_in_versions(self, version_ids=None):
373
"""Iterate over the lines in the versioned file from version_ids.
375
This may return lines from other versions, and does not return the
376
specific version marker at this point. The api may be changed
377
during development to include the version that the versioned file
378
thinks is relevant, but given that such hints are just guesses,
379
its better not to have it if we dont need it.
381
NOTES: Lines are normalised: they will all have \n terminators.
382
Lines are returned in arbitrary order.
384
raise NotImplementedError(self.iter_lines_added_or_present_in_versions)
386
def transaction_finished(self):
387
"""The transaction that this file was opened in has finished.
389
This records self.finished = True and should cause all mutating
394
@deprecated_method(zero_eight)
395
def walk(self, version_ids=None):
396
"""Walk the versioned file as a weave-like structure, for
397
versions relative to version_ids. Yields sequence of (lineno,
398
insert, deletes, text) for each relevant line.
400
Must raise RevisionNotPresent if any of the specified versions
401
are not present in the file history.
403
:param version_ids: the version_ids to walk with respect to. If not
404
supplied the entire weave-like structure is walked.
406
walk is deprecated in favour of iter_lines_added_or_present_in_versions
408
raise NotImplementedError(self.walk)
410
@deprecated_method(zero_eight)
411
def iter_names(self):
412
"""Walk the names list."""
413
return iter(self.versions())
415
def plan_merge(self, ver_a, ver_b):
416
"""Return pseudo-annotation indicating how the two versions merge.
418
This is computed between versions a and b and their common
421
Weave lines present in none of them are skipped entirely.
423
inc_a = set(self.get_ancestry([ver_a]))
424
inc_b = set(self.get_ancestry([ver_b]))
425
inc_c = inc_a & inc_b
427
for lineno, insert, deleteset, line in self.walk([ver_a, ver_b]):
428
if deleteset & inc_c:
429
# killed in parent; can't be in either a or b
430
# not relevant to our work
431
yield 'killed-base', line
432
elif insert in inc_c:
433
# was inserted in base
434
killed_a = bool(deleteset & inc_a)
435
killed_b = bool(deleteset & inc_b)
436
if killed_a and killed_b:
437
yield 'killed-both', line
439
yield 'killed-a', line
441
yield 'killed-b', line
443
yield 'unchanged', line
444
elif insert in inc_a:
445
if deleteset & inc_a:
446
yield 'ghost-a', line
450
elif insert in inc_b:
451
if deleteset & inc_b:
452
yield 'ghost-b', line
456
# not in either revision
457
yield 'irrelevant', line
459
yield 'unchanged', '' # terminator
461
def weave_merge(self, plan, a_marker='<<<<<<< \n', b_marker='>>>>>>> \n'):
465
# TODO: Return a structured form of the conflicts (e.g. 2-tuples for
466
# conflicted regions), rather than just inserting the markers.
468
# TODO: Show some version information (e.g. author, date) on
469
# conflicted regions.
471
# We previously considered either 'unchanged' or 'killed-both' lines
472
# to be possible places to resynchronize. However, assuming agreement
473
# on killed-both lines may be too agressive. -- mbp 20060324
474
for state, line in plan:
475
if state == 'unchanged':
476
# resync and flush queued conflicts changes if any
477
if not lines_a and not lines_b:
479
elif ch_a and not ch_b:
481
for l in lines_a: yield l
482
elif ch_b and not ch_a:
483
for l in lines_b: yield l
484
elif lines_a == lines_b:
485
for l in lines_a: yield l
488
for l in lines_a: yield l
490
for l in lines_b: yield l
497
if state == 'unchanged':
500
elif state == 'killed-a':
503
elif state == 'killed-b':
506
elif state == 'new-a':
509
elif state == 'new-b':
513
assert state in ('irrelevant', 'ghost-a', 'ghost-b', 'killed-base',
518
class InterVersionedFile(InterObject):
519
"""This class represents operations taking place between two versionedfiles..
521
Its instances have methods like join, and contain
522
references to the source and target versionedfiles these operations can be
525
Often we will provide convenience methods on 'versionedfile' which carry out
526
operations with another versionedfile - they will always forward to
527
InterVersionedFile.get(other).method_name(parameters).
531
"""The available optimised InterVersionedFile types."""
533
def join(self, pb=None, msg=None, version_ids=None, ignore_missing=False):
534
"""Integrate versions from self.source into self.target.
536
If version_ids is None all versions from source should be
537
incorporated into this versioned file.
539
Must raise RevisionNotPresent if any of the specified versions
540
are not present in the other files history unless ignore_missing is
541
supplied when they are silently skipped.
544
# - if the target is empty, just add all the versions from
545
# source to target, otherwise:
546
# - make a temporary versioned file of type target
547
# - insert the source content into it one at a time
549
if not self.target.versions():
552
# Make a new target-format versioned file.
553
temp_source = self.target.create_empty("temp", MemoryTransport())
555
graph = self.source.get_graph()
556
order = topo_sort(graph.items())
557
pb = ui.ui_factory.nested_progress_bar()
560
# TODO for incremental cross-format work:
561
# make a versioned file with the following content:
562
# all revisions we have been asked to join
563
# all their ancestors that are *not* in target already.
564
# the immediate parents of the above two sets, with
565
# empty parent lists - these versions are in target already
566
# and the incorrect version data will be ignored.
567
# TODO: for all ancestors that are present in target already,
568
# check them for consistent data, this requires moving sha1 from
570
# TODO: remove parent texts when they are not relevant any more for
571
# memory pressure reduction. RBC 20060313
572
# pb.update('Converting versioned data', 0, len(order))
573
# deltas = self.source.get_deltas(order)
574
for index, version in enumerate(order):
575
pb.update('Converting versioned data', index, len(order))
576
parent_text = target.add_lines(version,
577
self.source.get_parents(version),
578
self.source.get_lines(version),
579
parent_texts=parent_texts)
580
parent_texts[version] = parent_text
581
#delta_parent, sha1, noeol, delta = deltas[version]
582
#target.add_delta(version,
583
# self.source.get_parents(version),
588
#target.get_lines(version)
590
# this should hit the native code path for target
591
if target is not self.target:
592
return self.target.join(temp_source,
601
class InterVersionedFileTestProviderAdapter(object):
602
"""A tool to generate a suite testing multiple inter versioned-file classes.
604
This is done by copying the test once for each interversionedfile provider
605
and injecting the transport_server, transport_readonly_server,
606
versionedfile_factory and versionedfile_factory_to classes into each copy.
607
Each copy is also given a new id() to make it easy to identify.
610
def __init__(self, transport_server, transport_readonly_server, formats):
611
self._transport_server = transport_server
612
self._transport_readonly_server = transport_readonly_server
613
self._formats = formats
615
def adapt(self, test):
617
for (interversionedfile_class,
618
versionedfile_factory,
619
versionedfile_factory_to) in self._formats:
620
new_test = deepcopy(test)
621
new_test.transport_server = self._transport_server
622
new_test.transport_readonly_server = self._transport_readonly_server
623
new_test.interversionedfile_class = interversionedfile_class
624
new_test.versionedfile_factory = versionedfile_factory
625
new_test.versionedfile_factory_to = versionedfile_factory_to
626
def make_new_test_id():
627
new_id = "%s(%s)" % (new_test.id(), interversionedfile_class.__name__)
628
return lambda: new_id
629
new_test.id = make_new_test_id()
630
result.addTest(new_test)
634
def default_test_list():
635
"""Generate the default list of interversionedfile permutations to test."""
636
from bzrlib.weave import WeaveFile
637
from bzrlib.knit import KnitVersionedFile
639
# test the fallback InterVersionedFile from weave to annotated knits
640
result.append((InterVersionedFile,
643
for optimiser in InterVersionedFile._optimisers:
644
result.append((optimiser,
645
optimiser._matching_file_factory,
646
optimiser._matching_file_factory
648
# if there are specific combinations we want to use, we can add them
added
removed
bzrlib/versionedfile.py
