source: main/waeup.sirp/trunk/src/waeup/sirp/interfaces.py @ 5967

##
## interfaces.py
from zc.sourcefactory.basic import BasicSourceFactory
from zope.component import getUtility
from zope.component.interfaces import IObjectEvent
try:
    from zope.catalog.interfaces import ICatalog
except ImportError:
    # BBB
    from zope.app.catalog.interfaces import ICatalog
from zope.interface import Interface, Attribute, implements
from zope import schema
from zope.schema.vocabulary import SimpleVocabulary, SimpleTerm
from waeup.sirp.permissions import RoleSource

class IThemesProvider(Interface):
    """A component that delivers all themes defined.

    We normally do not deal with browser-related stuff in `waeup.sirp`
    but leave that to the `browser` subpackage. With themes (aka
    skins) we cannot follow that path because we need a theme as an
    attribute of each `University` instance.

    Therefore we must tell the browser subpackage how we expect themes
    to be announced code-wise.

    What we tell here is that we might ask for a utility providing
    IThemeProvider and that this component then should be callable to
    give us a list of themes and their respective internal names.
    """
    def __call__():
        """Get a list of all themes available.

        Returns a list of ``(<NAME>, <THEME>)`` tuples where
        ``<NAME>`` is the internal name under which a theme was
        registered and ``<THEME>`` is the real theme.

        Each <THEME> must have a `description` attribute.
        """

class ThemesSource(BasicSourceFactory):
    """A source for themes.
    """
    def getValues(self):
        """Get names of themes.
        """
        themes_provider = getUtility(IThemesProvider, name="default")
        return [x for x, y in themes_provider()]
    
    def getTitle(self, value):
        """Get a user-presentable description for a theme.
        """
        themes_provider = getUtility(IThemesProvider, name="default")
        for name, theme in themes_provider():
            if name == value:
                return theme.description
        return u'unnamed'

class ThemesSourceBinder(object):
    """A source binder for the `ThemeSource`.

    Normally, we can pass instances of a source (like `ThemeSource`)
    directly to fields in interfaces (writing something like ``source
    = ThemeSource()``. With `ThemeSource` we cannot do this, because
    the set of available themes is not available before the whole
    `waeup.sirp` package was grokked (and parsed).

    We bypass that problem by defining this trivial source-binder,
    which is asked for themes only when the values of the source are
    really needed and after the process of grokking and parsing
    everything on startup.

    So, although this binder binds to some context (`IUniversity` is
    currently the only interface making use of this source, so
    `University` instances are the only context used), the context
    does not really matter.
    """
    implements(schema.interfaces.IContextSourceBinder)

    def __call__(self, context):
        return ThemesSource()

class FatalCSVError(Exception):
    """Some row could not be processed.
    """
    pass

def SimpleWAeUPVocabulary(*terms):
    """A well-buildt vocabulary provides terms with a value, token and
       title for each term
    """
    return SimpleVocabulary([
            SimpleTerm(value, value, title) for title, value in terms])


class IWAeUPObject(Interface):
    """A WAeUP object.

    This is merely a marker interface.
    """

class IUniversity(IWAeUPObject):
    """Representation of a university.
    """
    name = schema.TextLine(
        title = u'Name of University',
        default = u'Unnamed',
        required = True,
        )

        
    skin = schema.Choice(
        title = u'Skin',
        default = u'waeuptheme-gray1.css',
        source = ThemesSourceBinder(),
        required = True,
        )

    faculties = Attribute("A container for faculties.")
    students = Attribute("A container for students.")
    hostels = Attribute("A container for hostels.")
    
class IWAeUPContainer(IWAeUPObject):
    """A container for WAeUP objects.
    """

class IWAeUPContained(IWAeUPObject):
    """An item contained in an IWAeUPContainer.
    """
    
class IStudentContainer(IWAeUPContainer):
    """A container for StudentObjects.
    """


class IHostelContainer(IWAeUPContainer):
    """A container for hostels.
    """
    def addHostel(hostel):
        """Add an IHostel object.

        Returns the key, under which the object was stored.
        """

class IHostel(IWAeUPObject):
    """Representation of a hostel.
    """
    name = schema.TextLine(
        title = u'Name of Hostel',
        default = u'Nobody',
        required = True,
        )

        
class IWAeUPExporter(Interface):
    """An exporter for objects.
    """
    def export(obj, filepath=None):
        """Export by pickling.

        Returns a file-like object containing a representation of `obj`.

        This is done using `pickle`. If `filepath` is ``None``, a
        `cStringIO` object is returned, that contains the saved data.
        """

class IWAeUPXMLExporter(Interface):
    """An XML exporter for objects.
    """
    def export(obj, filepath=None):
        """Export as XML.

        Returns an XML representation of `obj`.

        If `filepath` is ``None``, a StringIO` object is returned,
        that contains the transformed data.
        """

class IWAeUPXMLImporter(Interface):
    """An XML import for objects.
    """
    def doImport(filepath):
        """Create Python object from XML.

        Returns a Python object.
        """

class IBatchProcessor(Interface):
    """A batch processor that handles mass-operations.
    """
    name = schema.TextLine(
        title = u'Importer name'
        )

    mode = schema.Choice(
        title = u'Import mode',
        values = ['create', 'update', 'remove']
        )
    
    def doImport(path, headerfields, mode='create', user='Unknown',
                 logger=None):
        """Read data from ``path`` and update connected object.

        `headerfields` is a list of headerfields as read from the file
        to import.

        `mode` gives the import mode to use (``'create'``,
        ``'update'``, or ``'remove'``.

        `user` is a string describing the user performing the
        import. Normally fetched from current principal.

        `logger` is the logger to use during import.
        """

class ISchemaTypeConverter(Interface):
    """A converter for zope.schema.types.
    """
    def convert(string):
        """Convert string to certain schema type.
        """

    
class IUserAccount(IWAeUPObject):
    """A user account.
    """
    name = schema.TextLine(
        title = u'User ID',
        description = u'Loginname',
        required = True,)
    title = schema.TextLine(
        title = u'Username',
        description = u'Real name',
        required = False,)
    description = schema.TextLine(
        title = u'User description',
        required = False,)
    password = schema.Password(
        title = u'Password',
        required = True,)
    roles = schema.List(
        title = u'Roles',
        value_type = schema.Choice(source=RoleSource()))
    
    
class IUserContainer(IWAeUPObject):
    """A container for users (principals).

    These users are used for authentication purposes.
    """

    def addUser(name, password, title=None, description=None):
        """Add a user.
        """

    def delUser(name):
        """Delete a user if it exists.
        """

class IDataCenter(IWAeUPObject):
    """A data center.

    TODO : declare methods, at least those needed by pages.
    """
    pass

class IDataCenterFile(Interface):
    """A data center file.
    """

    name = schema.TextLine(
        title = u'Filename')

    size = schema.TextLine(
        title = u'Human readable file size')

    uploaddate = schema.TextLine(
        title = u'Human readable upload datetime')

    lines = schema.Int(
        title = u'Number of lines in file')
        
    def getDate():
        """Get creation timestamp from file in human readable form.
        """

    def getSize():
        """Get human readable size of file.
        """

    def getLinesNumber():
        """Get number of lines of file.
        """

class IDataCenterStorageMovedEvent(IObjectEvent):
    """Emitted, when the storage of a datacenter changes.
    """

class IQueryResultItem(Interface):
    """An item in a search result.
    """
    url = schema.TextLine(
        title = u'URL that links to the found item')
    title = schema.TextLine(
        title = u'Title displayed in search results.')
    description = schema.Text(
        title = u'Longer description of the item found.')
     
class IWAeUPSIRPPluggable(Interface):
    """A component that might be plugged into a WAeUP SIRP app.

    Components implementing this interface are referred to as
    'plugins'. They are normally called when a new
    :class:`waeup.sirp.app.University` instance is created.

    Plugins can setup and update parts of the central site without the
    site object (normally a :class:`waeup.sirp.app.University` object)
    needing to know about that parts. The site simply collects all
    available plugins, calls them and the plugins care for their
    respective subarea like the applicants area or the datacenter
    area.

    Currently we have no mechanism to define an order of plugins. A
    plugin should therefore make no assumptions about the state of the
    site or other plugins being run before and instead do appropriate
    checks if necessary.

    Updates can be triggered for instance by the respective form in
    the site configuration. You normally do updates when the
    underlying software changed.
    """
    def setup(site, name, logger):
        """Create an instance of the plugin.

        The method is meant to be called by the central app (site)
        when it is created.

        `site`:
           The site that requests a setup.

        `name`:
           The name under which the plugin was registered (utility name).

        `logger`:
           A standard Python logger for the plugins use.
        """

    def update(site, name, logger):
        """Method to update an already existing plugin.

        This might be called by a site when something serious
        changes. It is a poor-man replacement for Zope generations
        (but probably more comprehensive and better understandable).

        `site`:
           The site that requests an update.

        `name`:
           The name under which the plugin was registered (utility name).

        `logger`:
           A standard Python logger for the plugins use.
        """

class IAuthPluginUtility(Interface):
    """A component that cares for authentication setup at site creation.

    Utilities providing this interface are looked up when a Pluggable
    Authentication Utility (PAU) for any
    :class:`waeup.sirp.app.University` instance is created and put
    into ZODB.

    The setup-code then calls the `register` method of the utility and
    expects a modified (or unmodified) version of the PAU back.

    This allows to define any authentication setup modifications by
    submodules or third-party modules/packages.
    """

    def register(pau):
        """Register any plugins wanted to be in the PAU.
        """

    def unregister(pau):
        """Unregister any plugins not wanted to be in the PAU.
        """