For #406, mention more modern timezone sources

This commit is contained in:
Brandon Rhodes 2020-07-17 08:18:15 -04:00
parent b8fdc4dc4a
commit d23ce4e1ee
2 changed files with 61 additions and 34 deletions

View File

@ -63,20 +63,20 @@ are::
# All the ways you can create a Time object # All the ways you can create a Time object
# using a timescale: # using a timescale:
ts.utc(year, month, day, hour, minute, second) t = ts.utc(year, month, day, hour, minute, second)
ts.utc(dt) # Python datetime.datetime object t = ts.utc(dt) # Python datetime.datetime object
ts.tai(year, month, day, hour, minute, second) t = ts.tai(year, month, day, hour, minute, second)
ts.tai(jd=float) t = ts.tai_jd(float) # Julian date
ts.tt(year, month, day, hour, minute, second) t = ts.tt(year, month, day, hour, minute, second)
ts.tt(jd=float) t = ts.tt_jd(float) # Julian date
ts.tdb(year, month, day, hour, minute, second) t = ts.tdb(year, month, day, hour, minute, second)
ts.tdb(jd=float) t = ts.tdb_jd(float) # Julian date
ts.ut1(year, month, day, hour, minute, second) t = ts.ut1(year, month, day, hour, minute, second)
ts.ut1(jd=float) t = ts.ut1_jd(float) # Julian date
Once you have constructed a :class:`Time` object, Once you have constructed a :class:`Time` object,
you can provide it to any Skyfield routine that needs it. you can provide it to any Skyfield routine that needs it.
@ -110,8 +110,8 @@ are also automatically cached on the date object.
.. _building-dates: .. _building-dates:
UTC and your timezone Building and printing UTC
===================== =========================
The ``utc`` parameter in the examples above The ``utc`` parameter in the examples above
specifies Coordinated Universal Time (UTC), specifies Coordinated Universal Time (UTC),
@ -140,14 +140,14 @@ For example:
# Several ways to print a time as UTC. # Several ways to print a time as UTC.
print(tuple(t1.utc)) print(tuple(t1.utc))
print(t1.utc_iso()) print(t1.utc_iso(' '))
print(t1.utc_jpl()) print(t1.utc_jpl())
print(t1.utc_strftime('Date %Y-%m-%d and time %H:%M:%S')) print(t1.utc_strftime('Date %Y-%m-%d and time %H:%M:%S'))
.. testoutput:: .. testoutput::
(2014, 1, 18, 1, 35, 37.5) (2014, 1, 18, 1, 35, 37.5)
2014-01-18T01:35:38Z 2014-01-18 01:35:38Z
A.D. 2014-Jan-18 01:35:37.5000 UT A.D. 2014-Jan-18 01:35:37.5000 UT
Date 2014-01-18 and time 01:35:38 Date 2014-01-18 and time 01:35:38
@ -187,11 +187,33 @@ and configured with the correct time zone):
A.D. 2015-Oct-11 10:00:00.0000 UT A.D. 2015-Oct-11 10:00:00.0000 UT
To move beyond UTC to working with actual timezones, UTC and your timezone
you will need to install =====================
the third-party `pytz`_ package,
either by listing it in the dependencies of your package, To move beyond UTC and work with other world timezones,
adding it to your projects `requirements.txt`_ file, you will need to install a time zone database
for your version of Python.
* Every version of Python that Skyfield supports
will work with the `pytz`_ package described in this section.
* Python 3.6 upgraded the Standard Library ``datetime`` type
so that the contortions of `pytz`_ are no longer necessary,
and instead recommends
`dateutil <https://dateutil.readthedocs.io/en/stable/>`_
for working with timezones.
Consult its documentation if you are interested in using it.
* Python 3.9 will offer a native
`zoneinfo <https://docs.python.org/3.9/library/zoneinfo.html>`_
module that for the first time brings timezone support
into the Python Standard Library.
But this documentation will focus on the approach
which works universally across all Python versions.
You can install the third-party `pytz`_ library
by listing it in the dependencies of your package,
or adding it to your projects `requirements.txt`_ file,
or simply installing it manually:: or simply installing it manually::
pip install pytz pip install pytz

View File

@ -1,7 +1,7 @@
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
import re import re
from collections import namedtuple from collections import namedtuple
from datetime import date, datetime, timedelta, tzinfo from datetime import date, datetime
from numpy import (array, concatenate, cos, float_, interp, isnan, nan, from numpy import (array, concatenate, cos, float_, interp, isnan, nan,
ndarray, pi, rollaxis, searchsorted, sin, where, zeros_like) ndarray, pi, rollaxis, searchsorted, sin, where, zeros_like)
from time import strftime from time import strftime
@ -33,23 +33,28 @@ class CalendarArray(ndarray):
def second(self): return self[5] def second(self): return self[5]
try: try:
from pytz import utc from datetime import timezone
utc = timezone.utc
except ImportError: except ImportError:
try:
from pytz import utc
except ImportError:
# Lacking a full suite of timezones from pytz, we at least need a
# time zone object for UTC.
# Lacking a full suite of timezones from pytz, we at least need a from datetime import timedelta, tzinfo
# time zone object for UTC.
class UTC(tzinfo): class UTC(tzinfo):
'UTC' 'UTC'
zero = timedelta(0) zero = timedelta(0)
def utcoffset(self, dt): def utcoffset(self, dt):
return self.zero return self.zero
def tzname(self, dt): def tzname(self, dt):
return 'UTC' return 'UTC'
def dst(self, dt): def dst(self, dt):
return self.zero return self.zero
utc = UTC() utc = UTC()
# Much of the following code is adapted from the USNO's "novas.c". # Much of the following code is adapted from the USNO's "novas.c".
@ -949,7 +954,7 @@ You must either specify that your datetime is in UTC:
d = datetime(..., tzinfo=utc) # to build a new datetime d = datetime(..., tzinfo=utc) # to build a new datetime
d = d.replace(tzinfo=utc) # to fix an existing datetime d = d.replace(tzinfo=utc) # to fix an existing datetime
Or install the third-party `pytz` library and use any of its timezones: Or use a timezone object like those provided by the third-party `pytz` library:
from pytz import timezone from pytz import timezone
eastern = timezone('US/Eastern') eastern = timezone('US/Eastern')