Christmas Bird Count history report system

The purpose of this function is to create the report in XSL-FO form, write that to a temporary file, and then convert it to PDF form in another temporary file, and return the name of the PDF file to the caller.

At this writing (May 2012), the infohost.nmt.edu server, where this script will run, was only up to Python 2.4, and did not have either xep or fop to convert XSL-FO to PDF form. However, under /u/john/bin/fop there is an ancient fop install that will serve. Possible workaround: run xep on a different server.

# - - -   f o P h a s e

def foPhase(db, txny, circleList, cbcHist):
    '''Generate XSL Formatting Objects and convert to PDF.

      [ (db is a pycbc.CBCDatabase instance) and
        (txny is an xnomo3.Txny instance) and
        (foFile is a writeable file) ->
          if HistArgs() is consistent with db and txny ->
            a temp file +:=  the report requested by HistArgs() using
                  db and txny, in PDF format
            return the name of that temp file
          else ->
            raise lib.ScriptError ]
    '''

Relevant constants: Section 10.4.5, “TEMP_DIR”; Section 10.4.3, “FO_EXTENSION”; Section 10.4.4, “PDF_EXTENSION”. Relevant documentation: the Python tempfile module.

    #-- 1
    # [ foFile  :=  a writeable temporary file in directory
    #       TEMP_DIR whose name ends in FO_EXTENSION
    #   foFile  :=  the name of that file]
    #   pdfName  :=  the name of that file, with its extension
    #                changed to PDF_EXTENSION ]
    foFile = tempfile.NamedTemporaryFile(mode='w',
        dir=TEMP_DIR, suffix=FO_EXTENSION)
    foName = foFile.name
#--
# The code below is a workraound because the current server (at
# Python 2.4) doesn't have delete=False.
#--
    foFile.close()
    foFile = open(foName, 'w')
    pathPart, discard = os.path.splitext(foName)
    pdfName = pathPart+PDF_EXTENSION

See Section 10.24, “hist.cgi: foWrite()” for the logic that generates the XSL-FO for the report.

    #-- 2
    # [ if HistArgs() is consistent with db and txny ->
    #     foFile  +:=  the report requested by HistArgs() using
    #         db and txny, in XSL-FO format, closed
    #   else -> raise lib.ScriptError ]
    foWrite(db, txny, foFile, circleList, cbcHist)

The original plan for compiling the .fo file into .pdf form was to use Python's os.system() call to run either xep or fop in a subshell, but this is not allowed on the current host, for obscure reasons.

The current workaround is to use an undocumented XML-RPC server that runs on a different host that has a working xep install. Sometime soon the Web server will be upgraded and this will likely change. See Section 10.4.7, “XEPPER_URL” and Section 10.36, “hist.cgi: convertToPdf”.

    #-- 3
    # [ if XEPPER_URL is running the xepper server and it can convert
    #   foFile to PDF ->
    #     that PDF  :=  that file, so converted
    #   else -> raise lib.ScriptError ]
    convertToPdf(foName)

    #-- 4
    foFile.close()
    os.remove(foName)
    return pdfName