birdnotes.py: Objects to represent bird note files

An instance of this class represents a day-summary element. See the definition of the day-summary pattern in the schema.

The only item required by the constructor is the default location code.

# - - - - -   c l a s s   D a y S u m m a r y

class DaySummary:
    """Represents a day-summary element.

      Exports:
        DaySummary(defaultLocCode):
          [ defaultLocCode is a location code as a string ->
              return a new DaySummary instance with that
              default location code ]
        .defaultLocCode:  [ as passed to constructor ]

Locations are added using the .addLoc() method. The other attributes—route, film and such—are added by storing Narrative instances directly into attributes of the method. This, in the author's opinion, does not break encapsulation because the caller must satisfy the invariant on the attribute.

        .defaultLoc():
          [ return the default location as a Loc instance ]
        .addLoc(loc):
          [ loc is a location as a Loc instance ->
              if self has no location with the same code ->
                self  :=  self with that location added
              else -> raise KeyError ]
        .lookupLoc(locCode):
          [ locCode is a location code as a string ->
              if locCode is defined in self (case-sensitive) ->
                return that location as a Loc instance
              else -> raise KeyError ]
        .genLocs():
          [ generate the locations in self as a sequence of
            Loc instances in ascending order by code ]
        .route:
          [ if self has a route description ->
              that description as a Narrative instance
            else -> None ]
        .weather:
          [ if self has a weather description ->
              that description as a Narrative instance
            else -> None ]
        .missed:
          [ if self has a missed-species description ->
              that description as a Narrative instance
            else -> None ]
        .film:
          [ if self has a film description ->
              that description as a Narrative instance
            else -> None ]
        .notes:
          [ if self has general notes ->
              those notes as a Narrative instance
            else -> None ]

The class has the usual methods for reading and writing XML.

        DaySummary.readNode(node):  # Static method
          [ node is an et.Element ->
              if node conforms to birdnotes.rnc ->
                return a new DaySummaryclass instance that
                represents that node
              else -> raise IOError ]
        .writeNode(parent):
          [ parent is an et.Element ->
              parent  :=  parent with a new et.Element added
                          representing self
              return that new et.Element ]       

These additional state items are used to manage the content.

      State/Invariants:
        ._locCodeMap:
          [ a dictionary whose values are the locations in self
            as Loc instances, and each the corresponding key is
            the location code ]
    """

# - - -   D a y S u m m a r y . _ _ i n i t _ _

    def __init__(self, defaultLocCode):
        """Constructor
        """
        self.defaultLocCode = defaultLocCode
        self.route = None
        self.weather = None
        self.missed = None
        self.film = None
        self.notes = None
        self._locCodeMap = {}