sidereal.py: Internal maintenance specification

# - - -   c h e c k A l t A z

def checkAltAz ( rawAltAz ):
    """Check and convert a pair of horizon coordinates.

      [ rawAltAz is a string ->
          if rawAltAz is a valid set of horizon coordinates ->
            return those coordinates as a sidereal.AltAz instance
          else ->
            sys.stderr  +:=  error message
            stop execution ]
    """

This function is quite similar to Section 4.7, “checkRADec: Check equatorial coordinates”: it looks for the plus or minus sign separating the azimuth from the altitude, using SIGN_PAT. Then the two parts are processed by Section 9.14, “parseAngle(): Convert an external angle string”.

    #-- 1 --
    # [ if rawAltAz contains either a '+' or a '-' ->
    #     m  :=  a re.match instance describing the first matching
    #            character
    #   else ->
    #     sys.stderr  +:=  error message
    #     stop execution ]
    m  =  SIGN_PAT.search ( rawAltAz )
    if  m is None:
        usage ( "Equatorial coordinates must be separated by "
                "'+' or '-'." )
    #-- 2 --
    # [ rawAz  :=  rawAltAz up to the match described by m
    #   sign  :=  characters matched by m
    #   rawAlt  :=  rawAltAz past the match described by m ]
    rawAz  =  rawAltAz[:m.start()]
    sign  =  m.group()
    rawAlt  =  rawAltAz[m.end():]

    #-- 3 --
    # [ if rawAz is a valid angle ->
    #     az  :=  that angle as radians
    #   else ->
    #     sys.stderr  +:=  error message
    #     stop execution ]
    try:
        az  =  sidereal.parseAngle ( rawAz )
    except SyntaxError, detail:
        usage ( "Azimuth '%s' should have the form "
                "'NNNd[NNm[NN.NNNs]]'." % rawAz )

    #-- 4 --
    # [ if rawAlt is a valid angle ->
    #     alt  :=  that angle as radians
    #   else ->
    #     sys.stderr  +:=  error message
    #     stop execution ]
    try:
        absAlt  =  sidereal.parseAngle ( rawAlt )
    except SyntaxError, detail:
        usage ( "Altitude '%s' should have the form "
                "'NNd[NNm[NN.NNNs]]'." % rawAlt )

    #-- 5 --
    if  sign == '-':   alt  =  - absAlt
    else:              alt  =  absAlt

    #-- 6 --
    return  sidereal.AltAz ( alt, az )