diff --git a/changelog.d/704.doc.rst b/changelog.d/704.doc.rst new file mode 100644 index 0000000000000000000000000000000000000000..98c591aa12185ccb6867b4f422c259a662080905_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=..98c591aa12185ccb6867b4f422c259a662080905_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,50 @@ 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``. + + :return: + A :class:`dateutil.tz.tzfile`. If name is ``None``, + the ``tzfile`` localtime is returned. + + **Examples:** + + You can get the local time. + + .. code-block:: python + + >>> gettz() + tzfile('/etc/localtime') + + You can parse time zone names. + + .. code-block:: python + + >>> gettz('Pacific/Kiritimati') + tzfile('/usr/share/zoneinfo/Pacific/Kiritimati') + + You can parse a ``TZ`` variable. + + .. code-block:: python + + >>> 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. + + .. code-block:: python + + >>> tz.gettz('Pacific/Kiritimati') is tz.gettz('Pacific/Kiritimati') + True + + + """ def __init__(self): self.__instances = weakref.WeakValueDictionary() diff --git a/docs/tz.rst b/docs/tz.rst index 7b95e12104093da89ba84678be9d47f4ddb899f0_ZG9jcy90ei5yc3Q=..98c591aa12185ccb6867b4f422c259a662080905_ZG9jcy90ei5yc3Q= 100644 --- a/docs/tz.rst +++ b/docs/tz.rst @@ -4,3 +4,5 @@ .. automodule:: dateutil.tz :members: :undoc-members: + +.. automethod:: dateutil.tz.gettz \ No newline at end of file