webstats.py 4.0: Internal Maintenance Specification

# - - -   b u i l d H i t P a r a d e

def buildHitParade ( parent, accessSummary ):
    '''Build the hit parade page and the index page link to it.

      [ (parent is an et.Element) and
        (accessSummary is an AccessSummary) ->
          indexPage  +:=  (link to hit-parade-page made from
                          accessSummary) 
          hit-parade-page  :=  hits-content(accessSummary) ]
    '''

The link from the index to the hit parade page is the easy part.

    #-- 1 --
    # [ parent  +:=  a new paragraph containing a link to
    #       BY_HITS_WEB_PATH ]
    parent.append (
      E.p (
        E.a ( "Access report by number of hits",              
              href=BY_HITS_WEB_PATH.url ) ) )

Next we create a new TCCPage instance. For the page title, see Section 6.5, “Report label text”. For the definition of LEAF_NAV_LINKS, see Section 6.4, “Constants for HTML generation”.

    #-- 2 --
    # [ hitsPage  :=  a new tccpage2.TCCPage instance ]
    hitsPage  =  tccpage2.TCCPage ( BY_HITS_TITLE, LEAF_NAV_LINKS,
                                    url=BY_HITS_WEB_PATH.url )

For the routine that builds the skeleton of an access report table, see Section 13, “accessReport(): Start a new access report table”, which returns the tbody element under which detail rows will be added.

    #-- 3 --
    # [ hitsPage  +:=  a new access report as a 'table' element
    #   tbody  :=  the 'tbody' element of that table ]
    tbody  =  accessReport ( hitsPage.content )

Now comes the gigantic sort. The method described in Section 39, “AccessSummary.genByHits(): Generate the hit parade” conveniently generates what we need as a stream of HitCount instances in the correct order. All we have to do is make them into access table rows.

    #-- 4 --
    # [ tbody  +:=  access report rows made from HitCount
    #       instances in accessSummary, sorted according to
    #       HitCount.__cmp__ ]
    for hitCount in accessSummary.genByHits():
        if hitCount.nTotal < HITS_CUTOFF:
            break
        accessRow ( tbody, hitCount )

The page is complete; serialize it to a new file, assuming that we can create the file.

    #-- 5 --
    # [ if BY_HITS_WEB_PATH can be opened new for writing ->
    #     that file  +:=  hitsPage, serialized as XHTML
    #   else ->
    #     sys.stderr  +:=  error message
    #     stop execution ]
    try:
        hitsFile  =  open ( BY_HITS_WEB_PATH.absPath, 'w' )
    except IOError, detail:
        fatal ( "Can't open the hit-parade page '%s': %s" %
                (BY_HITS_WEB_PATH.absPath, detail) )
    hitsPage.write ( hitsFile )
    hitsFile.close()