Add __str__ method to classes

[MarkWieczorek]

Squash and Merge summary

Add a __str__ method to the Sphere, Ellipsoid and TriaxialEllipsoid classes that displays information about the realization in more readable way than __repr__. Use a new line character to separate mnultiple references in the realizations. Polish a few of the examples in the docstrings.

---

This PR adds the __str__ method to the three Boule classes. When using print, the output is formatted as

Callisto2024 - Callisto spheroid (2024)
Spheroid:
  Radius: 2410300 m
  GM: 7179292000000.0 m³/s²
  Angular velocity: 4.357108150919352e-06 rad/s
Source:
  Radius, GM: Anderson, J. D., et al. (2001). Shape, mean radius,
  gravity field, and interior structure of Callisto. Icarus, 153(1),
  157–161. https://doi.org/10.1006/icar.2001.6664; Angular velocity:
  Satellites and the Orientation of the Pole of Jupiter, personal
  communication to Horizons/NAIF. Accessed via JPL Solar System
  Dynamics, https://ssd.jpl.nasa.gov, JUP365.

Mars2009 - Mars ellipsoid (2009)
Oblate ellipsoid:
  Semimajor axis: 3395428 m
  Flattening: 0.005227617843759314
  GM: 42828372000000.0 m³/s²
  Angular velocity: 7.0882181e-05 rad/s
Source:
  Ardalan, A. A., Karimi, R., & Grafarend, E. W. (2009). A New Reference
  Equipotential Surface, and Reference Ellipsoid for the Planet Mars.
  Earth, Moon, and Planets, 106, 1-13. doi:10.1007/s11038-009-9342-7

Io2024 - Io equilibrium triaxial ellipsoid (2024)
Triaxial ellipsoid:
  Semimajor axis: 1829700 m
  Semimedium axis: 1819200 m
  Semiminor axis: 1815800 m
  GM: 5959910000000.0 m³/s²
  Angular velocity: 4.125530833185668e-05 rad/s
Source:
  Semi-axis: Thomas, P. C., et al. (1998). The Shape of Io from Galileo
  Limb Measurements. Icarus, 135(1), 175–180.
  https://doi.org/10.1006/icar.1998.5987; GM: Anderson, J. D., et al.
  (2001). Io's gravity field and interior structure. J. Geophys. Res.,
  106, 32963–32969. https://doi.org/10.1029/2000JE001367; Angular
  velocity: R. A. Jacobson (2021), The Orbits of the Regular Jovian
  Satellites and the Orientation of the Pole of Jupiter, personal
  communication to Horizons/NAIF. Accessed via JPL Solar System
  Dynamics, https://ssd.jpl.nasa.gov, JUP365.

Note that I placed the method after all of the properties. I also did not include a dock string. I'm not sure what the best practice is with this method.

Relevant issues/PRs:
Closes #181

[santisoler]

This looks nice @MarkWieczorek! I found a typo on the semimajor axis longitude (and I added a degree symbol to specify the units).

I also added some suggestions to make the outputs of the __str__ to look more similar to the format proposed by @leouieda in #213. Let me know what do you think!

I don't think you should worry about docstrings for this method. I don't think the __str__ method needs a description, so it should be fine to leave it without docstring.

Some of the lines in __str__ are not being tested. We could add some tests for them, but I'm ok if we want to leave them untested (we can still visually verify that the method works as expected).

On a side note, I like the idea of having a dataclass for each reference (as @VascoSch92 suggested), so we could still add the references in the __str__ but without the need to add the full text: we could only return the author's name, year and doi. Alternatively, we could have either a reference as a string or as a list of strings, so we can improve how they are printed. But I think we could work on that after we merge this PR.

[MarkWieczorek]

Here is some progress. First, I didn't implement the "left justified bullet + centered text" as I think it make things look more complex than it needs to be. I'll do whatever people think is best, and this PR isn't quite done yet anyway. There's still room for improvement.

Second, the above changes try to fix the multiple reference issues. I added line breaks in the reference string (which is probably better anyway), and then textwrapped each reference separately. I think this looks fine when multiple references are present, but you could argue that maybe we don't need the hanging indent when only one is present. Here's what it looks like:

Pluto2024 - Pluto spheroid (2024)
Spheroid:
  Radius: 1188300 m
  GM: 869600000000.0 m³/s²
  Angular velocity: 1.1385591834674098e-05 rad/s
Source:
  Radius: Nimmo, et al. (2017). Mean radius and shape of Pluto and
    Charon from New Horizons images. Icarus, 287, 12–29.
    https://doi.org/10.1016/j.icarus.2016.06.027
  GM, angular velocity: Brozović, M., et al. (2015). The orbits and
    masses of satellites of Pluto. Icarus, 246, 317–329.
    https://doi.org/10.1016/j.icarus.2014.03.015

WGS84 - World Geodetic System (1984)
Oblate ellipsoid:
  Semimajor axis: 6378137 m
  Flattening: 0.0033528106647474805
  GM: 398600441800000.0 m³/s²
  Angular velocity: 7.292115e-05 rad/s
Source:
  Hofmann-Wellenhof, B., & Moritz, H. (2006). Physical Geodesy (2nd,
    corr. ed. 2006 edition ed.). Wien; New York: Springer.

VestaTriaxial2017 - Vesta triaxial reference ellipsoid (2017)
Triaxial ellipsoid:
  Semimajor axis: 280413 m
  Semimedium axis: 274572 m
  Semiminor axis: 231253 m
  Semimajor axis longitude: 8.29°
  GM: 17288000000.0 m³/s²
  Angular velocity: 0.0003267 rad/s
Source:
  Karimi, R., Azmoudeh Ardalan, A., & Vasheghani Farahani, S. (2017).
    The size, shape and orientation of the asteroid Vesta based on data
    from the Dawn mission. Earth and Planetary Science Letters, 475,
    71–82. https://doi.org/10.1016/j.epsl.2017.07.033
Comments:
  Geocentric triaxial ellipsoid

I need to think about the code coverage issue. I think that the issue is that the docstring doesn't test "Comments" and a few don't test "References". Perhaps its best just to add these declarations to the doc string.

[MarkWieczorek]

I changed slightly the docstring tests by (1) making the reference shorter, and (2) adding a comment. Here is an example:

    >>> ellipsoid = Ellipsoid(
    ...     name="WGS84",
    ...     long_name="World Geodetic System 1984",
    ...     semimajor_axis=6378137,
    ...     flattening=1 / 298.257223563,
    ...     geocentric_grav_const=3986004.418e8,
    ...     angular_velocity=7292115e-11,
    ...     reference="Hofmann-Wellenhof & Moritz (2006)",
    ...     comments="This is the same as the boule WGS84 ellipsoid.",
    ... )

For sphere, I used the same data as in bl.Moon2015.

However, code-cov (though better) is still placing a warning at the lines if self.reference is not None: and if self.comments is not None:, even though these get used in the doctest. Not sure what to do about that....

[santisoler]

Hi @MarkWieczorek!

Here is some progress. First, I didn't implement the "left justified bullet + centered text" as I think it make things look more complex than it needs to be. I'll do whatever people think is best, and this PR isn't quite done yet anyway. There's still room for improvement.

Sure, no worries! We can keep it simple then. I would add the bullets so it's clear we are listing the attributes that define the ellipsoid. The bullet character I used is an ASCII character, so it'll show fine on any terminal. What do you think?

Second, the above changes try to fix the multiple reference issues. I added line breaks in the reference string (which is probably better anyway), and then textwrapped each reference separately. I think this looks fine when multiple references are present, but you could argue that maybe we don't need the hanging indent when only one is present. Here's what it looks like:

I love the hanging indent. Adding the line break is a nice and simple solution. I'd like to retake the references at some point (different PR), to think if we should use a dataclass or maybe allow to take a collection of references. But for this PR I think the new line character is perfect. I'll just leave one minor comment regarding this (see below).

However, code-cov (though better) is still placing a warning at the lines if self.reference is not None: and if self.comments is not None:, even though these get used in the doctest. Not sure what to do about that....

Codecov is putting a yellow exclamation mark on those lines:

This doesn't mean that those lines are not tested (they are actually being tested in the doctest). But codecov is highlighting them because we don't have any tests that check what happens when the if statement is not True (when comments is None). Basically, it complains because we are only testing one possible scenario. For this particular PR, I think it's ok not to reach 100% coverage for this: we'll still have visual inspection of this method in the documentation pages.

[MarkWieczorek]

Here's with bullets, and with the changes to the line breaks

Pluto2024 - Pluto spheroid (2024)
Spheroid:
  • Radius: 1188300 m
  • GM: 869600000000.0 m³/s²
  • Angular velocity: 1.1385591834674098e-05 rad/s
Source:
  Radius: Nimmo, et al. (2017). Mean radius and shape of Pluto and
    Charon from New Horizons images. Icarus, 287, 12–29.
    https://doi.org/10.1016/j.icarus.2016.06.027
  GM, angular velocity: Brozović, M., et al. (2015). The orbits and
    masses of satellites of Pluto. Icarus, 246, 317–329.
    https://doi.org/10.1016/j.icarus.2014.03.015

WGS84 - World Geodetic System (1984)
Oblate ellipsoid:
  • Semimajor axis: 6378137 m
  • Flattening: 0.0033528106647474805
  • GM: 398600441800000.0 m³/s²
  • Angular velocity: 7.292115e-05 rad/s
Source:
  Hofmann-Wellenhof, B., & Moritz, H. (2006). Physical Geodesy (2nd,
    corr. ed. 2006 edition ed.). Wien; New York: Springer.

VestaTriaxial2017 - Vesta triaxial reference ellipsoid (2017)
Triaxial ellipsoid:
  • Semimajor axis: 280413 m
  • Semimedium axis: 274572 m
  • Semiminor axis: 231253 m
  • Semimajor axis longitude: 8.29°
  • GM: 17288000000.0 m³/s²
  • Angular velocity: 0.0003267 rad/s
Source:
  Karimi, R., Azmoudeh Ardalan, A., & Vasheghani Farahani, S. (2017).
    The size, shape and orientation of the asteroid Vesta based on data
    from the Dawn mission. Earth and Planetary Science Letters, 475,
    71–82. https://doi.org/10.1016/j.epsl.2017.07.033
Comments:
  Geocentric triaxial ellipsoid

[santisoler]

Looks great! I'm merging it. Thanks @MarkWieczorek for the work!