# HG changeset patch # User Paul Ganssle <paul@ganssle.io> # Date 1525788147 14400 # Tue May 08 10:02:27 2018 -0400 # Node ID 4710eb3d0ad3a24cca227a4300ccef5fbe9eda86 # Parent 02091e1a6b9b92256687d21f7f91a5732a769e80 Improve documentation for gettz diff --git a/dateutil/tz/tz.py b/dateutil/tz/tz.py --- a/dateutil/tz/tz.py +++ b/dateutil/tz/tz.py @@ -1458,49 +1458,74 @@ tzlocal_classes += (tzwinlocal,) class GettzFunc(object): - """gettz(name=None) - - Given a variety of inputs, like time zone name and ``TZ`` varible, - return the tz (aka Olson) database time zone. - - :param name: - A time zone name, a ``TZ`` variable, or ``None``. + """ + Retrieve a time zone object from a string representation - :return: - A :class:`dateutil.tz.tzfile`. If name is ``None``, - the ``tzfile`` localtime is returned. + This function is intended to retrieve the :py:class:`tzinfo` subclass + that best represents the time zone that would be used if a POSIX + `TZ variable`_ were set to the same value. - **Examples:** + If no argument or an empty string is passed to ``gettz``, local time + is returned: - You can get the local time. - - .. code-block:: python + .. code-block:: python3 >>> gettz() tzfile('/etc/localtime') - You can parse time zone names. + This function is also the preferred way to map IANA tz database keys + to :class:`tzfile` objects: - .. code-block:: python + .. code-block:: python3 >>> gettz('Pacific/Kiritimati') tzfile('/usr/share/zoneinfo/Pacific/Kiritimati') - You can parse a ``TZ`` variable. + On Windows, the standard is extended to include the Windows-specific + zone names provided by the operating system: + + .. code-block:: python3 - .. code-block:: python + >>> gettz('Egypt Standard Time') + tzwin('Egypt Standard Time') + + Passing a GNU ``TZ`` style string time zone specification returns a + :class:`tzstr` object: + + .. code-block:: python3 >>> gettz('AEST-10AEDT-11,M10.1.0/2,M4.1.0/3') tzstr('AEST-10AEDT-11,M10.1.0/2,M4.1.0/3') - - Calling with the same name will return the same object. + + :param name: + A time zone name (IANA, or, on Windows, Windows keys), location of + a ``tzfile(5)`` zoneinfo file or ``TZ`` variable style time zone + specifier. An empty string, no argument or ``None`` is interpreted + as local time. + + :return: + Returns an instance of one of ``dateutil``'s :py:class:`tzinfo` + subclasses. - .. code-block:: python + .. versionchanged:: 2.7.0 + + After version 2.7.0, any two calls to ``gettz`` using the same + input strings will return the same object: - >>> tz.gettz('Pacific/Kiritimati') is tz.gettz('Pacific/Kiritimati') - True + .. code-block:: python3 + + >>> tz.gettz('America/Chicago') is tz.gettz('America/Chicago') + True + + In addition to improving performance, this ensures that + `"same zone" semantics`_ are used for datetimes in the same zone. + .. _`TZ variable`: + https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html + + .. _`"same zone" semantics`: + https://blog.ganssle.io/articles/2018/02/aware-datetime-arithmetic.html """ def __init__(self):