webstats.py 4.0: Internal Maintenance Specification

This function builds one of the letter pages, showing links to all personal accounts that start with a given letter. It also builds all the access reports for personal accounts whose names start with that letter.

# - - -   b u i l d L e t t e r

def buildLetter ( letter, letterWebPath, accessSummary ):
    '''Build one letter page and all its personal pages.

      [ (letter is a one-character string) and
        (letterWebPath is a WebPath instance) and
        (accessSummary is an Accesssummary instance) ->
          letter-page for (letter) from accessSummary  := 
              letter-content for (letter)
          personal-reports for accounts in accessSummary that start
              with (letter) :=  personal-content for those accounts ]
    '''

The first order of business is to start a new TCCPage instance to hold the letter page. See Section 6.4, “Constants for HTML generation” and Section 6.5, “Report label text”. On that page, the content has only one main element: a bullet list (ul element) under which each bullet will be a link.

    #-- 1 --
    # [ letterPage  :=  a new tccpage2.TCCPage instance using
    #       the URL from letterWebPath ]
    pageTitle  =  LETTER_PAGE_TITLE % (NMT_WEB_PATH.url, letter)
    letterPage  =  tccpage2.TCCPage ( pageTitle, LEAF_NAV_LINKS,
                                      url=letterWebPath.url )

    #-- 2 --
    # [ letterPage.content  +:=  a new 'ul' element ]
    ul  =  et.SubElement ( letterPage.content, 'ul' )

To find the complete set of usernames that start with this letter, we'll need the accessSummary.genPersonals() method; see Section 23, “class AccessSummary: Principal data structure”. This method generates all the usernames that start with a given letter, in alphabetical order. See Section 19, “addPersonalReport(): Generate links and access report for one personal account”.

    #-- 3 --
    # [ ul  +:=  'li' elements containing links to personal-report
    #            pages for each personal name in accessSummary
    #            that starts with (letter)
    #   personal-reports for accounts in accessSummary that start
    #   with (letter)  :=  personal-content for those accounts ]
    for userName in accessSummary.genPersonals(letter):
        #-- 3 body --
        # [ ul  +:=  an 'li' element containing a link to a
        #            personal-report page for (userName)
        #   personal-report for (userName)  :=  personal-content
        #       for (userName) ]
        addPersonalReport ( ul, userName, accessSummary )

Serialize the TCCPage instance to a file whose name is given by letterWebPath.

    #-- 4 --
    # [ file letterWebPath.absPath  :=  letterPage, serialized ]
    try:
        pageFile  =  open ( letterWebPath.absPath, 'w' )
    except IOError, detail:
        fatal ( "Can't open letter page '%s': %s." %
                (letterWebPath.absPath, detail) )
    letterPage.write ( pageFile )
    pageFile.close()