Christmas Bird Count history report system

# - - -   H i s t A r g s . _ f i n d L a t L o n s

    def _findLatLons(self, form):
        '''Locate which circle(s) the user wants in the report.

          [ form is a cgi.FieldStorage instance ->
              if (form has a key ALL) and
              (form has at least one key LAT_LON) and
              (the LAT_LON values are valid "ddmm-DDDMM" coordinates) ->
                 return those coordinates as a list of tuples
                 ("ddmm", "DDDMM")
              else if (form has a key whose name starts with
              regform.S_ and ending with valid
              "ddmm-DDDMM" coordinates) ->
                 return a list containing one tuple of the form
                 ("ddmm", "DDDMM") made from that ending
              else -> raise lib.ScriptError ]
        '''

The first step is to check whether the user clicked on the Report on selected circles submit button. If so, see Section 10.40, “HistArgs._allSelected(): Report on selected circles”.

        #-- 1
        # [ if form has a key ALL ->
        #     if (form has at least one key LAT_LON) and
        #     (the LAT_LON values are "ddmm-DDDMM" coordinates) ->
        #       return those coordinates as a list of tuples
        #       ("ddmm", "DDDMM")
        #     else -> raise ScriptError
        #   else -> I ]
        if regform.ALL in form:
            return self._allSelected(form)

The other way we get here is when the user clicks one of the submit buttons in a primary index entry. In that case, the form should have exactly one key whose prefix is S_, and the rest of that key should have the form ddmm-DDDMM.

        #-- 2
        # [ keyList  :=  list of keys in form that start with
        #                regform.S_ ]
        keyList = [ k
                    for k in form.keys()
                    if k.startswith(regform.S_) ]

        #-- 3
        # [ if keyList has exactly one element ->
        #     keyTail  :=  the part of that element after
        #                  regform.S_
        #   else -> raise ScriptError ]
        if len(keyList) == 1:
            keyTail = keyList[0][len(regform.S_):]
        elif len(keyList) == 0:
            raise lib.ScriptError("Invalid arguments, no submit "
                "buttons found.")
        elif len(keyList) > 1:
            raise lib.ScriptError("Invalid arguments, multiple submit "
                "buttons found.")

There is one more check: the keyTail must have the form ddmm-DDDMM; see Section 10.41, “HistArgs._checkLatLon(): Check one lat-lon argument”.

        #-- 4
        # [ if keyTail is a valid circle center in the form
        #   "ddmm-DDDMM" ->
        #     return a list containing that center as a tuple
        #     [("ddmm", "DDDMM")]
        #   else -> raise lib.ScriptError ]
        return [self._checkLatLon(keyTail)]