Documentation is unclear about how to create angles, what values to pass to degrees() or hours()

[akkana]

First, a question: is PyEphem still maintained or should I be switching to astropy?

The PyEphem documentation is very unclear about angles and how to create them or do math on them.

It says the only way to create an Angle is with degrees() or hours(), but it doesn't say what the argument should be. It says this:

You can also create angles yourself through two ephem functions: degrees() — return an Angle in degrees hours() — return an Angle in hours

Through experimentation, I've found that calling degrees on a string representing works, but if I call degrees on a float, the argument needs to be in radians:

seven_from_float = ephem.degrees(7.) seven_from_str = ephem.degrees('7') print(seven_from_float, seven_from_str) 401:04:13.6 7:00:00.0 print(seven_from_float.norm, seven_from_str) 41:04:13.6 7:00:00.0 seven_from_radians = ephem.degrees(7 * math.pi / 180.) print(seven_from_radians) 7:00:00.0

Hours does pretty much the same thing: initialized from a string, it wants hours, but from a float, it wants radians.

It's easy enough to make those conversions, but it's not what I would have expected from the documentation and took a while to experiment and figure out what I needed.

[brandon-rhodes]

Yes, I consider the sensitivity to type — string versus number — to have been a terrible design decision on my part, one of the things I hadn't yet learned to avoid when doing Python programming when I designed the interface long ago. It's fragile and confusing.

In my new astronomy library Skyfield, explicit argument names always make it clear whether an Angle is created using radians or degrees. And, yes, I think the astropy folks are similarly careful.

We can keep this issue open for the next time I'm in the PyEphem docs; I can at least try to clarify them a bit more. Where did you look in the docs that you'd like to be clearer, so I know which section to edit?

[akkana]

Thanks for the response! I looked first at http://rhodesmill.org/pyephem/quick.html#angles and then followed the link for more info, http://rhodesmill.org/pyephem/angle though actually, I don't think I found anything useful in the Angle document that wasn't already in the quick reference.

Meanwhile, I may take a look at Skyfield. I played around with astropy a bit, but there are still a lot of things pyephem does better: pyphem is massively faster, and it has a lot of convenience functions astropy lacks like rising/setting, equinoxes and solstices, elongation and the cities library, so at least for solar system programs, astropy programs require a lot more programming.

[brandon-rhodes]

I've updated the docs! Thanks for the suggestion :)