vendor/CMF/1.5.3/CMFSetup

view interfaces.py @ 0:3ed006215eb6

Vendor import of CMF 1.5.3
author fguillaume
date Tue, 09 Aug 2005 10:47:34 +0000
parents
children
line source
1 ##############################################################################
2 #
3 # Copyright (c) 2004 Zope Corporation and Contributors. All Rights Reserved.
4 #
5 # This software is subject to the provisions of the Zope Public License,
6 # Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution.
7 # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
8 # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
9 # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
10 # FOR A PARTICULAR PURPOSE.
11 #
12 ##############################################################################
13 """ CMFSetup product interfaces
15 $Id: interfaces.py 37351 2005-07-20 21:16:59Z jens $
16 """
18 from Interface import Interface
21 BASE, EXTENSION = range(2)
24 class IPseudoInterface( Interface ):
26 """ API documentation; not testable / enforceable.
27 """
29 class ISetupContext( Interface ):
31 """ Context used for export / import plugins.
32 """
33 def getSite():
35 """ Return the site object being configured / dumped.
36 """
38 class IImportContext( ISetupContext ):
40 def getEncoding():
42 """ Get the encoding used for configuration data within the site.
44 o Return None if the data should not be encoded.
45 """
47 def readDataFile( filename, subdir=None ):
49 """ Search the current configuration for the requested file.
51 o 'filename' is the name (without path elements) of the file.
53 o 'subdir' is an optional subdirectory; if not supplied, search
54 only the "root" directory.
56 o Return the file contents as a string, or None if the
57 file cannot be found.
58 """
60 def getLastModified( path ):
62 """ Return the modification timestamp of the item at 'path'.
64 o Result will be a DateTime instance.
66 o Search profiles in the configuration in order.
68 o If the context is filesystem based, return the 'stat' timestamp
69 of the file / directory to which 'path' points.
71 o If the context is ZODB-based, return the Zope modification time
72 of the object to which 'path' points.
74 o Return None if 'path' does not point to any object.
75 """
77 def isDirectory( path ):
79 """ Test whether path points to a directory / folder.
81 o If the context is filesystem based, check that 'path' points to
82 a subdirectory within the "root" directory.
84 o If the context is ZODB-based, check that 'path' points to a
85 "container" under the context's tool.
87 o Return None if 'path' does not resolve; otherwise, return a
88 bool.
89 """
91 def listDirectory( path, skip=('CVS', '.svn') ):
93 """ List IDs of the contents of a directory / folder.
95 o Omit names in 'skip'.
97 o If 'path' does not point to a directory / folder, return None.
98 """
100 def shouldPurge():
102 """ When installing, should the existing setup be purged?
103 """
105 class IImportPlugin( IPseudoInterface ):
107 """ Signature for callables used to import portions of site configuration.
108 """
109 def __call__( context ):
111 """ Perform the setup step.
113 o Return a message describing the work done.
115 o 'context' must implement IImportContext.
116 """
118 class IExportContext( ISetupContext ):
120 def writeDataFile( filename, text, content_type, subdir=None ):
122 """ Write data into the specified location.
124 o 'filename' is the unqualified name of the file.
126 o 'text' is the content of the file.
128 o 'content_type' is the MIMEtype of the file.
130 o 'subdir', if passed, is a path to a subdirectory / folder in
131 which to write the file; if not passed, write the file to the
132 "root" of the target.
133 """
135 class IExportPlugin( IPseudoInterface ):
137 """ Signature for callables used to export portions of site configuration.
138 """
139 def __call__( context ):
141 """ Write export data for the site wrapped by context.
143 o Return a message describing the work done.
145 o 'context' must implement IExportContext. The plugin will use
146 its 'writeDataFile' method for each file to be exported.
147 """
149 class IStepRegistry( Interface ):
151 """ Base interface for step registries.
152 """
153 def listSteps():
155 """ Return a sequence of IDs of registered steps.
157 o Order is not significant.
158 """
160 def listStepMetadata():
162 """ Return a sequence of mappings describing registered steps.
164 o Mappings will be ordered alphabetically.
165 """
167 def getStepMetadata( key, default=None ):
169 """ Return a mapping of metadata for the step identified by 'key'.
171 o Return 'default' if no such step is registered.
173 o The 'handler' metadata is available via 'getStep'.
174 """
176 def generateXML():
178 """ Return a round-trippable XML representation of the registry.
180 o 'handler' values are serialized using their dotted names.
181 """
183 def parseXML( text ):
185 """ Parse 'text'.
186 """
188 class IImportStepRegistry( IStepRegistry ):
190 """ API for import step registry.
191 """
192 def sortSteps():
194 """ Return a sequence of registered step IDs
196 o Sequence is sorted topologically by dependency, with the dependent
197 steps *after* the steps they depend on.
198 """
200 def checkComplete():
202 """ Return a sequence of ( node, edge ) tuples for unsatisifed deps.
203 """
205 def getStep( key, default=None ):
207 """ Return the IImportPlugin registered for 'key'.
209 o Return 'default' if no such step is registered.
210 """
212 def registerStep( id
213 , version
214 , handler
215 , dependencies=()
216 , title=None
217 , description=None
218 ):
219 """ Register a setup step.
221 o 'id' is a unique name for this step,
223 o 'version' is a string for comparing versions, it is preferred to
224 be a yyyy/mm/dd-ii formatted string (date plus two-digit
225 ordinal). when comparing two version strings, the version with
226 the lower sort order is considered the older version.
228 - Newer versions of a step supplant older ones.
230 - Attempting to register an older one after a newer one results
231 in a KeyError.
233 o 'handler' should implement IImportPlugin.
235 o 'dependencies' is a tuple of step ids which have to run before
236 this step in order to be able to run at all. Registration of
237 steps that have unmet dependencies are deferred until the
238 dependencies have been registered.
240 o 'title' is a one-line UI description for this step.
241 If None, the first line of the documentation string of the handler
242 is used, or the id if no docstring can be found.
244 o 'description' is a one-line UI description for this step.
245 If None, the remaining line of the documentation string of
246 the handler is used, or default to ''.
247 """
249 class IExportStepRegistry( IStepRegistry ):
251 """ API for export step registry.
252 """
253 def getStep( key, default=None ):
255 """ Return the IExportPlugin registered for 'key'.
257 o Return 'default' if no such step is registered.
258 """
260 def registerStep( id, handler, title=None, description=None ):
262 """ Register an export step.
264 o 'id' is the unique identifier for this step
266 o 'handler' should implement IExportPlugin.
268 o 'title' is a one-line UI description for this step.
269 If None, the first line of the documentation string of the step
270 is used, or the id if no docstring can be found.
272 o 'description' is a one-line UI description for this step.
273 If None, the remaining line of the documentation string of
274 the step is used, or default to ''.
275 """
277 class IToolsetRegistry( Interface ):
279 """ API for toolset registry.
280 """
281 def listForbiddenTools():
283 """ Return a list of IDs of tools which must be removed, if present.
284 """
286 def addForbiddenTool(tool_id ):
288 """ Add 'tool_id' to the list of forbidden tools.
290 o Raise KeyError if 'tool_id' is already in the list.
292 o Raise ValueError if 'tool_id' is in the "required" list.
293 """
295 def listRequiredTools():
297 """ Return a list of IDs of tools which must be present.
298 """
300 def getRequiredToolInfo( tool_id ):
302 """ Return a mapping describing a partiuclar required tool.
304 o Keys include:
306 'id' -- the ID of the tool
308 'class' -- a dotted path to its class
310 o Raise KeyError if 'tool_id' id not a known tool.
311 """
313 def listRequiredToolInfo():
315 """ Return a list of IDs of tools which must be present.
316 """
318 def addRequiredTool( tool_id, dotted_name ):
320 """ Add a tool to our "required" list.
322 o 'tool_id' is the tool's ID.
324 o 'dotted_name' is a dotted (importable) name of the tool's class.
326 o Raise KeyError if we have already registered a class for 'tool_id'.
328 o Raise ValueError if 'tool_id' is in the "forbidden" list.
329 """
331 class IProfileRegistry( Interface ):
333 """ API for profile registry.
334 """
335 def getProfileInfo( profile_id ):
337 """ Return a mapping describing a registered filesystem profile.
339 o Keys include:
341 'id' -- the ID of the profile
343 'title' -- its title
345 'description' -- a textual description of the profile
347 'path' -- a path to the profile on the filesystem.
349 'product' -- the name of the product to which 'path' is
350 relative (None for absolute paths).
352 'type' -- either BASE or EXTENSION
353 """
355 def listProfiles():
357 """ Return a list of IDs for registered profiles.
358 """
360 def listProfileInfo():
362 """ Return a list of mappings describing registered profiles.
364 o See 'getProfileInfo' for a description of the mappings' keys.
365 """
367 def registerProfile( name
368 , title
369 , description
370 , path
371 , product=None
372 , profile_type=BASE
373 ):
374 """ Add a new profile to the registry.
376 o If an existing profile is already registered for 'product:name',
377 raise KeyError.
379 o If 'product' is passed, then 'path' should be interpreted as
380 relative to the corresponding product directory.
381 """
383 class ISetupTool( Interface ):
385 """ API for SetupTool.
386 """
388 def getEncoding():
390 """ Get the encoding used for configuration data within the site.
392 o Return None if the data should not be encoded.
393 """
395 def getImportContextID():
397 """ Get the ID of the active import context.
398 """
400 def setImportContext( context_id ):
402 """ Set the ID of the active import context and update the registries.
403 """
405 def getImportStepRegistry():
407 """ Return the IImportStepRegistry for the tool.
408 """
410 def getExportStepRegistry():
412 """ Return the IExportStepRegistry for the tool.
413 """
415 def getToolsetRegistry():
417 """ Return the IToolsetRegistry for the tool.
418 """
420 def runImportStep( step_id, run_dependencies=True, purge_old=None ):
422 """ Execute a given setup step
424 o 'step_id' is the ID of the step to run.
426 o If 'purge_old' is True, then run the step after purging any
427 "old" setup first (this is the responsibility of the step,
428 which must check the context we supply).
430 o If 'run_dependencies' is True, then run any out-of-date
431 dependency steps first.
433 o Return a mapping, with keys:
435 'steps' -- a sequence of IDs of the steps run.
437 'messages' -- a dictionary holding messages returned from each
438 step
439 """
441 def runAllImportSteps( purge_old=None ):
443 """ Run all setup steps in dependency order.
445 o If 'purge_old' is True, then run each step after purging any
446 "old" setup first (this is the responsibility of the step,
447 which must check the context we supply).
449 o Return a mapping, with keys:
451 'steps' -- a sequence of IDs of the steps run.
453 'messages' -- a dictionary holding messages returned from each
454 step
455 """
457 def runExportStep( step_id ):
459 """ Generate a tarball containing artifacts from one export step.
461 o 'step_id' identifies the export step.
463 o Return a mapping, with keys:
465 'steps' -- a sequence of IDs of the steps run.
467 'messages' -- a dictionary holding messages returned from each
468 step
470 'tarball' -- the stringified tar-gz data.
471 """
473 def runAllExportSteps():
475 """ Generate a tarball containing artifacts from all export steps.
477 o Return a mapping, with keys:
479 'steps' -- a sequence of IDs of the steps run.
481 'messages' -- a dictionary holding messages returned from each
482 step
484 'tarball' -- the stringified tar-gz data.
485 """
487 def createSnapshot( snapshot_id ):
489 """ Create a snapshot folder using all steps.
491 o 'snapshot_id' is the ID of the new folder.
492 """
494 def compareConfigurations( lhs_context
495 , rhs_context
496 , missing_as_empty=False
497 , ignore_whitespace=False
498 ):
499 """ Compare two configurations.
501 o 'lhs_context' and 'rhs_context' must implement IImportContext.
503 o If 'missing_as_empty', then compare files not present as though
504 they were zero-length; otherwise, omit such files.
506 o If 'ignore_whitespace', then suppress diffs due only to whitespace
507 (c.f: 'diff -wbB')
508 """