Christmas Bird Count history report system

# - - -   b u i l d C i r c l e

def buildCircle(db, entryList, circle, firstYear, lastYear, isOverlap):
    '''Build all index entries pertaining to one circle center.

      [ (db is a pycbc.CBCData instance) and
        (entryList is a list) and
        (circle is a Circle instance) and
        (firstYear and lastYear are the last year numbers to be
        included, in year-number format) and
        (isOverlap is True iff overlap report desired) ->
          if circle has any effort in the year number range
          [firstYear, lastYear] ->
            entryList  +:=  (a PriIndex instance for the circle's
                current name) + (SecIndex instances for sets of
                efforts under names that have the same center as 
                (circle) but different as-published names) ]
    '''

First we call the class constructor for Section 22, “class PriIndex: Primary regional index entry” to build the primary entry. However, if its .effortList attribute is empty, that means there were no efforts in the range of interest.

    #-- 1
    # [ priEntry  :=  a PriIndex instance for circle (circle)
    #       including efforts from db in year numbers in
    #       [firstYear, lastYear] ]
    priEntry = lib.PriIndex(db, circle, firstYear, lastYear, isOverlap)

    #-- 2
    if len(priEntry.effortList) == 0:
        return

At this point we know that there was at least one effort in the desired year range; add the primary entry to the list. Then append any secondary entries; see Section 8.11, “regx.cgi: addSecondaries(): Generate secondary index entries for one circle”.

    #-- 3
    entryList.append(priEntry)

    #-- 4
    # [ entryList  +:=  SecEntry instances for each group of efforts
    #       with the same center as (circle) but different names ]
    addSecondaries(db, entryList, priEntry, firstYear, lastYear)