This class is an interface for finding all the month files in a tree of data files as described in the specification.
# - - - - - 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:
State/Invariants: ._monthList: [ list of months as "YYYY-MM" representing data files whose names match "YYYY/YYYY-MM.xml", in ascending order ] '''
# - - - 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
#-- 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
#-- 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()