diff --git a/AUTHORS.md b/AUTHORS.md index 7b95e12104093da89ba84678be9d47f4ddb899f0_QVVUSE9SUy5tZA==..0219cc3c8a3142ae26a6a3abb0cb5755039b0756_QVVUSE9SUy5tZA== 100644 --- a/AUTHORS.md +++ b/AUTHORS.md @@ -68,6 +68,7 @@ - Peter Bieringer <pb@MASKED> - Pierre Gergondet <pierre.gergondet@MASKED> (gh: @gergondet) - Quentin Pradet <quentin@MASKED> +- Raymond Cha (gh: @weatherpattern) **D** - Ridhi Mahajan <ridhikmahajan@MASKED> **D** - Roy Williams <rwilliams@MASKED> - Rustem Saiargaliev (gh: @amureki) **D** diff --git a/changelog.d/704.doc.rst b/changelog.d/704.doc.rst new file mode 100644 index 0000000000000000000000000000000000000000..0219cc3c8a3142ae26a6a3abb0cb5755039b0756_Y2hhbmdlbG9nLmQvNzA0LmRvYy5yc3Q= --- /dev/null +++ b/changelog.d/704.doc.rst @@ -0,0 +1,1 @@ +Added documentation for ``dateutil.tz.gettz``. Reported by @pganssle (gh issue #647). Fixed by @weatherpattern (gh pr #704) diff --git a/dateutil/tz/tz.py b/dateutil/tz/tz.py index 7b95e12104093da89ba84678be9d47f4ddb899f0_ZGF0ZXV0aWwvdHovdHoucHk=..0219cc3c8a3142ae26a6a3abb0cb5755039b0756_ZGF0ZXV0aWwvdHovdHoucHk= 100644 --- a/dateutil/tz/tz.py +++ b/dateutil/tz/tz.py @@ -190,8 +190,6 @@ class tzlocal(_tzinfo): """ A :class:`tzinfo` subclass built around the ``time`` timezone functions. - - """ def __init__(self): super(tzlocal, self).__init__() @@ -1460,6 +1458,75 @@ tzlocal_classes += (tzwinlocal,) class GettzFunc(object): + """ + Retrieve a time zone object from a string representation + + 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. + + If no argument or an empty string is passed to ``gettz``, local time + is returned: + + .. code-block:: python3 + + >>> gettz() + tzfile('/etc/localtime') + + This function is also the preferred way to map IANA tz database keys + to :class:`tzfile` objects: + + .. code-block:: python3 + + >>> gettz('Pacific/Kiritimati') + tzfile('/usr/share/zoneinfo/Pacific/Kiritimati') + + On Windows, the standard is extended to include the Windows-specific + zone names provided by the operating system: + + .. code-block:: python3 + + >>> 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') + + :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. + + .. versionchanged:: 2.7.0 + + After version 2.7.0, any two calls to ``gettz`` using the same + input strings will return the same object: + + .. 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): self.__instances = weakref.WeakValueDictionary() diff --git a/docs/tz.rst b/docs/tz.rst index 7b95e12104093da89ba84678be9d47f4ddb899f0_ZG9jcy90ei5yc3Q=..0219cc3c8a3142ae26a6a3abb0cb5755039b0756_ZG9jcy90ei5yc3Q= 100644 --- a/docs/tz.rst +++ b/docs/tz.rst @@ -1,6 +1,8 @@ == tz == +.. autofunction:: dateutil.tz.gettz + .. automodule:: dateutil.tz :members: :undoc-members: