Document how RevisionCollector can use CVSItem.revision_reader_token.
[cvs2svn.git] / cvs2svn_lib / revision_manager.py
blob6c62c3eff10fd30ca12d4e4fe457bd847fd898ac
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."""
23 def __init__(self):
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()."""
33 pass
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())."""
43 pass
45 def start(self):
46 """Data will soon start being collected.
48 Any non-idempotent initialization should be done here."""
50 pass
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 This method is allowed to store a pickleable object to the
61 CVSItem.revision_reader_token member of CVSItems in
62 CVS_FILE_ITEMS. These data are stored with the items and
63 available for the use of the RevisionReader."""
65 raise NotImplementedError()
67 def finish(self):
68 """All recording is done; clean up."""
70 pass
73 class NullRevisionCollector(RevisionCollector):
74 """A do-nothing variety of RevisionCollector."""
76 def process_file(self, cvs_file_items):
77 pass
80 class RevisionReader(object):
81 """An object that can read the contents of CVSRevisions."""
83 def register_artifacts(self, which_pass):
84 """Register artifacts that will be needed during branch exclusion.
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())."""
91 pass
93 def start(self):
94 """Prepare for calls to get_content_stream."""
96 pass
98 def get_content_stream(self, cvs_rev, suppress_keyword_substitution=False):
99 """Return a file-like object from which the contents of CVS_REV
100 can be read.
102 CVS_REV is a CVSRevision. If SUPPRESS_KEYWORD_SUBSTITUTION is
103 True, then suppress the substitution of RCS/CVS keywords in the
104 output."""
106 raise NotImplementedError
108 def finish(self):
109 """Inform the reader that all calls to get_content_stream are done.
110 Start may be called again at a later point."""
112 pass