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

##
## 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 CourseSource(BasicSourceFactory):
    """A course source delivers all courses inside the portal by looking
       up a catalog.
    """
    def getValues(self):
        catalog = getUtility(ICatalog, name='courses_catalog')
        return list(catalog.searchResults(code=('', 'z*')))

    def getToken(self, value):
        return value.code
        
    def getTitle(self, value):
        return "%s %s" % (value.code, value.title[:32])


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 IFaculty(IWAeUPContainer):
    """Representation of a university faculty.
    """
    title = schema.TextLine(
        title = u'Name of Faculty',
        default = u'Unnamed',
        required = True,
        )

    title_prefix = schema.TextLine(
        title = u'Title prefix',
        default = u'faculty',
        required = True,
        )
    
    code = schema.TextLine(
        title = u'Code',
        description = u'Abbreviated code of the faculty',
        default = u'NA',
        required = True,
        )

class IFacultyContainer(IWAeUPContainer):
    """A container for faculties.
    """
    def addFaculty(faculty):
        """Add an IFactulty object.

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

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 IDepartment(IWAeUPObject):
    """Representation of a department.
    """
    title = schema.TextLine(
        title = u'Name of Department',
        default = u'Unnamed',
        required = True,
        )

    title_prefix = schema.TextLine(
        title = u'Title prefix',
        default = u'department',
        required = True,
        )
    
    code = schema.TextLine(
        title = u'Code',
        default = u'NA',
        description = u'Abbreviated code of the department',
        required = True,
        )

    courses = Attribute("A container for courses.")
    certificates = Attribute("A container for certificates.")


class ICourseContainer(IWAeUPContainer):
    """A container for faculties.
    """
    def addCourse(faculty):
        """Add an ICourse object.

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

class ICourse(IWAeUPObject):
    """Representation of a course.
    """
    code = schema.TextLine(
        title = u'Code',
        default = u'NA',
        description = u'Abbreviated code of the course',
        required = True,
        readonly = True,
        )

    title = schema.TextLine(
        title = u'Title of course',
        default = u'Unnamed',
        required = True,
        )

    level = schema.TextLine(
        title = u'Level',
        default = u'100',
        required = False,
        )

    credits = schema.Int(
        title = u'Credits',
        default = 0,
        required = False,
        )
    
    passmark = schema.Int(
        title = u'Passmark',
        default = 40,
        required = False,
        )

    semester = schema.Choice(
        title = u'Semester/Term',
        default = 0,
        vocabulary = SimpleWAeUPVocabulary(
            ('N/A', 0), ('First Semester', 1),
            ('Second Semester', 2), ('Combined', 3)),
        required = True,
        )


class ICertificate(IWAeUPObject):
    """Representation of a certificate.
    """
    code = schema.TextLine(
        title = u'Code',
        default = u'NA',
        description = u'Abbreviated code of the certificate.',
        required = True,
        )

    review_state = schema.Choice(
        title = u'review state',
        default = 'unchecked',
        values = ['unchecked', 'checked']
        )

    title = schema.TextLine(
        title = u'title',
        required = True,
        )

    category = schema.TextLine(
        title = u'category',
        )

    study_mode = schema.TextLine(
        title = u'study mode',
        required = True,
        )

    start_level = schema.TextLine(
        title = u'start level',
        required = True,
        )
    
    end_level = schema.TextLine(
        title = u'end level',
        required = True,
        )
    
    application_category = schema.TextLine(
        title = u'application category',
        required = True,
        )
    
    max_pass = schema.TextLine(
        title = u'maximum pass',
        )
    

    
class ICertificateContainer(IWAeUPContainer):
    """A container for certificates.
    """
    def addCertificate(faculty):
        """Add an ICertificate object.

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

class ICertificateCourse(IWAeUPObject):
    """A certificatecourse is a course referenced by a certificate, which
       provides some own attributes.
    """
    course = schema.Choice(
        title = u'Course',
        source = CourseSource(),
        )
    
    level = schema.Int(
        title = u'Level of this course',
        required = True,
        default = 100
        )

    core_or_elective = schema.Bool(
        title = u'Is mandatory course (not elective)',
        required = True,
        default = True
        )

    def getCourseCode():
        """Return the code of the referenced course.

        This is needed for cataloging.
        """
        
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 IWAeUPCSVExporter(Interface):
    """A CSV exporter for objects.
    """

    def export(obj, filepath=None):
        """Export as CSV.

        Returns a CSV representation of `obj`.

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

class IWAeUPCSVImporter(Interface):
    """A CSV importer for objects.
    """
    datatype = schema.TextLine(
        title = u'Data type',
        description = u'Type of data supported by this filter.',
        required = True,)

    def doImport(clear_old_data=True, overwrite=True):
        """Read data from `filepath` and apply data.

        It depends on the context, what 'applying data' means here.

        If `clear_old_data` is False, old data will be
        preserved. Otherwise all old data will get lost.

        If `overwrite` is False, any existing entries with similar
        keys might be overwritten. This option is ignored, when
        `clear_old_data` is set to True.
        """

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 ICSVDataReceivers(Interface):
    """An object containing things ready for CSV imports.

    This is pure marker interface. Objects that implement it, indicate
    that they might provide attributes, which are able to receive CSV
    data, i.e. for which an IWAeUPCSVDataImporter exists.
    """

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