Christmas Bird Count history report system

# - - - - -   m a i n

def main():
    '''Regional index page CGI script: main logic.

      [ if (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 that allows the user to select
              history reports from the set of circles in the CBC
              database selected by those CGI arguments
        else ->
          sys.stdout  +:=  an error web page ]
    '''

The main logic has three parts: set up an empty page; fill it with content, or with an error message if there is any problem; then serialize the page to the output. As with Section 6.4, “pickaregion.cgi: main()”, the middle part is wrapped in a try-except block so that any terminal problem need only raise a ScriptError (see Section 15, “class ScriptError: Our exception”. The page is created by Section 8.4, “regx.cgi: buildEmptyPage(): Set up an empty page”.

    #-- 1
    # [ sys.stdout  +:=  CGI header for HTML output
    #   page  :=  a tp.TCCPage instance ]
    print "Content-type: text/html"
    print
    page = buildEmptyPage()

    #-- 2
    # [ if (PASS_FILE names a readable file containing the CBC
    #   database password) and (the pycbc database is available) and
    #   (the CGI arguments are valid and consistent with that
    #   database) ->
    #     page  :=  page modified to display a form for creating a
    #         history report for circles from that database selected
    #         by the CGI arguments
    #   else ->
    #     page  :=  page modified to display an error page ]
    try:
        #-- 2.1
        # [ if  (PASS_FILE names a readable file containing the
        #   CBC database password) and (the pycbc database is
        #   available) ->
        #     db  :=  that database as a pycbc.CBCDatabase instance
        #   else -> raise ScriptError ]
        try:
            db = lib.openDatabase()
        except IOError, x:
            raise lib.ScriptError("Can't access the CBC database: %s" %
                             str(x))

Because the CGI arguments are referred to in so many places, and because by definition there will be only one set, we use the Singleton design pattern as implemented by the Singleton class from the author's standard logscan.py library. Briefly, the first time the RegArgs() constructor is invoked, all the CGI arguments are checked and digested into attributes of an instance that is returned to the caller (unless there is a problem, in which case that constructor raises a ScriptError). Any invocation of the constructor after that point returns the same instance, so we don't have to pass the instance everywhere explicitly. (Okay, so it's a global variable, but Erich Gamma's gang has blessed it.)

        #-- 2.2
        # [ if the CGI arguments are valid ->
        #     RegArgs()  :=  the RegArgs singleton representing those
        #                 arguments
        #   else -> raise ScriptError ]
        RegArgs()

See Section 8.5, “regx.cgi: buildRegionsForm: Build the regional index form” for the logic that builds the page when everything works, and Section 17, “buildErrorPage()” for error page generation.

        #-- 2.3
        # [ if RegArgs() is consistent with db ->
        #     page  :=  page modified to display a page that allows
        #         the user to select history reports from the set of
        #         circles in db selected by RegArgs()
        #   else -> raise ScriptError ]
        buildRegionsForm(page, db)
    except lib.ScriptError, x:
        #-- 2x
        lib.buildErrorPage(page, x)

    #-- 3
    # [ sys.stdout  +:=  page, serialized as XHTML ]
    lib.addDocLink(page.content)
    page.write(sys.stdout)