@@ -7,7 +7,7 @@ they return instances of the following classes.
77
88.. testsetup ::
99
10- from skyfield.units import Distance
10+ from skyfield.units import Angle, Distance
1111
1212.. currentmodule :: skyfield.units
1313
@@ -25,3 +25,139 @@ they return instances of the following classes.
2525
2626.. autoclass :: Rate
2727 :members:
28+
29+ .. _Formatting angles :
30+
31+ -----------------
32+ Formatting angles
33+ -----------------
34+
35+ To display an angle as decimal degrees or hours,
36+ ask the angle for its ``.hours `` or ``.degrees `` attribute
37+ and then use any normal Python mechanism for formatting a float.
38+ For example:
39+
40+ .. testcode ::
41+
42+ ra, dec = Angle(hours=5.5877286), Angle(degrees=-5.38731536)
43+
44+ print('RA {:.8f} hours'.format(ra.hours))
45+ print('Dec {:+.8f} degrees'.format(dec.degrees))
46+
47+ .. testoutput ::
48+
49+ RA 5.58772860 hours
50+ Dec -5.38731536 degrees
51+
52+ If you let Skyfield do the formatting instead,
53+ then hours are split into 60 minutes of 60 seconds each,
54+ and degrees are split into 60 arcminutes of 60 arcseconds each:
55+
56+ .. testcode ::
57+
58+ print('RA', ra)
59+ print('Dec', dec)
60+
61+ .. testoutput ::
62+
63+ RA 05h 35m 15.82s
64+ Dec -05deg 23' 14.3"
65+
66+ If you want more control over the display of minutes and seconds,
67+ you can call an angle’s “hours as a string” method :meth: `~Angle.hstr `
68+ or “degrees as a string” method :meth: `~Angle.dstr `.
69+ The simplest adjustment you can make
70+ is to specify the number of decimal ``places ``
71+ that will be shown in the seconds field.
72+
73+ .. testcode ::
74+
75+ print('RA', ra.hstr(places=4))
76+ print('Dec', dec.dstr(places=4))
77+
78+ .. testoutput ::
79+
80+ RA 05h 35m 15.8230s
81+ Dec -05deg 23' 14.3353"
82+
83+ In each of these examples
84+ you can see that Skyfield marks arcminutes
85+ with the ASCII apostrophe ``' ``
86+ and arcseconds
87+ with the ASCII quotation mark ``" ``.
88+ Using plain ASCII lets Skyfield
89+ support as many operating systems and output media as possible.
90+ But it would be more correct
91+ to denote arcseconds and arcminutes
92+ with the Unicode symbols PRIME and DOUBLE PRIME,
93+ and to use the Unicode DEGREE SIGN to mark the whole number:
94+
95+ −5°23′14.3″
96+
97+ If you want to override Skyfield’s default notation
98+ to create either the string above, or any other notation,
99+ then give :meth: `~Angle.hstr ` or :meth: `~Angle.dstr `
100+ a ``format= `` string of your own.
101+ It should use the syntax of Python’s
102+ `str.format() <https://docs.python.org/3/library/string.html#formatstrings >`_
103+ method.
104+ For example,
105+ here’s the exact string you would use
106+ to format an angle in degrees, arcminutes, and arcseconds
107+ using the traditional typographic symbols discussed above:
108+
109+ .. testcode ::
110+
111+ print(dec.dstr(format=u'{0}{1}°{2:02}′{3:02}.{4:0{5}}″'))
112+
113+ .. testoutput ::
114+
115+ -5°23′14.3″
116+
117+ (Note that the leading ``u ``, for “Unicode”, is only mandatory
118+ in Python 2, not Python 3.)
119+
120+ Skyfield will call your string’s format method
121+ with these six arguments:
122+
123+ {0}
124+ An ASCII hyphen ``'-' `` if the angle is negative,
125+ else the empty string.
126+ If you want positive angles to be decorated with a plus sign,
127+ try using ``{0:+>1} `` which tells Python,
128+ “display positional parameter 0,
129+ padding the field to one character wide
130+ if it’s less than one character already,
131+ and use the ``+ `` character to do the padding.”
132+
133+ {1}
134+ The number of whole hours or degrees.
135+
136+ {2}
137+ The number of whole minutes.
138+
139+ {3}
140+ The number of whole seconds.
141+
142+ {4}
143+ The fractions of a second.
144+ Be sure to pad this field
145+ to the number of ``places= `` you’ve requested,
146+ or else a fraction like ``.0012 `` will format incorrectly as ``.12 ``.
147+ If you have asked for ``places=3 ``, for example,
148+ you’ll want to display this field as ``{4:03} ``.
149+ (See also the next item.)
150+
151+ {5}
152+ The number of ``places= `` you requested,
153+ which you will probably use like ``{4:0{5}} ``
154+ when formatting field 4.
155+ You can use this
156+ in case you might not know the number of places ahead of time,
157+ for example if the number of places is configured by your user.
158+
159+ It would have been nice if the ``format= `` string
160+ were the first option to :meth: `~Angle.hstr ` or :meth: `~Angle.dstr `
161+ so that its keyword name could be omitted
162+ but, alas, it was only added in Skyfield 1.39,
163+ by which point the other options had already grabbed the first spots.
0 commit comments