IBP banding data system: Internal maintenance specification

This method takes care of the logic of adding a new station (and possibly also location) to the internal dictionaries. It is a service routine designed to be used by the various concrete .readLine() methods in derived classes.

# - - -   B a s e S t a t i o n S e t . a d d S t a t i o n   - - -

    def addStation(self, locCode, staNo, staCode, staName):
        '''Add a new line from the stations file.

          [ (locCode is a location code as a string) and
            (staNo is a station number as a string) and
            (staCode is an alphabetic station code as a string) and
            (staName is the station name as a string) ->
              if locCode matches a key in self.locCodeMap, case
              insensitive ->
                corresponding value  +:=  a new Station made
                    from staNo, staCode, and staName
              else if the corresponding value already contains
              a station whose number matches staNo ->
                raise IOError
              else ->
                self.locCodeMap[locCode.upper()]  :=  a new
                    Location made from locCode, containing a
                    new Station made from staNo, staCode, and
                    staName ]
        '''

First, we uppercase locCode to get the proper key in self.locCodeMap.

        #-- 1 --
        locKey = locCode.upper()

Next, we check to see if this is a new location, and if so, create a new Location object. In any case we set loc to the Location object, whether new or existing.

        #-- 2 --
        # [ if locKey is a key in self.locCodeMap ->
        #     loc  :=  corresponding value
        #   else ->
        #     loc  :=  a new Location object made from locKey
        #     self.locCodeMap[locKey]  :=  that Location object ]
        try:
            loc = self.locCodeMap[locKey]
        except KeyError:
            loc = self.locCodeMap[locKey] = Location(locCode)

Next, we check to see that the new staCode is not duplicated in that location. Station codes can be duplicated in the file, so long as they are in different locations. See Section 9.3, “Location.lookupStaCode()”.

        #-- 3 --
        # [ loc is a Location ->
        #     if loc has a station with code staCode ->
        #       raise IOError
        #     else -> I ]
        try:
            oldSta = loc.lookupStaCode(staCode)
            raise IOError("Station code %s duplicates an "
                "existing station, %s." %
                (staCode, oldSta))
        except KeyError:
            pass

Now it's time to make a new Station object and add it to loc. See Section 9.2, “Location.addStation(): Add a new station to a location”.

        #-- 4 --
        # [ loc  +:=  a new Station object made from staNo,
        #       staCode, and staName ]
        sta = Station(loc, staNo, staName, staCode)
        loc.addStation(sta)

One thing remains: to check for duplicate station numbers in self, and add the station to self.staNoMap.

        #-- 5 --
        # [ if staNo is a key in self.staNoMap ->
        #     raise IOError
        #   else ->
        #     self.staNoMap[staNo] = sta ]
        try:
            oldSta = self.staNoMap[staNo]
            raise IOError("Station number %s duplicates an "
                "existing station, %s." %
                (staNo, oldSta))
        except KeyError:
            self.staNoMap[staNo] = sta