Next / Previous / Contents / Shipman's homepage

20. class BirdNoteTree

This class is an interface for finding all the month files in a tree of data files as described in the specification.

birdnotes.py
# - - - - -   c l a s s   B i r d N o t e T r e e

class BirdNoteTree(object):
    '''Represents a complete tree of monthly files.

      Exports:
        BirdNoteTree(txny, rootDir='.'):
          [ (txny is a taxonomy as a Txny instance) and
            (rootDir is the path name of a data file tree) ->
              if rootDir and its subdirectories can be
              examined ->
                return a new BirdNoteTree representing the data
                files rooted in rootDir with names of the form
                "YYYY/YYYY-MM.xml"
              else -> raise IOError ]
        .txny:        [ as passed to constructor, read-only ]
        .rootDir:     [ as passed to constructor, read-only ]
        .genMonths(startDate=None, endDate=None, startSeason=None,
                   endSeason=None):
          [ (startDate is an inclusive starting date as a
            datetime.date, or None for no starting cutoff) and
            (endDate is an inclusive ending date as a
            datetime.date or None for no ending cutoff) and
            (startSeason is an inclusive starting month and day
            as a datetime.date or None for no starting cutoff) and
            (endSeason is an inclusive ending month and day
            as a datetime.date or None for no ending cutoff) ->
              if all data files in self are readable and
              valid against self.txny ->
                generate a sequence of BirdNoteSet instances
                representing files that may contain dates in
                the range [startDate,endDate] and days of the
                year in the range [startSeason, endSeason] ]

Internals to this class:

birdnotes.py
      State/Invariants:
        ._monthList:
          [ list of months as "YYYY-MM" representing data files
            whose names match "YYYY/YYYY-MM.xml", in ascending
            order ]
    '''

20.1. BirdNoteTree.__init__(): Constructor

birdnotes.py
# - - -   B i r d N o t e T r e e . _ _ i n i t _ _

    def __init__(self, txny, rootDir='.'):
        '''Constructor
        '''

We don't read every data file at instantiation. We only find all the file names that look like yearly directories; see Section 5.2, “YEAR_PAT: Year directory name pattern”.

birdnotes.py
        #-- 1 --
        self.txny = txny
        self.rootDir = rootDir
        self._monthList = []

        #-- 2 --
        # [ if rootDir can be read ->
        #     yyyyList  :=  list of subdirectories of rootDir
        #                   with four-digit names, sorted
        #   else -> raise IOError ]
        yyyyList = sorted([ dirName
                              for dirName in os.listdir(rootDir)
                              if YEAR_PAT.match(dirName) ] )

For the regular expression that matches month file names, see Section 5.3, “YYYY_MM_XML_PAT: Month file name pattern”.

birdnotes.py
        #-- 3 --
        # [ if all subdirectories of self.rootDir whose names are in
        #   yyyyList can be read ->
        #     self._monthList  +:=  the "YYYY-MM" part of the
        #         names of files in those subdirectories whose names
        #         match YYYY_MM_XML_PAT
        #   else -> raise IOError ]
        for yyyy in yyyyList:
            #-- 3 body --
            # [ if subdirectory (yyyy) of self.rootDir can be read ->
            #     self._monthList  +:=  the "YYYY-MM" part of
            #         the names of files in that subdirectory
            #         whose names match YYYY_MM_XML_PAT
            #   else -> raise IOError ]
            self._findMonths(yyyy)

        #-- 4 --
        # [ self._monthList  :=  self._monthList sorted into
        #                         ascending order ]
        self._monthList.sort()