birdnotes.py: Objects to represent bird note files

An instance of this class defines one locality code used within one day's notes. See the definition of the loc pattern in the schema.

The .text attribute can be passed to the constructor, or added later by direct write to the instance's attribute.

# - - - - -   c l a s s   L o c

class Loc:
    """Represents one location.

      Exports:
        Loc(code, name, text=None):
          [ (code is a locality code as a string) and
            (name is the locality's name as a string) and
            (text is the locality's full description as a string,
            or None) ->
              return a new Loc instance with those values ]
        .code:     [ as passed to constructor, read-only ]
        .name:     [ as passed to constructor, read-only ]
        .text:     [ as passed to constructor, read-write ]

An instance is also a container for any number of GPS waypoints.

        .addGps(gps):
          [ gps is a waypoint as a Gps instance ->
               self  :=  self with gps added ]
        .genGps():
          [ generate the waypoints in self in the order
            they were added ]         

The class has the usual .readNode() and .writeNode() methods.

        Loc.readNode(node):   # Static method
          [ node is an rnc.LOC_N node as an et.Element ->
              return a new Loc instance made from node ]
        .writeNode(parent):
          [ parent is an et.Element ->
              parent  :=  parent with self's content added
                  as a new rnc.LOC_N child element
              return that new child element ]

Internal state:

      State/Invariants:
        ._gpsList:
          [ list of waypoints in self in the order they were
            added, as Gps instances ]
    """

# - - -   L o c . _ _ i n i t _ _

    def __init__(self, code, name, text=None):
        """Constructor for Loc.
        """
        self.code = code
        self.name = name
        self.text = text
        self._gpsList = []