webstats.py 4.0: Internal Maintenance Specification

# - - -   i n p u t P h a s e

def inputPhase(cutoffTime, now):
    '''Read all the access logs and return an AccessSummary.

      [ (access-logs are readable) and
        (cutoffTime is the start of the report interval as a
        datetime.datetime) and
        (now is the end of the report interval as a
        datetime.datetime) ->
          return a new AccessSummary containing all the relevant
          records from those logs ]
    '''

We'll always want to read the current access log, whose name is given by ACCESS_LOG_PATH. In theory we will also want to read N_OLDER_LOGS older, rotated log files, whose names are the same as the current log with extensions “.1”, “.2”, and so on. (All these constants are defined in Section 6.2, “Input file paths”.) However, the absence of one or all of these older files is not considered an error, because the server may not have been in operation for the full report period.

The first order of business is to create the AccessSummary instance that will accumulate the access data, summarized in various ways. See Section 23, “class AccessSummary: Principal data structure”.

    #-- 1 --
    # [ accessSummary  :=  an AccessSummary for the interval
    #       between cutoffTime and now ]
    accessSummary  =  AccessSummary ( cutoffTime, now )

If the current access log doesn't exist or isn't readable, that's a fatal error. There should always be a current access log.

    #-- 2 --
    # [ if the file at ACCESS_LOG_PATH is readable ->
    #     accessSummary  :=  accessSummary with valid records
    #                        added from that file
    #     sys.stderr  +:=  messages about lines in that file
    #         that aren't valid, if any
    #   else ->
    #     sys.stderr  +:=  error message
    #     stop execution ]
    try:
        readLogFile ( accessSummary, ACCESS_LOG_PATH )
    except IOError, detail:
        fatal ( "Can't read the current access log file '%s': %s" %
                (ACCESS_LOG_PATH, detail) )

Now add the data from any older logs that exist.

    #-- 3 --
    # [ if any of the N_OLDER_LOGS files whose names are
    #   (ACCESS_LOG_PATH+"."+n), n="1", "2", ... are readable ->
    #     accessSummary  :=  accessSummary with valid records
    #                        added from those files
    #     sys.stderr  +:=  messages about lines in that file
    #         that aren't valid, if any ]
    for logNo in range(1, N_OLDER_LOGS + 1):
        logName  =  "%s.%d" % (ACCESS_LOG_PATH, logNo)
        try:
            readLogFile ( accessSummary, logName )
        except IOError,detail:
            pass

    #-- 4 --
    return accessSummary