From d23ce4e1eed6394d7000a65222ec545c3b1287c2 Mon Sep 17 00:00:00 2001 From: Brandon Rhodes Date: Fri, 17 Jul 2020 08:18:15 -0400 Subject: [PATCH] For #406, mention more modern timezone sources --- skyfield/documentation/time.rst | 60 ++++++++++++++++++++++----------- skyfield/timelib.py | 35 ++++++++++--------- 2 files changed, 61 insertions(+), 34 deletions(-) diff --git a/skyfield/documentation/time.rst b/skyfield/documentation/time.rst index b7a2f60..33bc089 100644 --- a/skyfield/documentation/time.rst +++ b/skyfield/documentation/time.rst @@ -63,20 +63,20 @@ are:: # All the ways you can create a Time object # using a timescale: - ts.utc(year, month, day, hour, minute, second) - ts.utc(dt) # Python datetime.datetime object + t = ts.utc(year, month, day, hour, minute, second) + t = ts.utc(dt) # Python datetime.datetime object - ts.tai(year, month, day, hour, minute, second) - ts.tai(jd=float) + t = ts.tai(year, month, day, hour, minute, second) + t = ts.tai_jd(float) # Julian date - ts.tt(year, month, day, hour, minute, second) - ts.tt(jd=float) + t = ts.tt(year, month, day, hour, minute, second) + t = ts.tt_jd(float) # Julian date - ts.tdb(year, month, day, hour, minute, second) - ts.tdb(jd=float) + t = ts.tdb(year, month, day, hour, minute, second) + t = ts.tdb_jd(float) # Julian date - ts.ut1(year, month, day, hour, minute, second) - ts.ut1(jd=float) + t = ts.ut1(year, month, day, hour, minute, second) + t = ts.ut1_jd(float) # Julian date Once you have constructed a :class:`Time` object, 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: -UTC and your timezone -===================== +Building and printing UTC +========================= The ``utc`` parameter in the examples above specifies Coordinated Universal Time (UTC), @@ -140,14 +140,14 @@ For example: # Several ways to print a time as UTC. print(tuple(t1.utc)) - print(t1.utc_iso()) + print(t1.utc_iso(' ')) print(t1.utc_jpl()) print(t1.utc_strftime('Date %Y-%m-%d and time %H:%M:%S')) .. testoutput:: (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 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 -To move beyond UTC to working with actual timezones, -you will need to install -the third-party `pytz`_ package, -either by listing it in the dependencies of your package, -adding it to your project’s `requirements.txt`_ file, +UTC and your timezone +===================== + +To move beyond UTC and work with other world timezones, +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 `_ + for working with timezones. + Consult its documentation if you are interested in using it. + +* Python 3.9 will offer a native + `zoneinfo `_ + 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 project’s `requirements.txt`_ file, or simply installing it manually:: pip install pytz diff --git a/skyfield/timelib.py b/skyfield/timelib.py index c83f231..ffa0422 100644 --- a/skyfield/timelib.py +++ b/skyfield/timelib.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- import re 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, ndarray, pi, rollaxis, searchsorted, sin, where, zeros_like) from time import strftime @@ -33,23 +33,28 @@ class CalendarArray(ndarray): def second(self): return self[5] try: - from pytz import utc + from datetime import timezone + utc = timezone.utc 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 - # time zone object for UTC. + from datetime import timedelta, tzinfo - class UTC(tzinfo): - 'UTC' - zero = timedelta(0) - def utcoffset(self, dt): - return self.zero - def tzname(self, dt): - return 'UTC' - def dst(self, dt): - return self.zero + class UTC(tzinfo): + 'UTC' + zero = timedelta(0) + def utcoffset(self, dt): + return self.zero + def tzname(self, dt): + return 'UTC' + def dst(self, dt): + return self.zero - utc = UTC() + utc = UTC() # 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 = 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 eastern = timezone('US/Eastern')