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

##
## interfaces.py
## Login : <uli@pu.smp.net>
## Started on  Sun Jan 16 15:30:01 2011 Uli Fouquet
## $Id$
## 
## Copyright (C) 2011 Uli Fouquet
## This program is free software; you can redistribute it and/or modify
## it under the terms of the GNU General Public License as published by
## the Free Software Foundation; either version 2 of the License, or
## (at your option) any later version.
## 
## This program is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
## GNU General Public License for more details.
## 
## You should have received a copy of the GNU General Public License
## along with this program; if not, write to the Free Software
## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
##
"""Interfaces regarding student applicants and related components.
"""
import os
import waeup.sirp.browser
from grokcore.content.interfaces import IContainer
from zc.sourcefactory.basic import BasicSourceFactory
from zope import schema
from zope.component import getUtility, getUtilitiesFor
from zope.interface import Interface, Attribute
from zope.pluggableauth.interfaces import IPrincipalInfo
from zope.security.interfaces import IGroupClosureAwarePrincipal as IPrincipal
from waeup.sirp.image.schema import ImageFile
from waeup.sirp.image.image import WAeUPImageFile
from waeup.sirp.interfaces import IWAeUPObject, SimpleWAeUPVocabulary


IMAGE_PATH = os.path.join(
    os.path.dirname(waeup.sirp.browser.__file__),
    'static'
    )
DEFAULT_PASSPORT_IMAGE_MALE = WAeUPImageFile(
    'passport.jpg',
    open(os.path.join(IMAGE_PATH, 'placeholder_m.jpg')).read(),
    )
DEFAULT_PASSPORT_IMAGE_FEMALE = WAeUPImageFile(
    'passport.jpg',
    open(os.path.join(IMAGE_PATH, 'placeholder_f.jpg')).read(),
    )

#: Categories of applications we support.
#: Yet not complete nor correct.
APPLICATION_CATEGORIES = (
    ('Direct Entry Screening Exam (PDE)', 'pde'),
    ('Post-UME', 'pume'),
    ('Post-UDE', 'pude'),
    ('PCE', 'pce'),
    ('Common Entry Screening Test (CEST)', 'cest'),
    )

#: A :class:`waeup.sirp.interfaces.SimpleWAeUPVocabulary` of supported
#: application categories.
application_categories_vocab = SimpleWAeUPVocabulary(*APPLICATION_CATEGORIES)

class GenderSource(BasicSourceFactory):
    """A gender source delivers basically a mapping
       ``{'m': 'male', 'f': 'female'}``

       Using a source, we make sure that the tokens (which are
       stored/expected for instance from CSV files) are something one
       can expect and not cryptic IntIDs.
    """
    def getValues(self):
        return ['m', 'f']

    def getToken(self, value):
        return value[0].lower()
        
    def getTitle(self, value):
        if value == 'm':
            return 'male'
        if value == 'f':
            return 'female'
            
class ApplicantContainerProviderSource(BasicSourceFactory):
    """A source offering all available applicants container types.

    The values returned by this source are names of utilities that can
    create :class:`ApplicantContainer` instances. So, if you get a
    name like ``'myactype'`` from this source, then you can do:

      >>> from zope.component import getUtility
      >>> p = getUtility(IApplicantsContainerProvider, name=myactype)
      >>> my_applicants_container = p.factory()

    Or you can access class-attributes like

      >>> my_applicants_container.container_title
      'Pretty'
    
    """
    def getValues(self):
        """Returns a list of ``(<name>, <provider>)`` tuples.

        Here ``<name>`` is the name under which an
        :class:``ApplicantContainerProvider`` was registered as a
        utility and ``<provider>`` is the utility itself.
        """
        return getUtilitiesFor(IApplicantsContainerProvider)

    def getToken(self, value):
        """Return the name of the ``(<name>, <provider>)`` tuple.
        """
        return value[0]

    def getTitle(self, value):
        """Get a 'title - description' string for a container type.
        """
        factory = value[1].factory
        return "%s - %s" % (
            factory.container_title, factory.container_description)

class IResultEntry(IWAeUPObject):
    subject = schema.TextLine(
        title = u'Subject',
        description = u'The subject',
        required=False,
        )
    score = schema.TextLine(
        title = u'Score',
        description = u'The score',
        required=False,
        )

class IApplicantsRoot(IWAeUPObject, IContainer):
    """A container for university applicants containers.
    """
    pass
    

class IApplicantsContainer(IWAeUPObject):
    """An applicants container contains university applicants.

    """

    container_title = Attribute(
        u'classattribute: title for type of container')
    container_description = Attribute(
        u'classattribute: description for type of container')

    
    code = schema.TextLine(
        title = u'Code',
        description = u'Abbreviated code of applicants container',
        default = u'NA',
        required = True,
        readonly = True,
        )   
    
    provider = schema.Choice(
        title = u'Applicants container type',
        required = True,
        default = None,
        source = ApplicantContainerProviderSource(),
        )        
    
    title = schema.TextLine(
        title = u'Title of the type of applicants stored here',
        required = True,
        default = u'Untitled',
        )
    
    description = schema.Text(
        title = u'Human readable description in reST format',
        required = False,
        default = u'No description yet.'
        )

    startdate = schema.Date(
        title = u'Date when the application period starts',
        required = False,
        default = None,
        )

    enddate = schema.Date(
        title = u'Date when the application period ends',
        required = False,
        default = None,
        )

    strict_deadline = schema.Bool(
        title = u'Forbid additions after deadline (enddate)',
        required = True,
        default = True,
        )

    def archive(id=None):
        """Create on-dist archive of applicants stored in this term.

        If id is `None`, all applicants are archived.

        If id contains a single id string, only the respective
        applicants are archived.

        If id contains a list of id strings all of the respective
        applicants types are saved to disk.
        """

    def clear(id=None, archive=True):
        """Remove applicants of type given by 'id'.

        Optionally archive the applicants.
        
        If id is `None`, all applicants are archived.

        If id contains a single id string, only the respective
        applicants are archived.

        If id contains a list of id strings all of the respective
        applicant types are saved to disk.

        If `archive` is ``False`` none of the archive-handling is done
        and respective applicants are simply removed from the
        database.
        """

class IApplicantsContainerAdd(IApplicantsContainer):
    """An applicants container contains university applicants.
    """
    code = schema.TextLine(
        title = u'Code',
        description = u'Abbreviated code of applicants container',
        default = u'NA',
        required = True,
        readonly = False,
        )    

IApplicantsContainerAdd['code'].order =  IApplicantsContainer['code'].order

class IApplicantBaseData(IWAeUPObject):
    """The data for an applicant.

    This is a base interface with no field (except ``reg_no``)
    required. For use with importers, forms, etc., please use one of
    the derived interfaces below, which set more fields to required
    state, depending on use-case.
    """
    reg_no = schema.TextLine(
        title = u'JAMB Registration Number',
        )
    access_code = schema.TextLine(
        title = u'Access Code',
        required = False,
        )
    serial = schema.TextLine(
        title = u'Serial Number',
        required = False,
        )
    course1 = schema.TextLine(
        title = u'1st Choice Course of Study',
        required = False,
        )
    course2 = schema.TextLine(
        title = u'2nd Choice Course of Study',
        required = False,
        )
    course3 = schema.TextLine(
        title = u'3rd Choice Course of Study',
        required = False,
        )
    firstname = schema.TextLine(
        title = u'First Name',
        required = False,
        )
    middlenames = schema.TextLine(
        title = u'Middle Names',
        required = False,
        )
    lastname = schema.TextLine(
        title = u'Surname/Full Name',
        required = False,
        )
    date_of_birth = schema.Date(
        title = u'Date of Birth',
        required = False,
        )
    lga = schema.TextLine(
        # XXX: should be choice
        title = u'State/LGA (confirmed by applicant)',
        required = False,
        )
    sex = schema.Choice(
        title = u'Sex',
        source = GenderSource(),
        default = u'm',
        required = False,
        )
    email = schema.TextLine(
        title = u'Email',
        required = False,
        )
    phone = schema.TextLine(
        title = u'Phone',
        required = False,
        )
    passport = ImageFile(
        title = u'Passport Photograph',
        default = DEFAULT_PASSPORT_IMAGE_MALE,
        required = True,
        )
    aos = schema.TextLine(
        # XXX: should be choice
        title = u'Area of Specialisation',
        required = False,
        )
    subj1 = schema.TextLine(
        # XXX: should be choice
        title = u'1st Choice of Study',
        required = False,
        )
    subj2 = schema.TextLine(
        # XXX: should be choice
        title = u'2nd Choice of Study',
        required = False,
        )
    subj3 = schema.TextLine(
        # XXX: should be choice
        title = u'3rd Choice of Study',
        required = False,
        )
    #
    # Higher Educational Data
    #
    hq_matric_no = schema.TextLine(
        title = u'Former Matric Number',
        required = False,
        )
    hq_type = schema.TextLine(
        title = u'Higher Qualification',
        required = False,
        )
    hq_grade = schema.TextLine(
        title = u'Higher Qualification Grade',
        required = False,
        )
    hq_school = schema.TextLine(
        title = u'School Attended',
        required = False,
        )
    hq_session = schema.TextLine(
        title = u'Session Obtained',
        required = False,
        )
    hq_disc = schema.TextLine(
        title = u'Discipline',
        required = False,
        )
    #
    # First sitting data
    #
    fst_sit_fname = schema.TextLine(
        title = u'Full Name',
        required = False,
        )
    fst_sit_no = schema.TextLine(
        title = u'Exam Number',
        required = False,
        )
    fst_sit_date = schema.Date(
        title = u'Exam Date (dd/mm/yyyy)',
        required = False,
        )
    fst_sit_type = schema.TextLine(
        # XXX: Should be choice
        title = u'Exam Type',
        required = False,
        )
    fst_sit_results = schema.List(
        title = u'Results',
        required = False,
        value_type = schema.Object(
            title = u'Entries',
            schema = IResultEntry,
            required = False,
            )
        )
    scd_sit_fname = schema.TextLine(
        title = u'Full Name',
        required = False,
        )
    scd_sit_no = schema.TextLine(
        title = u'Exam Number',
        required = False,
        )
    scd_sit_date = schema.Date(
        title = u'Exam Date (dd/mm/yyyy)',
        required = False,
        )
    scd_sit_type = schema.TextLine(
        # XXX: Should be choice
        title = u'Exam Type',
        required = False,
        )
    scd_sit_results = schema.TextLine(
        # XXX: Should be nested list of choices
        title = u'Results',
        required = False,
        )
    #
    # JAMB scores
    #
    eng_score = schema.TextLine(
        title = u"'English' score",
        required = False,
        )
    subj1score = schema.TextLine(
        title = u'1st Choice of Study Score',
        required = False,
        )
    subj2score = schema.TextLine(
        title = u'2nd Choice of Study Score',
        required = False,
        )
    subj3score = schema.TextLine(
        title = u'3rd Choice of Study Score',
        required = False,
        )
    # XXX: Total score???
    
    #
    # Application Data
    #
    application_date = schema.Date(
        title = u'Application Date',
        required = False,
        )
    status = schema.TextLine(
        # XXX: should be 'status' type
        title = u'Application Status',
        required = False,
        )
    screening_date = schema.Date(
        title = u'Screening Date',
        required = False,
        )
    screening_type = schema.TextLine(
        # XXX: schould be choice
        title = u'Screening Type',
        required = False,
        )
    screening_score = schema.TextLine(
        title = u'Screening Score',
        required = False,
        )
    screening_venue = schema.TextLine(
        title = u'Screening Venue',
        required = False,
        )
    total_score = schema.TextLine(
        title = u'Total Score',
        required = False,
        )
    course_admitted = schema.TextLine(
        # XXX: should be choice
        title = u'Admitted Course of Study',
        required = False,
        )
    department = schema.TextLine(
        # XXX: if we have a course, dept. is not necessary
        title = u'Department',
        required = False,
        )
    faculty = schema.TextLine(
        # XXX: if we have a course, faculty is not necessary
        title = u'Faculty',
        required = False,
        )
    entry_session = schema.TextLine(
        # XXX: should be choice, should have sensible default: upcoming session
        title = u'Entry Session',
        required = False,
        )
    notice = schema.Text(
        title = u'Notice',
        required = False,
        )
    student_id = schema.TextLine(
        title = u'Student ID',
        required = False,
        )
    import_record_no = schema.TextLine(
        title = u'Import Record No.',
        required = False,
        )
    imported_by = schema.TextLine(
        title = u'Imported By',
        required = False,
        )
    import_date = schema.Datetime(
        title = u'Import Date',
        required = False,
        )
    import_from = schema.TextLine(
        title = u'Import Source',
        required = False,
        )
    confirm_passport = schema.Bool(
        title = u"Confirmation that photograph represents applicant ticked.",
        default = False,
        required = True,
        )

    
class IApplicant(IApplicantBaseData):
    """An applicant.

    This is basically the applicant base data. Here we repeat the
    fields from base data only with the `required` attribute of
    required attributes set to True (which is the default).
    """
    locked = schema.Bool(
        title = u'Form locked',
        default = False,
        readonly = True,
        )
    access_code = schema.TextLine(
        title = u'Access Code',
        )
    course1 = schema.TextLine(
        title = u'1st Choice Course of Study',
        )
    firstname = schema.TextLine(
        title = u'First Name',
        )
    middlenames = schema.TextLine(
        title = u'Middle Names',
        )
    lastname = schema.TextLine(
        title = u'Surname/Full Name',
        )
    date_of_birth = schema.Date(
        title = u'Date of Birth',
        )
    jamb_state = schema.TextLine(
        title = u'State (provided by JAMB)',
        )
    jamb_lga = schema.TextLine(
        title = u'LGA (provided by JAMB)',
        )
    lga = schema.TextLine(
        # XXX: should be choice
        title = u'State/LGA (confirmed by applicant)',
        )
    sex = schema.Choice(
        title = u'Sex',
        source = GenderSource(),
        default = u'm',
        )
    #passport = schema.Bool(
    #    title = u'Passport Photograph',
    #    default = True,
    #    )
    passport = ImageFile(
        title = u'Passport Photograph',
        default = DEFAULT_PASSPORT_IMAGE_MALE,
        required = True ,
        )
    #
    # Higher Educational Data
    #

    #
    # First sitting data
    #
    fst_sit_fname = schema.TextLine(
        title = u'Full Name',
        )

    #
    # Second sitting data
    #
    scd_sit_fname = schema.TextLine(
        title = u'Full Name',
        )
    #
    # Application Data
    #
    application_date = schema.Date(
        title = u'Application Date',
        )
    status = schema.TextLine(
        # XXX: should be 'status' type
        title = u'Application Status',
        )
    screening_date = schema.Date(
        title = u'Screening Date',
        )
    screening_type = schema.TextLine(
        # XXX: schould be choice
        title = u'Screening Type',
        )
    screening_score = schema.TextLine(
        title = u'Screening Score',
        )
    entry_session = schema.TextLine(
        # XXX: should be choice
        # XXX: should have sensible default: upcoming session
        title = u'Entry Session',
        )
    import_record_no = schema.TextLine(
        title = u'Import Record No.',
        )
    imported_by = schema.TextLine(
        title = u'Imported By',
        )
    import_date = schema.Datetime(
        title = u'Import Date',
        )
    import_from = schema.TextLine(
        title = u'Import Source',
        )

class IApplicantPDEEditData(IWAeUPObject):
    """The data set presented to PDE applicants.
    """
    locked = schema.Bool(
        title = u'Form locked',
        default = False,
        readonly = True,
        )
    access_code = schema.TextLine(
        title = u'Access Code',
        readonly = True,
        )
    course1 = schema.TextLine(
        title = u'1st Choice Course of Study',
        readonly = True,
        )
    course2 = schema.TextLine(
        title = u'2nd Choice Course of Study',
        required = False,
        )
    course3 = schema.TextLine(
        title = u'3rd Choice Course of Study',
        required = False,
        )
    lastname = schema.TextLine(
        title = u'Name',
        readonly = True,
        )
    date_of_birth = schema.Date(
        title = u'Date of Birth',
        required = True,
        )
    lga = schema.TextLine(
        # XXX: should be choice
        title = u'State/LGA (confirmed by applicant)',
        required = False,
        )
    email = schema.TextLine(
        title = u'Email',
        required = False,
        )
    phone = schema.TextLine(
        title = u'Phone',
        required = False,
        )
    aos = schema.TextLine(
        # XXX: should be choice
        title = u'Area of Specialisation',
        required = False,
        )
    subj1 = schema.TextLine(
        # XXX: should be choice
        title = u'1st Choice of Study',
        readonly = True,
        )
    subj2 = schema.TextLine(
        # XXX: should be choice
        title = u'2nd Choice of Study',
        required = False,
        )
    subj3 = schema.TextLine(
        # XXX: should be choice
        title = u'3rd Choice of Study',
        required = False,
        )
    
    #
    # Application Data
    #
    application_date = schema.Date(
        title = u'Application Date',
        readonly = True,
        )
    status = schema.TextLine(
        # XXX: should be 'status' type
        title = u'Application Status',
        readonly = True,
        )
    screening_date = schema.Date(
        title = u'Screening Date',
        readonly = True,
        )
    passport = ImageFile(
        title = u'Passport Photograph',
        default = DEFAULT_PASSPORT_IMAGE_MALE,
        required = True,
        )
    confirm_passport = schema.Bool(
        title = u"Confirmation that photograph represents applicant ticked.",
        default = False,
        required = True,
        )

    
class IApplicantPrincipalInfo(IPrincipalInfo):
    """Infos about principals that are applicants.
    """
    access_code = Attribute("The Access Code the user purchased")

class IApplicantPrincipal(IPrincipal):
    """A principal that is an applicant.

    This interface extends zope.security.interfaces.IPrincipal and
    requires also an `id` and other attributes defined there.
    """
    access_code = schema.TextLine(
        title = u'Access Code',
        description = u'The access code purchased by the user.',
        required = True,
        readonly = True)

class IApplicantsFormChallenger(Interface):
    """A challenger that uses a browser form to collect applicant
       credentials.
    """
    loginpagename = schema.TextLine(
        title = u'Loginpagename',
        description = u"""Name of the login form used by challenger.

        The form must provide an ``access_code`` input field.
        """)

    accesscode_field = schema.TextLine(
        title = u'Access code field',
        description = u'''Field of the login page which is looked up for
                          access_code''',
        default = u'access_code',
        )


class IApplicantSessionCredentials(Interface):
    """Interface for storing and accessing applicant credentials in a
       session.
    """

    def __init__(access_code):
        """Create applicant session credentials."""

    def getAccessCode():
        """Return the access code."""


class IApplicantsContainerProvider(Interface):
    """A provider for applicants containers.

    Applicants container providers are meant to be looked up as
    utilities. This way we can find all applicant container types
    defined somewhere.

    Each applicants container provider registered as utility provides
    one container type and one should be able to call the `factory`
    attribute to create an instance of the requested container type.

    .. THE FOLLOWING SHOULD GO INTO SPHINX DOCS (and be tested)
    
    Samples
    *******
    
    Given, you had an IApplicantsContainer implementation somewhere
    and you would like to make it findable on request, then you would
    normally create an appropriate provider utility like this::

      import grok
      from waeup.sirp.applicants.interfaces import IApplicantsContainerProvider

      class MyContainerProvider(grok.GlobalUtility):
          grok.implements(IApplicantsContainerProvider)
          grok.name('MyContainerProvider') # Must be unique
          factory = MyContainer # A class implementing IApplicantsContainer
                                # or derivations thereof.

    This utility would be registered on startup and could then be used
    like this:

      >>> from zope.component import getAllUtilitiesRegisteredFor
      >>> from waeup.sirp.applicants.interfaces import (
      ...     IApplicantsContainerProvider)
      >>> all_providers = getAllUtilitiesRegisteredFor(
      ...     IApplicantsContainerProvider)
      >>> all_providers
      [<MyContainerProvider object at 0x...>]

    You could look up this specific provider by name:

      >>> from zope.component import getUtility
      >>> p = getUtility(IApplicantsContainerProvider, name='MyProvider')
      >>> p
      <MyContainerProvider object at 0x...>
      
    An applicants container would then be created like this:

      >>> provider = all_providers[0]
      >>> container = provider.factory()
      >>> container
      <MyContainer object at 0x...>

    """
    factory = Attribute("A class that can create instances of the "
                        "requested container type")