Logo Search packages:      
Sourcecode: zope-cmf1.5 version File versions  Download package

interfaces.py

##############################################################################
#
# Copyright (c) 2004 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
""" CMFSetup product interfaces

$Id: interfaces.py 37351 2005-07-20 21:16:59Z jens $
"""

from Interface import Interface


BASE, EXTENSION = range(2)


00024 class IPseudoInterface( Interface ):

    """ API documentation;  not testable / enforceable.
    """

00029 class ISetupContext( Interface ):

    """ Context used for export / import plugins.
    """
00033     def getSite():

        """ Return the site object being configured / dumped.
        """

class IImportContext( ISetupContext ):

    def getEncoding():

        """ Get the encoding used for configuration data within the site.

        o Return None if the data should not be encoded.
        """

    def readDataFile( filename, subdir=None ):

        """ Search the current configuration for the requested file.

        o 'filename' is the name (without path elements) of the file.

        o 'subdir' is an optional subdirectory;  if not supplied, search
          only the "root" directory.

        o Return the file contents as a string, or None if the
          file cannot be found.
        """

    def getLastModified( path ):

        """ Return the modification timestamp of the item at 'path'.

        o Result will be a DateTime instance.

        o Search profiles in the configuration in order.

        o If the context is filesystem based, return the 'stat' timestamp
          of the file / directory to which 'path' points.

        o If the context is ZODB-based, return the Zope modification time
          of the object to which 'path' points.

        o Return None if 'path' does not point to any object.
        """

    def isDirectory( path ):

        """ Test whether path points to a directory / folder.

        o If the context is filesystem based, check that 'path' points to
          a subdirectory within the "root" directory.

        o If the context is ZODB-based, check that 'path' points to a
          "container" under the context's tool.

        o Return None if 'path' does not resolve;  otherwise, return a
          bool.
        """

    def listDirectory( path, skip=('CVS', '.svn') ):

        """ List IDs of the contents of a  directory / folder.

        o Omit names in 'skip'.

        o If 'path' does not point to a directory / folder, return None.
        """

    def shouldPurge():

        """ When installing, should the existing setup be purged?
        """

00105 class IImportPlugin( IPseudoInterface ):

    """ Signature for callables used to import portions of site configuration.
    """
00109     def __call__( context ):

        """ Perform the setup step.

        o Return a message describing the work done.

        o 'context' must implement IImportContext.
        """

class IExportContext( ISetupContext ):

    def writeDataFile( filename, text, content_type, subdir=None ):

        """ Write data into the specified location.

        o 'filename' is the unqualified name of the file.

        o 'text' is the content of the file.

        o 'content_type' is the MIMEtype of the file.

        o 'subdir', if passed, is a path to a subdirectory / folder in
          which to write the file;  if not passed, write the file to the
          "root" of the target.
        """

00135 class IExportPlugin( IPseudoInterface ):

    """ Signature for callables used to export portions of site configuration.
    """
00139     def __call__( context ):

        """ Write export data for the site wrapped by context.

        o Return a message describing the work done.

        o 'context' must implement IExportContext.  The plugin will use
          its 'writeDataFile' method for each file to be exported.
        """

00149 class IStepRegistry( Interface ):

    """ Base interface for step registries.
    """
00153     def listSteps():

        """ Return a sequence of IDs of registered steps.

        o Order is not significant.
        """

00160     def listStepMetadata():

        """ Return a sequence of mappings describing registered steps.

        o Mappings will be ordered alphabetically.
        """

00167     def getStepMetadata( key, default=None ):

        """ Return a mapping of metadata for the step identified by 'key'.

        o Return 'default' if no such step is registered.

        o The 'handler' metadata is available via 'getStep'.
        """

00176     def generateXML():

        """ Return a round-trippable XML representation of the registry.

        o 'handler' values are serialized using their dotted names.
        """

00183     def parseXML( text ):

        """ Parse 'text'.
        """

00188 class IImportStepRegistry( IStepRegistry ):

    """ API for import step registry.
    """
00192     def sortSteps():

        """ Return a sequence of registered step IDs

        o Sequence is sorted topologically by dependency, with the dependent
          steps *after* the steps they depend on.
        """

00200     def checkComplete():

        """ Return a sequence of ( node, edge ) tuples for unsatisifed deps.
        """

00205     def getStep( key, default=None ):

        """ Return the IImportPlugin registered for 'key'.

        o Return 'default' if no such step is registered.
        """

00212     def registerStep( id
                    , version
                    , handler
                    , dependencies=()
                    , title=None
                    , description=None
                    ):
        """ Register a setup step.

        o 'id' is a unique name for this step,

        o 'version' is a string for comparing versions, it is preferred to
          be a yyyy/mm/dd-ii formatted string (date plus two-digit
          ordinal).  when comparing two version strings, the version with
          the lower sort order is considered the older version.

          - Newer versions of a step supplant older ones.

          - Attempting to register an older one after a newer one results
            in a KeyError.

        o 'handler' should implement IImportPlugin.

        o 'dependencies' is a tuple of step ids which have to run before
          this step in order to be able to run at all. Registration of
          steps that have unmet dependencies are deferred until the
          dependencies have been registered.

        o 'title' is a one-line UI description for this step.
          If None, the first line of the documentation string of the handler
          is used, or the id if no docstring can be found.

        o 'description' is a one-line UI description for this step.
          If None, the remaining line of the documentation string of
          the handler is used, or default to ''.
        """

00249 class IExportStepRegistry( IStepRegistry ):

    """ API for export step registry.
    """
00253     def getStep( key, default=None ):

        """ Return the IExportPlugin registered for 'key'.

        o Return 'default' if no such step is registered.
        """

00260     def registerStep( id, handler, title=None, description=None ):

        """ Register an export step.

        o 'id' is the unique identifier for this step

        o 'handler' should implement IExportPlugin.

        o 'title' is a one-line UI description for this step.
          If None, the first line of the documentation string of the step
          is used, or the id if no docstring can be found.

        o 'description' is a one-line UI description for this step.
          If None, the remaining line of the documentation string of
          the step is used, or default to ''.
        """

00277 class IToolsetRegistry( Interface ):

    """ API for toolset registry.
    """
00281     def listForbiddenTools():

        """ Return a list of IDs of tools which must be removed, if present.
        """

00286     def addForbiddenTool(tool_id ):

        """ Add 'tool_id' to the list of forbidden tools.

        o Raise KeyError if 'tool_id' is already in the list.

        o Raise ValueError if 'tool_id' is in the "required" list.
        """

00295     def listRequiredTools():

        """ Return a list of IDs of tools which must be present.
        """

00300     def getRequiredToolInfo( tool_id ):

        """ Return a mapping describing a partiuclar required tool.

        o Keys include:

          'id' -- the ID of the tool

          'class' -- a dotted path to its class

        o Raise KeyError if 'tool_id' id not a known tool.
        """

00313     def listRequiredToolInfo():

        """ Return a list of IDs of tools which must be present.
        """

00318     def addRequiredTool( tool_id, dotted_name ):

        """ Add a tool to our "required" list.

        o 'tool_id' is the tool's ID.

        o 'dotted_name' is a dotted (importable) name of the tool's class.

        o Raise KeyError if we have already registered a class for 'tool_id'.

        o Raise ValueError if 'tool_id' is in the "forbidden" list.
        """

00331 class IProfileRegistry( Interface ):

    """ API for profile registry.
    """
00335     def getProfileInfo( profile_id ):

        """ Return a mapping describing a registered filesystem profile.

        o Keys include:

          'id' -- the ID of the profile

          'title' -- its title

          'description' -- a textual description of the profile

          'path' -- a path to the profile on the filesystem.

          'product' -- the name of the product to which 'path' is
             relative (None for absolute paths).

          'type' -- either BASE or EXTENSION
        """

00355     def listProfiles():

        """ Return a list of IDs for registered profiles.
        """

00360     def listProfileInfo():

        """ Return a list of mappings describing registered profiles.

        o See 'getProfileInfo' for a description of the mappings' keys.
        """

00367     def registerProfile( name
                       , title
                       , description
                       , path
                       , product=None
                       , profile_type=BASE
                       ):
        """ Add a new profile to the registry.

        o If an existing profile is already registered for 'product:name',
          raise KeyError.

        o If 'product' is passed, then 'path' should be interpreted as
          relative to the corresponding product directory.
        """

00383 class ISetupTool( Interface ):

    """ API for SetupTool.
    """

00388     def getEncoding():

        """ Get the encoding used for configuration data within the site.

        o Return None if the data should not be encoded.
        """

00395     def getImportContextID():

        """ Get the ID of the active import context.
        """

00400     def setImportContext( context_id ):

        """ Set the ID of the active import context and update the registries.
        """

00405     def getImportStepRegistry():

        """ Return the IImportStepRegistry for the tool.
        """

00410     def getExportStepRegistry():

        """ Return the IExportStepRegistry for the tool.
        """

00415     def getToolsetRegistry():

        """ Return the IToolsetRegistry for the tool.
        """

00420     def runImportStep( step_id, run_dependencies=True, purge_old=None ):

        """ Execute a given setup step

        o 'step_id' is the ID of the step to run.

        o If 'purge_old' is True, then run the step after purging any
          "old" setup first (this is the responsibility of the step,
          which must check the context we supply).

        o If 'run_dependencies' is True, then run any out-of-date
          dependency steps first.

        o Return a mapping, with keys:

          'steps' -- a sequence of IDs of the steps run.

          'messages' -- a dictionary holding messages returned from each
            step
        """

00441     def runAllImportSteps( purge_old=None ):

        """ Run all setup steps in dependency order.

        o If 'purge_old' is True, then run each step after purging any
          "old" setup first (this is the responsibility of the step,
          which must check the context we supply).

        o Return a mapping, with keys:

          'steps' -- a sequence of IDs of the steps run.

          'messages' -- a dictionary holding messages returned from each
            step
        """

00457     def runExportStep( step_id ):

        """ Generate a tarball containing artifacts from one export step.

        o 'step_id' identifies the export step.

        o Return a mapping, with keys:

          'steps' -- a sequence of IDs of the steps run.

          'messages' -- a dictionary holding messages returned from each
            step

          'tarball' -- the stringified tar-gz data.
        """

00473     def runAllExportSteps():

        """ Generate a tarball containing artifacts from all export steps.

        o Return a mapping, with keys:

          'steps' -- a sequence of IDs of the steps run.

          'messages' -- a dictionary holding messages returned from each
            step

          'tarball' -- the stringified tar-gz data.
        """

00487     def createSnapshot( snapshot_id ):

        """ Create a snapshot folder using all steps.

        o 'snapshot_id' is the ID of the new folder.
        """

00494     def compareConfigurations( lhs_context
                             , rhs_context
                             , missing_as_empty=False
                             , ignore_whitespace=False
                             ):
        """ Compare two configurations.

        o 'lhs_context' and 'rhs_context' must implement IImportContext.

        o If 'missing_as_empty', then compare files not present as though
          they were zero-length;  otherwise, omit such files.

        o If 'ignore_whitespace', then suppress diffs due only to whitespace
          (c.f:  'diff -wbB')
        """

Generated by  Doxygen 1.6.0   Back to index