diff --git a/generate/template/astronomy.py b/generate/template/astronomy.py index 03c715dd..eada36b1 100644 --- a/generate/template/astronomy.py +++ b/generate/template/astronomy.py @@ -157,26 +157,48 @@ _PlanetOrbitalPeriod = [ ] class Error(Exception): + """Indicates an error in an astronomical calculation.""" def __init__(self, message): Exception.__init__(self, message) class EarthNotAllowedError(Error): + """The Earth is not allowed as the celestial body in this calculation.""" def __init__(self): Error.__init__(self, 'The Earth is not allowed as the body.') class InvalidBodyError(Error): + """The celestial body is not allowed for this calculation.""" def __init__(self): Error.__init__(self, 'Invalid astronomical body.') class BadVectorError(Error): + """A vector magnitude is too small to have a direction in space.""" def __init__(self): Error.__init__(self, 'Vector is too small to have a direction.') class InternalError(Error): + """An internal error occured that should be reported as a bug. + + Indicates an unexpected and unrecoverable condition occurred. + If you encounter this error using Astronomy Engine, it would be very + helpful to report it at the [Issues](https://github.com/cosinekitty/astronomy/issues) + page on GitHub. Please include a copy of the stack trace, along with a description + of how to reproduce the error. This will help improve the quality of + Astronomy Engine for everyone! (Thank you in advance from the author.) + """ def __init__(self): Error.__init__(self, 'Internal error - please report issue at https://github.com/cosinekitty/astronomy/issues') class NoConvergeError(Error): + """A numeric solver did not converge. + + Indicates that there was a failure of a numeric solver to converge. + If you encounter this error using Astronomy Engine, it would be very + helpful to report it at the [Issues](https://github.com/cosinekitty/astronomy/issues) + page on GitHub. Please include a copy of the stack trace, along with a description + of how to reproduce the error. This will help improve the quality of + Astronomy Engine for everyone! (Thank you in advance from the author.) + """ def __init__(self): Error.__init__(self, 'Numeric solver did not converge - please report issue at https://github.com/cosinekitty/astronomy/issues') @@ -472,7 +494,7 @@ def _vector2radec(pos): if xyproj == 0.0: if pos[2] == 0.0: # Indeterminate coordinates: pos vector has zero length. - raise Error('Cannot convert vector to polar coordinates') + raise BadVectorError() ra = 0.0 if pos[2] < 0.0: dec = -90.0 diff --git a/pydown/pydown.py b/pydown/pydown.py index f5b80c01..47c1dce9 100755 --- a/pydown/pydown.py +++ b/pydown/pydown.py @@ -197,13 +197,27 @@ def MdEnumType(c): md += '---\n' md += '\n' md += '\n'.format(c.__name__) - md += '### ' + c.__name__ + '\n' + md += '### enum ' + c.__name__ + '\n' info = DocInfo(doc) info.VerifyEnum(set(c.__members__)) md += info.Markdown() md += '\n' return md +def MdErrType(c): + md = '' + doc = inspect.getdoc(c) + if doc: + md += '\n' + md += '---\n' + md += '\n' + md += '\n'.format(c.__name__) + md += '### ' + c.__name__ + '\n' + info = DocInfo(doc) + md += info.Markdown() + md += '\n' + return md + def Markdown(module): md = '' funclist = [] @@ -242,14 +256,13 @@ def Markdown(module): for c in enumlist: md += MdEnumType(c) - if False: # not yet ready to generate Markdown for error types - md += '---\n' - md += '\n' - md += '\n' - md += '## Error Types\n' - md += '\n' - for c in errlist: - md += MdErrType(c) + md += '---\n' + md += '\n' + md += '\n' + md += '## Error Types\n' + md += '\n' + for c in errlist: + md += MdErrType(c) md += '---\n' md += '\n' diff --git a/source/python/README.md b/source/python/README.md index 6b5a0d08..176c4daa 100644 --- a/source/python/README.md +++ b/source/python/README.md @@ -51,7 +51,7 @@ dates and times represented by `Time` objects. --- -### ApsisKind +### enum ApsisKind **Represents whether a satellite is at a closest or farthest point in its orbit.** @@ -72,7 +72,7 @@ two cases applies to a particular apsis event. --- -### Body +### enum Body **The celestial bodies supported by Astronomy Engine calculations.** @@ -96,7 +96,7 @@ two cases applies to a particular apsis event. --- -### Direction +### enum Direction **Indicates whether a body is rising above or setting below the horizon.** @@ -115,7 +115,7 @@ and `Direction.Set` is used to find sunset times. --- -### Refraction +### enum Refraction **Selects if/how to correct for atmospheric refraction.** @@ -131,6 +131,91 @@ as seen by an observer on the surface of the Earth. | `JplHorizons` | Used only for compatibility testing with JPL Horizons online tool. | +--- + + +## Error Types + + +--- + + +### BadVectorError + +A vector magnitude is too small to have a direction in space. + + + + + +--- + + +### EarthNotAllowedError + +The Earth is not allowed as the celestial body in this calculation. + + + + + +--- + + +### Error + +Indicates an error in an astronomical calculation. + + + + + +--- + + +### InternalError + +**An internal error occured that should be reported as a bug.** + +Indicates an unexpected and unrecoverable condition occurred. +If you encounter this error using Astronomy Engine, it would be very +helpful to report it at the [Issues](https://github.com/cosinekitty/astronomy/issues) +page on GitHub. Please include a copy of the stack trace, along with a description +of how to reproduce the error. This will help improve the quality of +Astronomy Engine for everyone! (Thank you in advance from the author.) + + + + + +--- + + +### InvalidBodyError + +The celestial body is not allowed for this calculation. + + + + + +--- + + +### NoConvergeError + +**A numeric solver did not converge.** + +Indicates that there was a failure of a numeric solver to converge. +If you encounter this error using Astronomy Engine, it would be very +helpful to report it at the [Issues](https://github.com/cosinekitty/astronomy/issues) +page on GitHub. Please include a copy of the stack trace, along with a description +of how to reproduce the error. This will help improve the quality of +Astronomy Engine for everyone! (Thank you in advance from the author.) + + + + --- diff --git a/source/python/astronomy.py b/source/python/astronomy.py index a45b2775..f812ba36 100644 --- a/source/python/astronomy.py +++ b/source/python/astronomy.py @@ -157,26 +157,48 @@ _PlanetOrbitalPeriod = [ ] class Error(Exception): + """Indicates an error in an astronomical calculation.""" def __init__(self, message): Exception.__init__(self, message) class EarthNotAllowedError(Error): + """The Earth is not allowed as the celestial body in this calculation.""" def __init__(self): Error.__init__(self, 'The Earth is not allowed as the body.') class InvalidBodyError(Error): + """The celestial body is not allowed for this calculation.""" def __init__(self): Error.__init__(self, 'Invalid astronomical body.') class BadVectorError(Error): + """A vector magnitude is too small to have a direction in space.""" def __init__(self): Error.__init__(self, 'Vector is too small to have a direction.') class InternalError(Error): + """An internal error occured that should be reported as a bug. + + Indicates an unexpected and unrecoverable condition occurred. + If you encounter this error using Astronomy Engine, it would be very + helpful to report it at the [Issues](https://github.com/cosinekitty/astronomy/issues) + page on GitHub. Please include a copy of the stack trace, along with a description + of how to reproduce the error. This will help improve the quality of + Astronomy Engine for everyone! (Thank you in advance from the author.) + """ def __init__(self): Error.__init__(self, 'Internal error - please report issue at https://github.com/cosinekitty/astronomy/issues') class NoConvergeError(Error): + """A numeric solver did not converge. + + Indicates that there was a failure of a numeric solver to converge. + If you encounter this error using Astronomy Engine, it would be very + helpful to report it at the [Issues](https://github.com/cosinekitty/astronomy/issues) + page on GitHub. Please include a copy of the stack trace, along with a description + of how to reproduce the error. This will help improve the quality of + Astronomy Engine for everyone! (Thank you in advance from the author.) + """ def __init__(self): Error.__init__(self, 'Numeric solver did not converge - please report issue at https://github.com/cosinekitty/astronomy/issues') @@ -1099,7 +1121,7 @@ def _vector2radec(pos): if xyproj == 0.0: if pos[2] == 0.0: # Indeterminate coordinates: pos vector has zero length. - raise Error('Cannot convert vector to polar coordinates') + raise BadVectorError() ra = 0.0 if pos[2] < 0.0: dec = -90.0