##
## 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
from zope import schema
from zope.schema.vocabulary import SimpleVocabulary, SimpleTerm
from waeup.sirp.permissions import RoleSource

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

class IUniversity(IWAeUPObject):
    """Representation of a university.
    """
    name = schema.TextLine(
        title = u'Name of University',
        default = u'Unnamed',
        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):
        """Read data from ``path`` and update connected object.
        """

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.
    """
    def setup(site, name, logger):
        """Create an instance of the plugin.

        The method is meant to be called by the central app on startup.
        """

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