Christmas Bird Count history report system

# - - -   b u i l d H e a d i n g s

def buildHeadings(sox, db):
    '''Output the overall title and repeated circle index entries.

      [ (sox is a sox.Sox instance) and
        (db is a pycbc.CbcDatabase instance) ->
          if the circle centers in HistArgs().latLonList all match circles
          in db ->
            sox  +:=  main title and primary index entries for those
                      circles
            circleList  :=  those circles as a sequence of Circle
                            records
          else -> raise lib.ScriptError ]
    '''

First we look up all the ("ddmm", "DDDMM") tuples that define the centers of the circles of interest. The resulting list is sorted using the Circle class's native comparator, which will order them by name.

    #-- 1
    # [ if all the circle centers in HistArgs().latLonList match circles
    #   in db ->
    #     circleList  :=  a list of the corresponding Circle instances
    #                     from db
    #   else -> raise ScriptError ]
    try:
        circleList = sorted(
          [ db.getCircle(*center)
            for center in HistArgs().latLonList ])
    except KeyError, x:
        raise lib.ScriptError("Unknown circle center: %s" % str(x))

Generation of the primary index entries in straightforward.

    #-- 2
    # [ sox  +:=  primary index entries for the circles in circleList ]
    for circle in circleList:
        #-- 2 body
        # [ sox  +:=  primary index entry for circle, limited by year
        #             range in HistArgs() ]
        priIndex = lib.PriIndex(db, circle,
            firstYear=HistArgs().firstYear,
            lastYear=HistArgs().lastYear)
        priIndex.soxMain(sox)

    #-- 3
    sox.flush()
    return circleList