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 RevisionRecorder:
  21   """An object that can record text and deltas from CVS files."""
  22
  23   def __init__(self):
  24     """Initialize the RevisionRecorder.
  25
  26     Please note that a RevisionRecorder 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 during data recording.
  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 start_file(self, cvs_file_items):
  53     """Prepare to receive data for the file with the specified CVS_FILE_ITEMS.
  54
  55     CVS_FILE_ITEMS is an instance of CVSFileItems describing the file
  56     dependency topology right after the file tree was parsed out of
  57     the RCS file.  (I.e., it reflects the original CVS dependency
  58     structure.)  Please note that the CVSFileItems instance will be
  59     changed later."""
  60
  61     pass
  62
  63   def record_text(self, cvs_rev, log, text):
  64     """Record information about a revision and optionally return a token.
  65
  66     CVS_REV is a CVSRevision instance describing a revision that has
  67     log message LOG and text TEXT (as retrieved from the RCS file).
  68     (TEXT is full text for the HEAD revision, and deltas for other
  69     revisions.)"""
  70
  71     raise NotImplementedError()
  72
  73   def finish_file(self, cvs_file_items):
  74     """The current file is finished; finish and clean up.
  75
  76     CVS_FILE_ITEMS is a CVSFileItems instance describing the file's
  77     items at the end of processing of the RCS file in CollectRevsPass.
  78     It may be modified relative to the CVS_FILE_ITEMS instance passed
  79     to the corresponding start_file() call (revisions might be
  80     deleted, topology changed, etc)."""
  81
  82     pass
  83
  84   def finish(self):
  85     """All recording is done; clean up."""
  86
  87     pass
  88
  89
  90 class NullRevisionRecorder(RevisionRecorder):
  91   """A do-nothing variety of RevisionRecorder."""
  92
  93   def record_text(self, cvs_rev, log, text):
  94     return None
  95
  96
  97 class RevisionExcluder:
  98   """An interface for informing a RevisionReader about excluded revisions.
  99
 100   Currently, revisions can be excluded via the --exclude option and
 101   various fixups for CVS peculiarities.  This interface can be used to
 102   inform the associated RevisionReader about CVSItems that are being
 103   excluded.  (The recorder might use that information to free some
 104   temporary data or adjust its expectations about which revisions will
 105   later be read.)"""
 106
 107   def __init__(self):
 108     """Initialize the RevisionExcluder.
 109
 110     Please note that a RevisionExcluder is instantiated in every
 111     program run, even if the branch-exclusion pass will not be
 112     executed.  (This is to allow its register_artifacts() method to be
 113     called.)  Therefore, the __init__() method should not do much, and
 114     more substantial preparation for use (like actually creating the
 115     artifacts) should be done in start()."""
 116
 117     pass
 118
 119   def register_artifacts(self, which_pass):
 120     """Register artifacts that will be needed during branch exclusion.
 121
 122     WHICH_PASS is the pass that will call our callbacks, so it should
 123     be used to do the registering (e.g., call
 124     WHICH_PASS.register_temp_file() and/or
 125     WHICH_PASS.register_temp_file_needed())."""
 126
 127     pass
 128
 129   def start(self):
 130     """Prepare to handle branch exclusions."""
 131
 132     pass
 133
 134   def process_file(self, cvs_file_items):
 135     """Called for files whose trees were modified in FilterSymbolsPass.
 136
 137     This callback is called once for each CVSFile whose topology was
 138     modified in FilterSymbolsPass."""
 139
 140     raise NotImplementedError()
 141
 142   def finish(self):
 143     """Called after all branch exclusions for all files are done."""
 144
 145     pass
 146
 147
 148 class NullRevisionExcluder(RevisionExcluder):
 149   """A do-nothing variety of RevisionExcluder."""
 150
 151   def process_file(self, cvs_file_items):
 152     pass
 153
 154
 155 class RevisionReader(object):
 156   """An object that can read the contents of CVSRevisions."""
 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 for calls to get_content_stream."""
 170
 171     pass
 172
 173   def get_content_stream(self, cvs_rev, suppress_keyword_substitution=False):
 174     """Return a file-like object from which the contents of CVS_REV
 175     can be read.
 176
 177     CVS_REV is a CVSRevision.  If SUPPRESS_KEYWORD_SUBSTITUTION is
 178     True, then suppress the substitution of RCS/CVS keywords in the
 179     output."""
 180
 181     raise NotImplementedError
 182
 183   def finish(self):
 184     """Inform the reader that all calls to get_content_stream are done.
 185     Start may be called again at a later point."""
 186
 187     pass
 188
 189