vendor/CMF/1.6-r41367/GenericSetup

view interfaces.py @ 0:d62b03aaa782

CMF 1.6 r41367 snapshot.
author fguillaume
date Thu, 19 Jan 2006 16:49:24 +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 """ GenericSetup product interfaces
15 $Id: interfaces.py 40878 2005-12-18 21:57:56Z yuppie $
16 """
18 from zope.interface import Interface
19 from zope.schema import Text
20 from zope.schema import TextLine
22 BASE, EXTENSION = range(1, 3)
25 class IPseudoInterface( Interface ):
27 """ API documentation; not testable / enforceable.
28 """
31 class ISetupEnviron(Interface):
33 """Context for im- and export adapters.
34 """
36 def getLogger(name):
37 """Get a logger with the specified name, creating it if necessary.
38 """
40 def shouldPurge():
41 """When installing, should the existing setup be purged?
42 """
45 class ISetupContext(ISetupEnviron):
47 """ Context used for export / import plugins.
48 """
49 def getSite():
51 """ Return the site object being configured / dumped.
52 """
54 def getSetupTool():
56 """ Return the site object being configured / dumped.
57 """
59 def getEncoding():
61 """ Get the encoding used for configuration data within the site.
63 o Return None if the data should not be encoded.
64 """
66 def listNotes():
67 """ Return notes recorded by this context.
69 o Result a sequence of (component, message) tuples
70 """
72 def clearNotes():
73 """ Clear all notes recorded by this context.
74 """
76 class IImportContext( ISetupContext ):
78 def readDataFile( filename, subdir=None ):
80 """ Search the current configuration for the requested file.
82 o 'filename' is the name (without path elements) of the file.
84 o 'subdir' is an optional subdirectory; if not supplied, search
85 only the "root" directory.
87 o Return the file contents as a string, or None if the
88 file cannot be found.
89 """
91 def getLastModified( path ):
93 """ Return the modification timestamp of the item at 'path'.
95 o Result will be a DateTime instance.
97 o Search profiles in the configuration in order.
99 o If the context is filesystem based, return the 'stat' timestamp
100 of the file / directory to which 'path' points.
102 o If the context is ZODB-based, return the Zope modification time
103 of the object to which 'path' points.
105 o Return None if 'path' does not point to any object.
106 """
108 def isDirectory( path ):
110 """ Test whether path points to a directory / folder.
112 o If the context is filesystem based, check that 'path' points to
113 a subdirectory within the "root" directory.
115 o If the context is ZODB-based, check that 'path' points to a
116 "container" under the context's tool.
118 o Return None if 'path' does not resolve; otherwise, return a
119 bool.
120 """
122 def listDirectory( path, skip=('CVS', '.svn') ):
124 """ List IDs of the contents of a directory / folder.
126 o Omit names in 'skip'.
128 o If 'path' does not point to a directory / folder, return None.
129 """
132 class IImportPlugin( IPseudoInterface ):
134 """ Signature for callables used to import portions of site configuration.
135 """
136 def __call__( context ):
138 """ Perform the setup step.
140 o Return a message describing the work done.
142 o 'context' must implement IImportContext.
143 """
145 class IExportContext( ISetupContext ):
147 def writeDataFile( filename, text, content_type, subdir=None ):
149 """ Write data into the specified location.
151 o 'filename' is the unqualified name of the file.
153 o 'text' is the content of the file.
155 o 'content_type' is the MIMEtype of the file.
157 o 'subdir', if passed, is a path to a subdirectory / folder in
158 which to write the file; if not passed, write the file to the
159 "root" of the target.
160 """
162 class IExportPlugin( IPseudoInterface ):
164 """ Signature for callables used to export portions of site configuration.
165 """
166 def __call__( context ):
168 """ Write export data for the site wrapped by context.
170 o Return a message describing the work done.
172 o 'context' must implement IExportContext. The plugin will use
173 its 'writeDataFile' method for each file to be exported.
174 """
176 class IStepRegistry( Interface ):
178 """ Base interface for step registries.
179 """
180 def listSteps():
182 """ Return a sequence of IDs of registered steps.
184 o Order is not significant.
185 """
187 def listStepMetadata():
189 """ Return a sequence of mappings describing registered steps.
191 o Mappings will be ordered alphabetically.
192 """
194 def getStepMetadata( key, default=None ):
196 """ Return a mapping of metadata for the step identified by 'key'.
198 o Return 'default' if no such step is registered.
200 o The 'handler' metadata is available via 'getStep'.
201 """
203 def generateXML():
205 """ Return a round-trippable XML representation of the registry.
207 o 'handler' values are serialized using their dotted names.
208 """
210 def parseXML( text ):
212 """ Parse 'text'.
213 """
215 class IImportStepRegistry( IStepRegistry ):
217 """ API for import step registry.
218 """
219 def sortSteps():
221 """ Return a sequence of registered step IDs
223 o Sequence is sorted topologically by dependency, with the dependent
224 steps *after* the steps they depend on.
225 """
227 def checkComplete():
229 """ Return a sequence of ( node, edge ) tuples for unsatisifed deps.
230 """
232 def getStep( key, default=None ):
234 """ Return the IImportPlugin registered for 'key'.
236 o Return 'default' if no such step is registered.
237 """
239 def registerStep( id
240 , version
241 , handler
242 , dependencies=()
243 , title=None
244 , description=None
245 ):
246 """ Register a setup step.
248 o 'id' is a unique name for this step,
250 o 'version' is a string for comparing versions, it is preferred to
251 be a yyyy/mm/dd-ii formatted string (date plus two-digit
252 ordinal). when comparing two version strings, the version with
253 the lower sort order is considered the older version.
255 - Newer versions of a step supplant older ones.
257 - Attempting to register an older one after a newer one results
258 in a KeyError.
260 o 'handler' should implement IImportPlugin.
262 o 'dependencies' is a tuple of step ids which have to run before
263 this step in order to be able to run at all. Registration of
264 steps that have unmet dependencies are deferred until the
265 dependencies have been registered.
267 o 'title' is a one-line UI description for this step.
268 If None, the first line of the documentation string of the handler
269 is used, or the id if no docstring can be found.
271 o 'description' is a one-line UI description for this step.
272 If None, the remaining line of the documentation string of
273 the handler is used, or default to ''.
274 """
276 class IExportStepRegistry( IStepRegistry ):
278 """ API for export step registry.
279 """
280 def getStep( key, default=None ):
282 """ Return the IExportPlugin registered for 'key'.
284 o Return 'default' if no such step is registered.
285 """
287 def registerStep( id, handler, title=None, description=None ):
289 """ Register an export step.
291 o 'id' is the unique identifier for this step
293 o 'handler' should implement IExportPlugin.
295 o 'title' is a one-line UI description for this step.
296 If None, the first line of the documentation string of the step
297 is used, or the id if no docstring can be found.
299 o 'description' is a one-line UI description for this step.
300 If None, the remaining line of the documentation string of
301 the step is used, or default to ''.
302 """
304 class IToolsetRegistry( Interface ):
306 """ API for toolset registry.
307 """
308 def listForbiddenTools():
310 """ Return a list of IDs of tools which must be removed, if present.
311 """
313 def addForbiddenTool(tool_id ):
315 """ Add 'tool_id' to the list of forbidden tools.
317 o Raise KeyError if 'tool_id' is already in the list.
319 o Raise ValueError if 'tool_id' is in the "required" list.
320 """
322 def listRequiredTools():
324 """ Return a list of IDs of tools which must be present.
325 """
327 def getRequiredToolInfo( tool_id ):
329 """ Return a mapping describing a partiuclar required tool.
331 o Keys include:
333 'id' -- the ID of the tool
335 'class' -- a dotted path to its class
337 o Raise KeyError if 'tool_id' id not a known tool.
338 """
340 def listRequiredToolInfo():
342 """ Return a list of IDs of tools which must be present.
343 """
345 def addRequiredTool( tool_id, dotted_name ):
347 """ Add a tool to our "required" list.
349 o 'tool_id' is the tool's ID.
351 o 'dotted_name' is a dotted (importable) name of the tool's class.
353 o Raise KeyError if we have already registered a class for 'tool_id'.
355 o Raise ValueError if 'tool_id' is in the "forbidden" list.
356 """
358 class IProfileRegistry( Interface ):
360 """ API for profile registry.
361 """
362 def getProfileInfo( profile_id, for_=None ):
364 """ Return a mapping describing a registered filesystem profile.
366 o Keys include:
368 'id' -- the ID of the profile
370 'title' -- its title
372 'description' -- a textual description of the profile
374 'path' -- a path to the profile on the filesystem.
376 'product' -- the name of the product to which 'path' is
377 relative (None for absolute paths).
379 'type' -- either BASE or EXTENSION
381 o 'for_', if passed, should be the interface specifying the "site
382 type" for which the profile is relevant, e.g.
383 Products.CMFCore.interfaces.ISiteRoot or
384 Products.PluggableAuthService.interfaces.IPluggableAuthService.
385 If 'None', list all profiles.
386 """
388 def listProfiles( for_=None ):
390 """ Return a list of IDs for registered profiles.
392 o 'for_', if passed, should be the interface specifying the "site
393 type" for which the profile is relevant, e.g.
394 Products.CMFCore.interfaces.ISiteRoot or
395 Products.PluggableAuthService.interfaces.IPluggableAuthService.
396 If 'None', list all profiles.
397 """
399 def listProfileInfo( for_=None ):
401 """ Return a list of mappings describing registered profiles.
403 o See 'getProfileInfo' for a description of the mappings' keys.
405 o 'for_', if passed, should be the interface specifying the "site
406 type" for which the profile is relevant, e.g.
407 Products.CMFCore.interfaces.ISiteRoot or
408 Products.PluggableAuthService.interfaces.IPluggableAuthService.
409 If 'None', list all profiles.
410 """
412 def registerProfile( name
413 , title
414 , description
415 , path
416 , product=None
417 , profile_type=BASE
418 , for_=None
419 ):
420 """ Add a new profile to the registry.
422 o If an existing profile is already registered for 'product:name',
423 raise KeyError.
425 o If 'product' is passed, then 'path' should be interpreted as
426 relative to the corresponding product directory.
428 o 'for_', if passed, should be the interface specifying the "site
429 type" for which the profile is relevant, e.g.
430 Products.CMFCore.interfaces.ISiteRoot or
431 Products.PluggableAuthService.interfaces.IPluggableAuthService.
432 If 'None', the profile might be used in any site.
433 """
435 class ISetupTool( Interface ):
437 """ API for SetupTool.
438 """
440 def getEncoding():
442 """ Get the encoding used for configuration data within the site.
444 o Return None if the data should not be encoded.
445 """
447 def getImportContextID():
449 """ Get the ID of the active import context.
450 """
452 def setImportContext( context_id ):
454 """ Set the ID of the active import context and update the registries.
455 """
457 def getImportStepRegistry():
459 """ Return the IImportStepRegistry for the tool.
460 """
462 def getExportStepRegistry():
464 """ Return the IExportStepRegistry for the tool.
465 """
467 def getToolsetRegistry():
469 """ Return the IToolsetRegistry for the tool.
470 """
472 def runImportStep( step_id, run_dependencies=True, purge_old=None ):
474 """ Execute a given setup step
476 o 'step_id' is the ID of the step to run.
478 o If 'purge_old' is True, then run the step after purging any
479 "old" setup first (this is the responsibility of the step,
480 which must check the context we supply).
482 o If 'run_dependencies' is True, then run any out-of-date
483 dependency steps first.
485 o Return a mapping, with keys:
487 'steps' -- a sequence of IDs of the steps run.
489 'messages' -- a dictionary holding messages returned from each
490 step
491 """
493 def runAllImportSteps( purge_old=None ):
495 """ Run all setup steps in dependency order.
497 o If 'purge_old' is True, then run each step after purging any
498 "old" setup first (this is the responsibility of the step,
499 which must check the context we supply).
501 o Return a mapping, with keys:
503 'steps' -- a sequence of IDs of the steps run.
505 'messages' -- a dictionary holding messages returned from each
506 step
507 """
509 def runExportStep( step_id ):
511 """ Generate a tarball containing artifacts from one export step.
513 o 'step_id' identifies the export step.
515 o Return a mapping, with keys:
517 'steps' -- a sequence of IDs of the steps run.
519 'messages' -- a dictionary holding messages returned from each
520 step
522 'tarball' -- the stringified tar-gz data.
523 """
525 def runAllExportSteps():
527 """ Generate a tarball containing artifacts from all export steps.
529 o Return a mapping, with keys:
531 'steps' -- a sequence of IDs of the steps run.
533 'messages' -- a dictionary holding messages returned from each
534 step
536 'tarball' -- the stringified tar-gz data.
537 """
539 def createSnapshot( snapshot_id ):
541 """ Create a snapshot folder using all steps.
543 o 'snapshot_id' is the ID of the new folder.
544 """
546 def compareConfigurations( lhs_context
547 , rhs_context
548 , missing_as_empty=False
549 , ignore_whitespace=False
550 ):
551 """ Compare two configurations.
553 o 'lhs_context' and 'rhs_context' must implement IImportContext.
555 o If 'missing_as_empty', then compare files not present as though
556 they were zero-length; otherwise, omit such files.
558 o If 'ignore_whitespace', then suppress diffs due only to whitespace
559 (c.f: 'diff -wbB')
560 """
563 class IWriteLogger(Interface):
565 """Write methods used by the python logging Logger.
566 """
568 def debug(msg, *args, **kwargs):
569 """Log 'msg % args' with severity 'DEBUG'.
570 """
572 def info(msg, *args, **kwargs):
573 """Log 'msg % args' with severity 'INFO'.
574 """
576 def warning(msg, *args, **kwargs):
577 """Log 'msg % args' with severity 'WARNING'.
578 """
580 def error(msg, *args, **kwargs):
581 """Log 'msg % args' with severity 'ERROR'.
582 """
584 def exception(msg, *args):
585 """Convenience method for logging an ERROR with exception information.
586 """
588 def critical(msg, *args, **kwargs):
589 """Log 'msg % args' with severity 'CRITICAL'.
590 """
592 def log(level, msg, *args, **kwargs):
593 """Log 'msg % args' with the integer severity 'level'.
594 """
597 class INode(Interface):
599 """Node im- and exporter.
600 """
602 node = Text(description=u'Im- and export the object as a DOM node.')
605 class IBody(INode):
607 """Body im- and exporter.
608 """
610 body = Text(description=u'Im- and export the object as a file body.')
612 mime_type = TextLine(description=u'MIME type of the file body.')
614 name = TextLine(description=u'Enforce this name for the file.')
616 suffix = TextLine(description=u'Suffix for the file.')
619 class IFilesystemExporter(Interface):
620 """ Plugin interface for site structure export.
621 """
622 def export(export_context, subdir, root=False):
623 """ Export our 'context' using the API of 'export_context'.
625 o 'export_context' must implement
626 Products.GenericSupport.interfaces.IExportContext.
628 o 'subdir', if passed, is the relative subdirectory containing our
629 context within the site.
631 o 'root', if true, indicates that the current context is the
632 "root" of an import (this may be used to adjust paths when
633 interacting with the context).
634 """
636 def listExportableItems():
637 """ Return a sequence of the child items to be exported.
639 o Each item in the returned sequence will be a tuple,
640 (id, object, adapter) where adapter must implement
641 IFilesystemExporter.
642 """
644 class IFilesystemImporter(Interface):
645 """ Plugin interface for site structure export.
646 """
647 def import_(import_context, subdir, root=False):
648 """ Import our 'context' using the API of 'import_context'.
650 o 'import_context' must implement
651 Products.GenericSupport.interfaces.IImportContext.
653 o 'subdir', if passed, is the relative subdirectory containing our
654 context within the site.
656 o 'root', if true, indicates that the current context is the
657 "root" of an import (this may be used to adjust paths when
658 interacting with the context).
659 """
661 class IContentFactory(Interface):
662 """ Adapter interface for factories specific to a container.
663 """
664 def __call__(id):
665 """ Return a new instance, seated in the context under 'id'.
666 """
668 class IContentFactoryName(Interface):
669 """ Adapter interface for finding the name of the ICF for an object.
670 """
671 def __call__():
672 """ Return a string, suitable for looking up an IContentFactory.
674 o The string should allow finding a factory for our context's
675 container which would create an "empty" instance of the same
676 type as our context.
677 """
679 class ICSVAware(Interface):
680 """ Interface for objects which dump / load 'text/comma-separated-values'.
681 """
682 def getId():
683 """ Return the Zope id of the object.
684 """
686 def as_csv():
687 """ Return a string representing the object as CSV.
688 """
690 def put_csv(fd):
691 """ Parse CSV and update the object.
693 o 'fd' must be a file-like object whose 'read' method returns
694 CSV text parseable by the 'csv.reader'.
695 """
697 class IINIAware(Interface):
698 """ Interface for objects which dump / load INI-format files..
699 """
700 def getId():
701 """ Return the Zope id of the object.
702 """
704 def as_ini():
705 """ Return a string representing the object as INI.
706 """
708 def put_ini(stream_or_text):
709 """ Parse INI-formatted text and update the object.
711 o 'stream_or_text' must be either a string, or else a stream
712 directly parseable by ConfigParser.
713 """
715 class IDAVAware(Interface):
716 """ Interface for objects which handle their own FTP / DAV operations.
717 """
718 def getId():
719 """ Return the Zope id of the object.
720 """
722 def manage_FTPget():
723 """ Return a string representing the object as a file.
724 """
726 def PUT(REQUEST, RESPONSE):
727 """ Parse file content and update the object.
729 o 'REQUEST' will have a 'get' method, which will have the
730 content object in its "BODY" key. It will also have 'get_header'
731 method, whose headers (e.g., "Content-Type") may affect the
732 processing of the body.
733 """