← Back to branch summary

~loggerhead-team/loggerhead/trunk-rich

« back to all changes in this revision

Viewing changes to loggerhead/history2.py

  • Committer: Ian Clatworthy
  • Date: 2010-04-14 06:34:41 UTC
  • Revision ID: ian.clatworthy@canonical.com-20100414063441-a4yikrgjgxyb0yk5
Simplify .bzrignore

Show diffs side-by-side

added added

removed removed

Lines of Context:
loggerhead/history2.py
1
 
"""Extract data suitable for web presentation from Bazaar branches.
2
 
 
3
 
The module is the interface between Loggerhead and bzrlib.  Other code in
4
 
Loggerhead should not use bzrlib APIs, and functions and methods in this
5
 
module should not return bzrlib data types.
6
 
 
7
 
The core method is `History.getRevisionInfo`.  This method is meant to be
8
 
cheap, so you should not worry about calling it multiple times with the same
9
 
argument or calling it just to retreive a subset of the information it
10
 
returns.
11
 
 
12
 
Revisions are described using good old bzrlib revision ids.
13
 
 
14
 
Revision ids, file ids, file names and file paths are always utf-8 encoded 8
15
 
bit strings.
16
 
"""
17
 
 
18
 
class FileDelta(object):
19
 
    """Information about how an inventory entry changed in a revision.
20
 
 
21
 
    All attribute names are fairly self explanatory.  The ``*_parent`` fields
22
 
    are the file id of the parent or ``None`` for the root.
23
 
 
24
 
    :ivar file_id:
25
 
    :ivar old_path:
26
 
    :ivar new_path:
27
 
    :ivar old_name:
28
 
    :ivar new_name:
29
 
    :ivar old_parent:
30
 
    :ivar new_parent:
31
 
    :ivar old_kind:
32
 
    :ivar new_kind:
33
 
    :ivar content_change:
34
 
    :type content_change: ``bool``
35
 
    :ivar execute_change: A boolean reflecting the new state if it changed, or
36
 
                          ``None`` if it did not.
37
 
    :type execute_change: ``bool`` or ``None``
38
 
    """
39
 
 
40
 
 
41
 
class FileChanges(object):
42
 
    """Contains information about which files changed in a revision.
43
 
 
44
 
    Note that the 'files changed' information is relative to left-most parent
45
 
    by default, as in 'bzr log -v'.
46
 
 
47
 
    :ivar deltas: A list of `FileDelta` objects.
48
 
    :ivar fileset: ``set(d.file_id for d in self.deltas)``, but cached.
49
 
    """
50
 
 
51
 
class RevisionInfo(object):
52
 
    """Contains all the immutable information Loggerhead needs about a
53
 
    particular revision.
54
 
 
55
 
    :ivar revid: Obvious.
56
 
    :ivar date: The date and time this revision was committed.
57
 
    :type date: ``datetime.datetime``
58
 
    :ivar committer: The committer.
59
 
    :type committer: utf-8 encoded ``str``
60
 
    :ivar revprops: The branch properties.
61
 
    :type revprops: A dictionary mapping ``str``\ s to ``str``\ s (both utf-8
62
 
                    encoded).
63
 
    :ivar message: The commit message of this revision.
64
 
    :type message: utf-8 encoded ``str``
65
 
    :ivar parents: The list of the revids of the revision's parents.
66
 
    """
67
 
 
68
 
class BranchRevisionInfo(object):
69
 
    """Contains all the mutable information Loggerhead needs about a
70
 
    particular revision, and points to the immutable data.
71
 
 
72
 
    :ivar revno: The dotted revno of this revision in this branch.
73
 
    :type revno: ``str``
74
 
    :ivar where_merged: The list of revids that have this revision as a
75
 
                        parent.
76
 
    :ivar info: The corresponding `RevisionInfo`.
77
 
    """
78
 
 
79
 
class FileEntry(object):
80
 
    """An entry in the list returned by `getFileList`.
81
 
 
82
 
    :ivar path: The path of the object in the revision passed to
83
 
                `getFileList`.
84
 
    :ivar fileid: Obvious.
85
 
    :ivar kind: one of ``'file'``, ``'executable'``, ``'link'`` or
86
 
                ``'directory'``.
87
 
    :type kind: ``str``
88
 
    :ivar last_changed_revid: The revid of the revision in which this path
89
 
                              last changed.  Not that this is recursive,
90
 
                              i.e. the last_changed_revid for a directory is
91
 
                              the revid in which the directory or anything
92
 
                              contained in in changed.x
93
 
    :ivar size: The size of this object in this revision in bytes.
94
 
    :type size: ``int``
95
 
    """
96
 
 
97
 
class History(object):
98
 
    """Provide the information loggerhead needs about a bzrlib Branch.
99
 
 
100
 
    An instance of this class is effectively a wrapper around a
101
 
    `bzrlib.branch.Branch` that translates the information provided by bzrlib
102
 
    into a form convenient for use in loggerhead.
103
 
 
104
 
    :ivar last_revision: The revid of the tip of the branch.
105
 
    """
106
 
 
107
 
    @classmethod
108
 
    def fromBranch(cls, branch):
109
 
        """Create and initialize a `History` object from a
110
 
        `bzrlib.branch.Branch`.
111
 
        """
112
 
 
113
 
    def outOfDate(self):
114
 
        """Decide whether this History object is still current.
115
 
 
116
 
        At least to start with, an out of date History object should be thrown
117
 
        away and a fresh one created.
118
 
        """
119
 
 
120
 
    def getRevisionInfo(self, revid):
121
 
        """Find the `BranchRevisionInfo` object for a given revision id.
122
 
 
123
 
        This operation is to be thought of as 'cheap', which is to say that
124
 
        you should not worry about calling it repeatedly with the same
125
 
        argument or about calling it just to retrieve a subset of the
126
 
        information it includes.
127
 
 
128
 
        :param revid: a revision id.
129
 
        :returns: a `BranchRevisionInfo` object or ``None`` if the given
130
 
                  revision id does not exist in the branch.
131
 
        """
132
 
 
133
 
    def getChanges(self, revid, other_revid=None):
134
 
        """Find the `FileChanges` object between two revision.
135
 
 
136
 
        :param revid: A revision id.
137
 
        :param other_revid: The revision id to compare against.  If ``None``
138
 
                            or not given, compare against the leftmost parent
139
 
                            of ``revid``.
140
 
        :returns: The corresponding `FileChanges` object.
141
 
        """
142
 
 
143
 
    # There will need to be some more methods here to allow searching for
144
 
    # revisions by date, committer, commit message, etc...
145
 
 
146
 
    def getDiff(self, revidA, revidB):
147
 
        """Compute the diff between two revisions.
148
 
 
149
 
        Not sure what this will return yet, probably something similar to but
150
 
        more structured than the 'chunks' loggerhead already works with.
151
 
        """
152
 
 
153
 
    def getDirList(self, fileid, revid):
154
 
        """List the files in the given directory as of the given revision.
155
 
 
156
 
        :return: a list of `FileEntry` objects.
157
 
        """
158
 
 
159
 
    def getFileAnnotation(self, fileid, revid):
160
 
        """Annotate the given file.
161
 
 
162
 
        Not sure what this should return, mostly likely a list of
163
 
        (revid-or-None, line contents) (and ``None`` for a binary file).
164
 
        """
165
 
 
166
 
    def getFileText(self, fileid, revid):
167
 
        """Fetch the contents of a file at a particular revision.
168
 
 
169
 
        :returns: (filename, data)
170
 
        :rtype: ``(str, str)``
171
 
        """
172
 
 
173
 
    def getBundle(self, revid, compare_revid=None):
174
 
        """Return a bundle for this revision.
175
 
 
176
 
        Relative to compare_revid, or left-most parent if this is not supplied
177
 
        or None.
178
 
 
179
 
        :return: A bundle (in a string).
180
 
        """
181
 
 
182
 
    def normalizeRevivionSpec(self, revspec):
183
 
        """Convert a revid or revno or 'head' to a revid.
184
 
 
185
 
        :returns: a revision id.
186
 
        """
187
 
 
188
 
    def normalizeFileArguments(self, revid, fileid, filepath):
189
 
        """Handle various ways of specifying a file in the branch.
190
 
 
191
 
        One of ``fileid`` and ``filepath`` should be None.
192
 
 
193
 
        :returns: (fileid, filepath)
194
 
        """