source: main/waeup.sirp/branches/ulif-paster/src/waeup/sirp/jambtables/README.txt @ 11107

JAMB registration numbers
*************************

.. :doctest:

JAMB data is stored in a JAMBDataTable.

Creating JAMB Tables
====================

We can import JAMB registration data from a regular CSV file:

    >>> datafile = 'jambsample.csv'
    >>> open(datafile, 'wb').write(
    ... '''reg_no,fst_sit_fname,lastname,firstname,middlenames,sex,date_of_birth,jamb_state,jamb_lga,course1,screening_date,screening_venue,entry_session,screening_type
    ... 91100546DD,ISUOSUO MOSES ODOMERO,ISUOSUO,MOSES,ODOMERO,M,25/5/1982,DEL,ISO-S,BSCPOL,2009/09/25 09:00:00 GMT+1,REPRINT SLIP AS FROM WED 23/09/2009,9,pde
    ... 91111834CC,DURUIHEOMA AUGUSTINA ADANNA,DURUIHEOMA,AUGUSTINA,ADANNA,F,15/4/1986,IMO,MBAIT,BSCPOL,2009/09/25 09:00:00 GMT+1,REPRINT SLIP AS FROM WED 23/09/2009,9,pde
    ... 91109351AC,ARISERE EBIKEBUNA COMFORT,ARISERE,EBIKEBUNA,COMFORT,F,6/1/1984,EDO,OV-SW,BSCPOL,2009/09/25 09:00:00 GMT+1,REPRINT SLIP AS FROM WED 23/09/2009,9,pde
    ... ''')

JAMB CSV tables have to provide the following header fields in the
first line:

    >>> from pprint import pprint
    >>> from waeup.sirp.jambtables.jambtables import JAMB_DATA_HEADERS
    >>> JAMB_DATA_HEADERS
    ['firstname', 'lastname', 'middlenames', 'screening_type',
     'screening_venue', 'reg_no', 'sex', 'course1', 'jamb_state',
     'screening_date', 'jamb_lga', 'fst_sit_fname', 'date_of_birth']

Now we create a JAMBDataTable and import the data:

    >>> from waeup.sirp.jambtables import JAMBDataTable
    >>> table = JAMBDataTable()
    >>> len(list(table))
    0

    >>> table.importFromCSV(datafile)
    >>> len(list(table))
    3

Accessing JAMB Data
===================

Getting Entries
---------------

We can get the entries from the table as an iterator:

    >>> from pprint import pprint
    >>> entries = [x for x in table]
    >>> pprint(entries)
    [{'course1': u'BSCPOL',
      'date_of_birth': datetime.date(1982, 5, 25),
      'entry_session': '9',
      'firstname': u'MOSES',
      'fst_sit_fname': u'ISUOSUO MOSES ODOMERO',
      'jamb_lga': u'ISO-S',
      'jamb_state': u'DEL',
      'lastname': u'ISUOSUO',
      'middlenames': u'ODOMERO',
      'reg_no': u'91100546DD',
      'screening_date': u'2009/09/25 09:00:00 GMT+1',
      'screening_type': u'pde',
      'screening_venue': u'REPRINT SLIP AS FROM WED 23/09/2009',
      'sex': u'M'},
     {...},
     {...}]

Also a :meth:`keys` and :meth:`items` method are available. They both
return an iterator.

The :meth:`keys` method in action:

     >>> pprint(list(table.keys()))
     [u'91100546DD', u'91111834CC', u'91109351AC']

The :meth:`items` method in action:

     >>> pprint(list(table.items()))
     [(u'91100546DD',
      {'course1': u'BSCPOL',
       'date_of_birth': datetime.date(1982, 5, 25),
       'entry_session': '9',
       'firstname': u'MOSES',
       'fst_sit_fname': u'ISUOSUO MOSES ODOMERO',
       'jamb_lga': u'ISO-S',
       'jamb_state': u'DEL',
       'lastname': u'ISUOSUO',
       'middlenames': u'ODOMERO',
       'reg_no': u'91100546DD',
       'screening_date': u'2009/09/25 09:00:00 GMT+1',
       'screening_type': u'pde',
       'screening_venue': u'REPRINT SLIP AS FROM WED 23/09/2009',
       'sex': u'M'}),
     (u'91111834CC',
      {...}),
     (u'91109351AC',
      {...})]

A ``values()``-like behaviour cen be archieved by simply using the
iterator.

Getting JAMB Table Meta Data
----------------------------

We can also get a datetime stamp, that tells, when the table was
imported. This could help with maintaining old tables:

    >>> table.import_datetime
    datetime.datetime(..., ..., ..., ..., ..., ..., ...)
    

We can delete the table:

    >>> del JAMBDataTable

Clean up:

    >>> import os
    >>> os.unlink(datafile)