Christmas Bird Count history report system

See the general remarks on program flow in Section 10.1, “hist.cgi: Overall flow”.

# - - - - -   m a i n

def main():
    '''Generate a history of one or more Christmas Bird Count circles.

      [ if (xnomo3's taxonomic authority file is readable and
        valid) and
        (the pycbc database is available) and
        (PASS_FILE names a readable file containing the pycbc
        database password) and 
        (the CGI arguments are valid and consistent with the pycbc
        database) ->
          sys.stdout  +:=  a web page displaying the history
              from that database requested by those arguments and
              using that taxonomy
        else ->
          sys.stdout  +:=  an error web page ]
    '''

Error handling at every level below here is handled by raising a lib.ScriptError exception containing a description of the problem.

    #-- 1
    try:

First we check that the form arguments are valid. If they aren't, see Section 10.6, “fullErrorPage()”.

        #-- 1.1
        # [ if the CGI arguments are valid ->
        #     HistArgs()  :=  the HistArgs singleton representing those
        #                 arguments
        #   else -> raise lib.ScriptError ]
        HistArgs()

We'll need access to the CBC database. See Section 16, “openDatabase(): Open the CBC database”.

        #-- 1.2
        # [ if (the pycbc database is available) and
        #   (PASS_FILE names a readable file containing the pycbc
        #   database password) and
        #       db  :=  that database as a pycbc.CBCDatabase instance
        #   else -> raise lib.ScriptError ]
        try:
            db = lib.openDatabase()
        except IOError, x:
            raise lib.ScriptError("Can't open the CBC database: "
                "%s" % str(x))

At this point we can pull the Circle records out of the database that correspond to the requested circles in HistArgs().

        #-- 1.3
        # [ if all the circle centers in HistArgs().latLonList correspond
        #   to circles in db ->
        #     circleList  :=  a list of CBCDatabase.Circle instances
        #         representing those circles, sorted by lat-lon
        #   else -> raise lib.ScriptError ]
        circleList = findCircles(db)

Next, we'll need access to the taxonomy authority file.

        #-- 1.4
        # [ if xnomo3's taxonomic authority file is readable and
        #   valid ->
        #     txny  :=  an xnomo3.Txny instance representing a
        #               classification of birds
        #   else ->
        #     sys.stdout  +:=  an error page
        #     stop execution ]
        try:
            txny = xnomo3.Txny()
        except IOError, x:
            raise lib.ScriptError("Can't open the taxonomic "
                "authority file: %s" % str(x))

For the history research phase, see Section 10.8, “hist.cgi: findHistory(): Pull the effort and census records”. The object returned is large and complex and takes up most of the memory.

        #-- 1.5
        # [ if none of the circles in circleList have effort in db
        #   for the years selected by Args() ->
        #     raise lib.ScriptError
        #   else ->
        #     cbcHist  :=  a lib.CbcHist instance representing all
        #         effort and census data for those circles from db ]
        cbcHist = findHistory(db, txny, circleList)

There are two major routes for output.

        #-- 1.6
        # [ if HistArgs().pdf ->
        #     if PDF_CONVERTER is available ->
        #         sys.stdout  +:=  an HTTP response containing the
        #             report requested by HistArgs() using db and
        #             txny, in PDF format
        #     else -> raise lib.ScriptError
        #   else ->
        #     sys.stdout  +:= the report requested by HistArgs() using
        #         db and txny, as an XHTML page ]
        if HistArgs().pdf:
            buildPdf(db, txny, circleList, cbcHist)
        else:
            buildXhtml(db, txny, circleList, cbcHist)

All errors are handled by Section 10.6, “fullErrorPage()”.

    #-- 2
    except lib.ScriptError, x:
        fullErrorPage(x)