diff --git a/changelog.d/671.doc.rst b/changelog.d/671.doc.rst new file mode 100644 index 0000000000000000000000000000000000000000..37e4ff00bb7b62593daec3376e79daed42449542_Y2hhbmdlbG9nLmQvNjcxLmRvYy5yc3Q= --- /dev/null +++ b/changelog.d/671.doc.rst @@ -0,0 +1,1 @@ +Add doctest examples to tzfile documentation. Done by @weatherpattern and @pganssle (gh pr #671) diff --git a/dateutil/tz/tz.py b/dateutil/tz/tz.py index 08e04766a1434a7713aec18b017eedd45c5e9f28_ZGF0ZXV0aWwvdHovdHoucHk=..37e4ff00bb7b62593daec3376e79daed42449542_ZGF0ZXV0aWwvdHovdHoucHk= 100644 --- a/dateutil/tz/tz.py +++ b/dateutil/tz/tz.py @@ -395,5 +395,14 @@ <https://www.iana.org/time-zones>`_ with the `zic time zone compiler <https://www.freebsd.org/cgi/man.cgi?query=zic&sektion=8>`_ + .. note:: + + Only construct a ``tzfile`` directly if you have a specific timezone + file on disk that you want to read into a Python ``tzinfo`` object. + If you want to get a ``tzfile`` representing a specific IANA zone, + (e.g. ``'America/New_York'``), you should call + :func:`dateutil.tz.gettz` with the zone identifier. + + **Examples:** @@ -398,4 +407,12 @@ **Examples:** + Using the US Eastern time zone as an example, we can see that a ``tzfile`` + provides time zone information for the standard Daylight Saving offsets: + + .. testsetup:: tzfile + + from dateutil.tz import gettz + from datetime import datetime + .. doctest:: tzfile @@ -400,7 +417,6 @@ .. doctest:: tzfile - >>> tz = tzfile("/etc/localtime") - >>> datetime.now(tz) - datetime.datetime(2003, 9, 27, 12, 3, 48, 392138, - tzinfo=tzfile('/etc/localtime')) + >>> NYC = gettz('America/New_York') + >>> NYC + tzfile('/usr/share/zoneinfo/America/New_York') @@ -406,4 +422,4 @@ - >>> datetime.now(tz).astimezone(tzutc()) - datetime.datetime(2003, 9, 27, 15, 3, 53, 70863, tzinfo=tzutc()) + >>> print(datetime(2016, 1, 3, tzinfo=NYC)) # EST + 2016-01-03 00:00:00-05:00 @@ -409,7 +425,5 @@ - >>> datetime.now(tz).tzname() - 'BRST' - >>> datetime(2003, 1, 1, tzinfo=tz).tzname() - 'BRDT' + >>> print(datetime(2016, 7, 7, tzinfo=NYC)) # EDT + 2016-07-07 00:00:00-04:00 @@ -414,6 +428,8 @@ - Check the daylight limit: + The ``tzfile`` structure contains a fully history of the time zone, + so historical dates will also have the right offsets. For example, before + the adoption of the UTC standards, New York used local solar mean time: .. doctest:: tzfile @@ -417,15 +433,16 @@ .. doctest:: tzfile - >>> tz = tzfile('/usr/share/zoneinfo/EST5EDT') - >>> datetime(2003, 4, 6, 1, 59, tzinfo=tz).tzname() - 'EST' - >>> datetime(2003, 4, 6, 2, 00, tzinfo=tz).tzname() - 'EDT' - >>> datetime(2003, 10, 26, 0, 59, tzinfo=tz).tzname() - 'EDT' - >>> datetime(2003, 10, 26, 1, 00, tzinfo=tz).tzname() - 'EST' + >>> print(datetime(1901, 4, 12, tzinfo=NYC)) # LMT + 1901-04-12 00:00:00-04:56 + + And during World War II, New York was on "Eastern War Time", which was a + state of permanent daylight saving time: + + .. doctest:: tzfile + + >>> print(datetime(1944, 2, 7, tzinfo=NYC)) # EWT + 1944-02-07 00:00:00-04:00 """