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')