Logo Search packages:      
Sourcecode: plone3 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.
#
##############################################################################
""" GenericSetup product interfaces

$Id: interfaces.py 82852 2008-01-13 20:51:57Z wichert $
"""

from zope.interface import Attribute
from zope.interface import Interface
from zope.schema import Text
from zope.schema import TextLine

# Please note that these values may change. Always import 
# the values from here instead of using the values directly.
BASE, EXTENSION = 1, 2
SKIPPED_FILES = ('CVS', '.svn', '_svn', '_darcs')
SKIPPED_SUFFIXES = ('~',)


00030 class IPseudoInterface( Interface ):

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


00036 class ISetupEnviron(Interface):

    """Context for im- and export adapters.
    """

00041     def getLogger(name):
        """Get a logger with the specified name, creating it if necessary.
        """

00045     def shouldPurge():
        """When installing, should the existing setup be purged?
        """


00050 class ISetupContext(ISetupEnviron):

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

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

00059     def getSetupTool():

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

00064     def getEncoding():

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

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

00071     def listNotes():
        """ Return notes recorded by this context.
        
        o Result a sequence of (component, message) tuples
        """

00077     def clearNotes():
        """ Clear all notes recorded by this context.
        """

class IImportContext( ISetupContext ):

    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=SKIPPED_FILES ):

        """ 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.
        """


00137 class IImportPlugin( IPseudoInterface ):

    """ Signature for callables used to import portions of site configuration.
    """
00141     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.
        """

00167 class IExportPlugin( IPseudoInterface ):

    """ Signature for callables used to export portions of site configuration.
    """
00171     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.
        """

00181 class IStepRegistry( Interface ):

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

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

        o Order is not significant.
        """

00192     def listStepMetadata():

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

        o Mappings will be ordered alphabetically.
        """

00199     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'.
        """

00208     def generateXML():

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

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

00215     def parseXML( text ):

        """ Parse 'text'.
        """

00220 class IImportStepRegistry( IStepRegistry ):

    """ API for import step registry.
    """
00224     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.
        """

00232     def checkComplete():

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

00237     def getStep( key, default=None ):

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

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

00244     def registerStep( id
                    , version=None
                    , handler=None
                    , 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.

          NOTE: The version argument is deprecated.

        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 ''.
        """

00283 class IExportStepRegistry( IStepRegistry ):

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

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

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

00294     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 ''.
        """

00311 class IToolsetRegistry( Interface ):

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

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

00320     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.
        """

00329     def listRequiredTools():

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

00334     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.
        """

00347     def listRequiredToolInfo():

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

00352     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.
        """

00365 class IProfileRegistry( Interface ):

    """ API for profile registry.
    """
00369     def getProfileInfo( profile_id, for_=None ):

        """ 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
        
        o 'for_', if passed, should be the interface specifying the "site
            type" for which the profile is relevant, e.g.
            Products.CMFCore.interfaces.ISiteRoot or
            Products.PluggableAuthService.interfaces.IPluggableAuthService.
            If 'None', list all profiles.
        """

00395     def listProfiles( for_=None ):

        """ Return a list of IDs for registered profiles.
        
        o 'for_', if passed, should be the interface specifying the "site
            type" for which the profile is relevant, e.g.
            Products.CMFCore.interfaces.ISiteRoot or
            Products.PluggableAuthService.interfaces.IPluggableAuthService.
            If 'None', list all profiles.
        """

00406     def listProfileInfo( for_=None ):

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

        o See 'getProfileInfo' for a description of the mappings' keys.
        
        o 'for_', if passed, should be the interface specifying the "site
            type" for which the profile is relevant, e.g.
            Products.CMFCore.interfaces.ISiteRoot or
            Products.PluggableAuthService.interfaces.IPluggableAuthService.
            If 'None', list all profiles.
        """

00419     def registerProfile( name
                       , title
                       , description
                       , path
                       , product=None
                       , profile_type=BASE
                       , for_=None
                       ):
        """ 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.
        
        o 'for_', if passed, should be the interface specifying the "site
          type" for which the profile is relevant, e.g.
          Products.CMFCore.interfaces.ISiteRoot or
          Products.PluggableAuthService.interfaces.IPluggableAuthService.
          If 'None', the profile might be used in any site.
        """

00442 class ISetupTool( Interface ):

    """ API for SetupTool.
    """

00447     def getEncoding():

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

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

00454     def getImportContextID():

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

        DEPRECATED.  The idea of a stateful active import context is
        going away.
        """

00462     def getBaselineContextID():
        """ Get the ID of the base profile for this configuration.
        """

00466     def setImportContext( context_id ):

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

        DEPRECATED.  The idea of a stateful active import context is
        going away.
        """

00474     def setBaselineContext( context_id, encoding=None):
        """ Specify the base profile for this configuration.
        """

00478     def applyContext( context, encoding=None ):

        """ Update the tool from the supplied context, without modifying its
            "permanent" ID.
        """

00484     def getImportStepRegistry():

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

00489     def getExportStepRegistry():

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

00494     def getToolsetRegistry():

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

00499     def getProfileDependencyChain( profile_id ):

        """Return a list of dependencies for a profile.

        The list is ordered by install order, with the requested profile as
        last item.
        """

00507     def runImportStepFromProfile(profile_id, step_id,
                                 run_dependencies=True, purge_old=None):

        """ Execute a given setup step from the given profile.

        o 'profile_id' must be a valid ID of a registered profile;
           otherwise, raise KeyError.

        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
        """

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

        """ Execute a given setup step from the current
        _import_context_id context.

        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

        DEPRECATED.  Use runImportStepFromProfile instead.
        """

00556     def runAllImportStepsFromProfile(profile_id, purge_old=None, ignore_dependencies=False):

        """ Run all setup steps for the given profile in dependency order.

        o 'profile_id' must be a valid ID of a registered profile;
           otherwise, raise KeyError.

        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 Unless 'ignore_dependencies' is true this will also import
          all profiles this profile depends on.

        o Return a mapping, with keys:

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

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

00578     def runAllImportSteps(purge_old=None):

        """ Run all setup steps for the _import_context_id profile 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

        DEPRECATED.  Use runAllImportStepsFromProfile instead.
        """

00597     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.
        """

00613     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.
        """

00627     def createSnapshot( snapshot_id ):

        """ Create a snapshot folder using all steps.

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

00634     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')
        """

00650     def getProfileImportDate(profile_id):
        """ Return the last date an extension was imported.

        o The result will be a string, formated as IS0.
        """


00657 class IWriteLogger(Interface):

    """Write methods used by the python logging Logger.
    """

00662     def debug(msg, *args, **kwargs):
        """Log 'msg % args' with severity 'DEBUG'.
        """

00666     def info(msg, *args, **kwargs):
        """Log 'msg % args' with severity 'INFO'.
        """

00670     def warning(msg, *args, **kwargs):
        """Log 'msg % args' with severity 'WARNING'.
        """

00674     def error(msg, *args, **kwargs):
        """Log 'msg % args' with severity 'ERROR'.
        """

00678     def exception(msg, *args):
        """Convenience method for logging an ERROR with exception information.
        """

00682     def critical(msg, *args, **kwargs):
        """Log 'msg % args' with severity 'CRITICAL'.
        """

00686     def log(level, msg, *args, **kwargs):
        """Log 'msg % args' with the integer severity 'level'.
        """


00691 class INode(Interface):

    """Node im- and exporter.
    """

    node = Text(description=u'Im- and export the object as a DOM node.')


00699 class IBody(INode):

    """Body im- and exporter.
    """

    body = Text(description=u'Im- and export the object as a file body.')

    mime_type = TextLine(description=u'MIME type of the file body.')

    name = TextLine(description=u'Enforce this name for the file.')

    suffix = TextLine(description=u'Suffix for the file.')


00713 class IFilesystemExporter(Interface):
    """ Plugin interface for site structure export.
    """
00716     def export(export_context, subdir, root=False):
        """ Export our 'context' using the API of 'export_context'.

        o 'export_context' must implement
          Products.GenericSupport.interfaces.IExportContext.

        o 'subdir', if passed, is the relative subdirectory containing our
          context within the site.

        o 'root', if true, indicates that the current context is the
          "root" of an import (this may be used to adjust paths when
          interacting with the context).
        """

00730     def listExportableItems():
        """ Return a sequence of the child items to be exported.

        o Each item in the returned sequence will be a tuple,
          (id, object, adapter) where adapter must implement
          IFilesystemExporter.
        """

00738 class IFilesystemImporter(Interface):
    """ Plugin interface for site structure export.
    """
00741     def import_(import_context, subdir, root=False):
        """ Import our 'context' using the API of 'import_context'.

        o 'import_context' must implement
          Products.GenericSupport.interfaces.IImportContext.

        o 'subdir', if passed, is the relative subdirectory containing our
          context within the site.

        o 'root', if true, indicates that the current context is the
          "root" of an import (this may be used to adjust paths when
          interacting with the context).
        """

00755 class IContentFactory(Interface):
    """ Adapter interface for factories specific to a container.
    """
00758     def __call__(id):
        """ Return a new instance, seated in the context under 'id'.
        """

00762 class IContentFactoryName(Interface):
    """ Adapter interface for finding the name of the ICF for an object.
    """
00765     def __call__():
        """ Return a string, suitable for looking up an IContentFactory.
        
        o The string should allow finding a factory for our context's
          container which would create an "empty" instance of the same
          type as our context.
        """

00773 class ICSVAware(Interface):
    """ Interface for objects which dump / load 'text/comma-separated-values'.
    """
00776     def getId():
        """ Return the Zope id of the object.
        """

00780     def as_csv():
        """ Return a string representing the object as CSV.
        """

00784     def put_csv(fd):
        """ Parse CSV and update the object.

        o 'fd' must be a file-like object whose 'read' method returns
          CSV text parseable by the 'csv.reader'.
        """

00791 class IINIAware(Interface):
    """ Interface for objects which dump / load INI-format files..
    """
00794     def getId():
        """ Return the Zope id of the object.
        """

00798     def as_ini():
        """ Return a string representing the object as INI.
        """

00802     def put_ini(stream_or_text):
        """ Parse INI-formatted text and update the object.

        o 'stream_or_text' must be either a string, or else a stream
          directly parseable by ConfigParser.
        """

00809 class IDAVAware(Interface):
    """ Interface for objects which handle their own FTP / DAV operations.
    """
00812     def getId():
        """ Return the Zope id of the object.
        """

00816     def manage_FTPget():
        """ Return a string representing the object as a file.
        """

00820     def PUT(REQUEST, RESPONSE):
        """ Parse file content and update the object.

        o 'REQUEST' will have a 'get' method, which will have the 
          content object in its "BODY" key.  It will also have 'get_header'
          method, whose headers (e.g., "Content-Type") may affect the
          processing of the body.
        """

00829 class IBeforeProfileImportEvent(Interface):
    """ An event which is fired before (part of) a profile is imported.
    """
    profile_id = Attribute("id of the profile to be imported or None for non-profile imports.")

    steps = Attribute("list of steps that will be imported")

    full_import = Attribute("True if all steps will be imported")

    tool = Attribute("The tool which is performing the import")


00841 class IProfileImportedEvent(Interface):
    """ An event which is fired when (part of) a profile is imported.
    """
    profile_id = Attribute("id of the imported profile")

    steps = Attribute("list of steps have been imported")

    full_import = Attribute("True if all steps are imported")

    tool = Attribute("The tool which is performing the import")


Generated by  Doxygen 1.6.0   Back to index