##
## interfaces.py
## Login : <uli@pu.smp.net>
## Started on  Sun Jun 27 11:06:23 2010 Uli Fouquet
## $Id$
## 
## Copyright (C) 2010 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 for JAMB data tables and related components.
"""
from waeup.sirp.interfaces import IWAeUPObject
from zc.sourcefactory.basic import BasicSourceFactory
from zope import schema
from zope.interface import Interface, Attribute
from zope.pluggableauth.interfaces import IPrincipalInfo
from zope.security.interfaces import IGroupClosureAwarePrincipal as IPrincipal


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 IJAMBDataTable(IWAeUPObject):
    """A table containing JAMB data.
    """
    import_datetime = schema.Datetime(
        title = u'Datetime of import of contained data.',
        required = False,
        )

    importer_username = schema.TextLine(
        title = u'Name of user who initiated import.',
        required = False,
        )

    def __iter__():
        """An iterator over all data elements.
        """

    def keys():
        """Get iterator over all registration numbers of data.
        """

    def items():
        """Get iterator over tuples of registration numbers and datasets.
        """

    def clear():
        """Clear all data contained.

        This will also erase any import data.
        """

    def importFromCSV(filepath, username=None):
        """Import data from filepath.

        `filepath` - the path to the CSV file to import data from.

        `username` - the (optional) username of the importing person.
        """
        
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 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,
        )
    jamb_age = schema.Int(
        title = u'Age (provided by JAMB)',
        required = False,
        )
    date_of_birth = schema.Date(
        title = u'Date of Birth',
        required = False,
        )
    jamb_state = schema.TextLine(
        title = u'State (provided by JAMB)',
        required = False,
        )
    jamb_lga = schema.TextLine(
        title = u'LGA (provided by JAMB)',
        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 = schema.Bool(
        title = u'Passport Photograph',
        default = True,
        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',
        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
        # XXX: 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,
        )

    
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).
    """
    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,
        )
    #
    # 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',
        )
    #
    # JAMB scores
    #
    
    #
    # 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 IApplicantPDEImportData(IApplicantBaseData):
    """Data for applicants, that passed PDE screening.

    This data set should be suitable for imports from JAMB tables. It
    is also basicall the basic applicant data from
    :class:`IApplicantBaseData` only with the required fields set.

    """
    firstname = schema.TextLine(
        title = u'First Name',
        required = True,
        )
    middlenames = schema.TextLine(
        title = u'Middle Names',
        required = True,
        )
    lastname = schema.TextLine(
        title = u'Surname/Full Name',
        required = True,
        )
    date_of_birth = schema.Date(
        title = u'Date of Birth',
        required = True,
        )
    jamb_state = schema.TextLine(
        title = u'State (provided by JAMB)',
        required = True,
        )
    jamb_lga = schema.TextLine(
        title = u'LGA (provided by JAMB)',
        required = True,
        )
    course1 = schema.TextLine(
        title = u'1st Choice Course of Study',
        required = True,
        )
    screening_date = schema.Date(
        title = u'Screening Date',
        required = True,
        )
    screening_type = schema.TextLine(
        # XXX: schould be choice
        title = u'Screening Type',
        required = True,
        )
    screening_venue = schema.TextLine(
        title = u'Screening Venue',
        required = True,
        )
    entry_session = schema.TextLine(
        # XXX: should be choice
        # XXX: should have sensible default: upcoming session
        title = u'Entry Session',
        required = True,
        )
    
class IApplicantContainer(IWAeUPObject):
    """A container for applicants.
    """

class IApplicantPrincipalInfo(IPrincipalInfo):
    """Infos about principals that are applicants.
    """
    reg_no = Attribute("The JAMB registration no. of the user")

    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.
    """
    reg_no = schema.TextLine(
        title = u'Registration number',
        description = u'The JAMB registration number',
        required = True,
        readonly = True)

    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 IJAMBApplicantsFormChallenger(IApplicantsFormChallenger):
    """A challenger that uses a browser form to collect applicant
       credentials for applicants in JAMB process.

       JAMB-screened applicants have to provide an extra registration
       no. provided by JAMB.
    """
    jamb_reg_no_field = schema.TextLine(
        title = u'JAMB registration no.',
        description = u'''Field of the login page which is looked up for
                          the JAMB registration number.''',
        default = u'jamb_reg_no',
        )

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

    def __init__(access_code):
        pass

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


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

    def __init__(access_code, jamb_reg_no):
        pass

    def getJAMBRegNo():
        """Return the JAMB registration no."""