##
## interfaces.py
from zc.sourcefactory.basic import BasicSourceFactory
from zope.component import getUtility
from zope.component.interfaces import IObjectEvent
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.
    """
    factory_name = schema.TextLine(
        title = u'Name of the factory to create an instance of the pluggble.',
        description = u'The given name should be usable for '
                      u'calls like createObject(factory_name).' )

    name = schema.TextLine(
        title = u'Name under which the pluggable should be created.')