cvs2svn_lib/revision_manager.py

   1 # (Be in -*- python -*- mode.)
   2 #
   3 # ====================================================================
   4 # Copyright (c) 2000-2008 CollabNet.  All rights reserved.
   5 #
   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.
  11 #
  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 # ====================================================================
  16
  17 """This module describes the interface to the CVS repository."""
  18
  19
  20 class RevisionCollector(object):
  21   """Optionally collect revision information for CVS files."""
  22
  23   def __init__(self):
  24     """Initialize the RevisionCollector.
  25
  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()."""
  32
  33     pass
  34
  35   def register_artifacts(self, which_pass):
  36     """Register artifacts that will be needed while collecting data.
  37
  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())."""
  42
  43     pass
  44
  45   def start(self):
  46     """Data will soon start being collected.
  47
  48     Any non-idempotent initialization should be done here."""
  49
  50     pass
  51
  52   def process_file(self, cvs_file_items):
  53     """Collect data for the file described by CVS_FILE_ITEMS.
  54
  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."""
  59
  60     raise NotImplementedError()
  61
  62   def finish(self):
  63     """All recording is done; clean up."""
  64
  65     pass
  66
  67
  68 class RevisionRecorder:
  69   """An object that can record text and deltas from CVS files."""
  70
  71   def __init__(self):
  72     """Initialize the RevisionRecorder.
  73
  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()."""
  80
  81     pass
  82
  83   def register_artifacts(self, which_pass):
  84     """Register artifacts that will be needed during data recording.
  85
  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())."""
  90
  91     pass
  92
  93   def start(self):
  94     """Data will soon start being collected.
  95
  96     Any non-idempotent initialization should be done here."""
  97
  98     pass
  99
 100   def start_file(self, cvs_file):
 101     """Prepare to receive data for CVS_FILE."""
 102
 103     pass
 104
 105   def record_text(self, cvs_rev, log, text):
 106     """Record information about a revision and optionally return a token.
 107
 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
 111     revisions.)"""
 112
 113     raise NotImplementedError()
 114
 115   def finish_file(self, cvs_file_items):
 116     """The current file is finished; finish and clean up.
 117
 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."""
 120
 121     pass
 122
 123   def finish(self):
 124     """All recording is done; clean up."""
 125
 126     pass
 127
 128
 129 class NullRevisionRecorder(RevisionRecorder):
 130   """A do-nothing variety of RevisionRecorder."""
 131
 132   def record_text(self, cvs_rev, log, text):
 133     return None
 134
 135
 136 class RevisionExcluder:
 137   """An interface for informing a RevisionReader about excluded revisions.
 138
 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
 144   later be read.)"""
 145
 146   def __init__(self):
 147     """Initialize the RevisionExcluder.
 148
 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()."""
 155
 156     pass
 157
 158   def register_artifacts(self, which_pass):
 159     """Register artifacts that will be needed during branch exclusion.
 160
 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())."""
 165
 166     pass
 167
 168   def start(self):
 169     """Prepare to handle branch exclusions."""
 170
 171     pass
 172
 173   def process_file(self, cvs_file_items):
 174     """Called for files whose trees were modified in FilterSymbolsPass.
 175
 176     This callback is called once for each CVSFile whose topology was
 177     modified in FilterSymbolsPass."""
 178
 179     raise NotImplementedError()
 180
 181   def finish(self):
 182     """Called after all branch exclusions for all files are done."""
 183
 184     pass
 185
 186
 187 class NullRevisionExcluder(RevisionExcluder):
 188   """A do-nothing variety of RevisionExcluder."""
 189
 190   def process_file(self, cvs_file_items):
 191     pass
 192
 193
 194 class RevisionReader(object):
 195   """An object that can read the contents of CVSRevisions."""
 196
 197   def register_artifacts(self, which_pass):
 198     """Register artifacts that will be needed during branch exclusion.
 199
 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())."""
 204
 205     pass
 206
 207   def start(self):
 208     """Prepare for calls to get_content_stream."""
 209
 210     pass
 211
 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
 214     can be read.
 215
 216     CVS_REV is a CVSRevision.  If SUPPRESS_KEYWORD_SUBSTITUTION is
 217     True, then suppress the substitution of RCS/CVS keywords in the
 218     output."""
 219
 220     raise NotImplementedError
 221
 222   def finish(self):
 223     """Inform the reader that all calls to get_content_stream are done.
 224     Start may be called again at a later point."""
 225
 226     pass
 227
 228