sidereal.py: Internal maintenance specification

# - - -   c h e c k R A D e c

def checkRADec ( rawRADec ):
    """Check and convert a pair of equatorial coordinates.

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

A set of equatorial coordinates consists of a quantity in hours, a “+” or “-” sign, and a declination as an angle. So we'll start by finding and saving the sign and breaking the string into its two parts. The .search() method of a precompiled regular expression searches for that pattern anywhere in a string. For SIGN_PAT, see Section 4.3, “Constants”.

    #-- 1 --
    # [ if rawRADec 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 ( rawRADec )
    if  m is None:
        usage ( "Equatorial coordinates must be separated by "
                "'+' or '-'." )
    #-- 2 --
    # [ rawRA  :=  rawRADec up to the match described by m
    #   sign  :=  characters matched by m
    #   rawDec  :=  rawRADec past the match described by m ]
    rawRA  =  rawRADec[:m.start()]
    sign  =  m.group()
    rawDec  =  rawRADec[m.end():]

To convert the raw RA, we'll use Section 9.20, “parseHours(): Convert an external quantity in hours”.

    #-- 3 --
    # [ if rawRA is a valid hours expression ->
    #     ra  :=  rawRA as radians
    #   else ->
    #     sys.stderr  +:=  error message
    #     stop execution ]
    try:
        raHours  =  sidereal.parseHours ( rawRA )
        ra  =  sidereal.hoursToRadians ( raHours )
    except SyntaxError, detail:
        usage ( "Right ascension '%s' should have the form "
                "'NNh[NNm[NN.NNNs]]'." % rawRA )

To convert the raw declination, we'll use Section 9.14, “parseAngle(): Convert an external angle string”.

    #-- 4 --
    # [ if rawDec is a valid angle expression ->
    #     absDec  :=  that angle in radians
    #     sys.stderr  +:=  error message
    #     stop execution ]
    try:
        absDec  =  sidereal.parseAngle ( rawDec )
    except SyntaxError, detail:
        usage ( "Right ascension '%s' should have the form "
                "'NNd[NNm[NN.NNNs]]'." % rawDec )

All that remains is to attach the sign to the declination, wrap both coordinates in an RADec instance, and return it.

    #-- 5 --
    if  sign == '-':   dec  =  - absDec
    else:              dec  =  absDec

    #-- 6 --
    return sidereal.RADec ( ra, dec )