diff --git a/dateutil/tz/tz.py b/dateutil/tz/tz.py index 02091e1a6b9b92256687d21f7f91a5732a769e80_ZGF0ZXV0aWwvdHovdHoucHk=..4710eb3d0ad3a24cca227a4300ccef5fbe9eda86_ZGF0ZXV0aWwvdHovdHoucHk= 100644 --- a/dateutil/tz/tz.py +++ b/dateutil/tz/tz.py @@ -1458,11 +1458,6 @@ 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 @@ -1468,5 +1463,5 @@ - :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. @@ -1472,3 +1467,4 @@ - **Examples:** + If no argument or an empty string is passed to ``gettz``, local time + is returned: @@ -1474,8 +1470,6 @@ - You can get the local time. - - .. code-block:: python + .. code-block:: python3 >>> gettz() tzfile('/etc/localtime') @@ -1478,6 +1472,7 @@ >>> 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: @@ -1483,6 +1478,6 @@ - .. code-block:: python + .. code-block:: python3 >>> gettz('Pacific/Kiritimati') tzfile('/usr/share/zoneinfo/Pacific/Kiritimati') @@ -1485,6 +1480,9 @@ >>> 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 @@ -1490,5 +1488,11 @@ - .. 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') @@ -1492,6 +1496,14 @@ >>> 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. @@ -1497,3 +1509,6 @@ - .. 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: @@ -1499,5 +1514,10 @@ - >>> 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. @@ -1502,5 +1522,10 @@ + .. _`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):