1 # (Be in -*- python -*- mode.)
3 # ====================================================================
4 # Copyright (c) 2000-2008 CollabNet. All rights reserved.
6 # This software is licensed as described in the file COPYING, which
7 # you should have received as part of this distribution. The terms
8 # are also available at http://subversion.tigris.org/license-1.html.
9 # If newer versions of this license are posted there, you may use a
10 # newer version instead, at your option.
12 # This software consists of voluntary contributions made by many
13 # individuals. For exact contribution history, see the revision
14 # history and logs, available at http://cvs2svn.tigris.org/.
15 # ====================================================================
17 """This module describes the interface to the CVS repository."""
20 class RevisionCollector(object):
21 """Optionally collect revision information for CVS files."""
24 """Initialize the RevisionCollector.
26 Please note that a RevisionCollector is instantiated in every
27 program run, even if the data-collection pass will not be
28 executed. (This is to allow it to register the artifacts that it
29 produces.) Therefore, the __init__() method should not do much,
30 and more substantial preparation for use (like actually creating
31 the artifacts) should be done in start()."""
35 def register_artifacts(self
, which_pass
):
36 """Register artifacts that will be needed while collecting data.
38 WHICH_PASS is the pass that will call our callbacks, so it should
39 be used to do the registering (e.g., call
40 WHICH_PASS.register_temp_file() and/or
41 WHICH_PASS.register_temp_file_needed())."""
46 """Data will soon start being collected.
48 Any non-idempotent initialization should be done here."""
52 def process_file(self
, cvs_file_items
):
53 """Collect data for the file described by CVS_FILE_ITEMS.
55 CVS_FILE_ITEMS has already been transformed into the logical
56 representation of the file's history as it should be output.
57 Therefore it is not necessarily identical to the history as
58 recorded in the RCS file."""
60 raise NotImplementedError()
63 """All recording is done; clean up."""
68 class RevisionRecorder
:
69 """An object that can record text and deltas from CVS files."""
72 """Initialize the RevisionRecorder.
74 Please note that a RevisionRecorder is instantiated in every
75 program run, even if the data-collection pass will not be
76 executed. (This is to allow it to register the artifacts that it
77 produces.) Therefore, the __init__() method should not do much,
78 and more substantial preparation for use (like actually creating
79 the artifacts) should be done in start()."""
83 def register_artifacts(self
, which_pass
):
84 """Register artifacts that will be needed during data recording.
86 WHICH_PASS is the pass that will call our callbacks, so it should
87 be used to do the registering (e.g., call
88 WHICH_PASS.register_temp_file() and/or
89 WHICH_PASS.register_temp_file_needed())."""
94 """Data will soon start being collected.
96 Any non-idempotent initialization should be done here."""
100 def start_file(self
, cvs_file
):
101 """Prepare to receive data for CVS_FILE."""
105 def record_text(self
, cvs_rev
, log
, text
):
106 """Record information about a revision and optionally return a token.
108 CVS_REV is a CVSRevision instance describing a revision that has
109 log message LOG and text TEXT (as retrieved from the RCS file).
110 (TEXT is full text for the HEAD revision, and deltas for other
113 raise NotImplementedError()
115 def finish_file(self
, cvs_file_items
):
116 """The current file is finished; finish and clean up.
118 CVS_FILE_ITEMS is a CVSFileItems instance describing the file's
119 items at the end of processing of the RCS file in CollectRevsPass."""
124 """All recording is done; clean up."""
129 class NullRevisionRecorder(RevisionRecorder
):
130 """A do-nothing variety of RevisionRecorder."""
132 def record_text(self
, cvs_rev
, log
, text
):
136 class RevisionExcluder
:
137 """An interface for informing a RevisionReader about excluded revisions.
139 Currently, revisions can be excluded via the --exclude option and
140 various fixups for CVS peculiarities. This interface can be used to
141 inform the associated RevisionReader about CVSItems that are being
142 excluded. (The recorder might use that information to free some
143 temporary data or adjust its expectations about which revisions will
147 """Initialize the RevisionExcluder.
149 Please note that a RevisionExcluder is instantiated in every
150 program run, even if the branch-exclusion pass will not be
151 executed. (This is to allow its register_artifacts() method to be
152 called.) Therefore, the __init__() method should not do much, and
153 more substantial preparation for use (like actually creating the
154 artifacts) should be done in start()."""
158 def register_artifacts(self
, which_pass
):
159 """Register artifacts that will be needed during branch exclusion.
161 WHICH_PASS is the pass that will call our callbacks, so it should
162 be used to do the registering (e.g., call
163 WHICH_PASS.register_temp_file() and/or
164 WHICH_PASS.register_temp_file_needed())."""
169 """Prepare to handle branch exclusions."""
173 def process_file(self
, cvs_file_items
):
174 """Called for files whose trees were modified in FilterSymbolsPass.
176 This callback is called once for each CVSFile whose topology was
177 modified in FilterSymbolsPass."""
179 raise NotImplementedError()
182 """Called after all branch exclusions for all files are done."""
187 class NullRevisionExcluder(RevisionExcluder
):
188 """A do-nothing variety of RevisionExcluder."""
190 def process_file(self
, cvs_file_items
):
194 class RevisionReader(object):
195 """An object that can read the contents of CVSRevisions."""
197 def register_artifacts(self
, which_pass
):
198 """Register artifacts that will be needed during branch exclusion.
200 WHICH_PASS is the pass that will call our callbacks, so it should
201 be used to do the registering (e.g., call
202 WHICH_PASS.register_temp_file() and/or
203 WHICH_PASS.register_temp_file_needed())."""
208 """Prepare for calls to get_content_stream."""
212 def get_content_stream(self
, cvs_rev
, suppress_keyword_substitution
=False):
213 """Return a file-like object from which the contents of CVS_REV
216 CVS_REV is a CVSRevision. If SUPPRESS_KEYWORD_SUBSTITUTION is
217 True, then suppress the substitution of RCS/CVS keywords in the
220 raise NotImplementedError
223 """Inform the reader that all calls to get_content_stream are done.
224 Start may be called again at a later point."""