Improve documentation for utils.default_tzinfo

1 files changed, 15 insertions, 0 deletions

diff --git a/dateutil/utils.py b/dateutil/utils.py
index ae700b9..29f8181 100644
--- a/dateutil/utils.py
+++ b/dateutil/utils.py
@@ -24,6 +24,21 @@ def default_tzinfo(dt, tzinfo):
     """
     Sets the the ``tzinfo`` parameter on naive datetimes only
 
+    This is useful for example when you are provided a datetime that may have
+    either an implicit or explicit time zone, such as when parsing a time zone
+    string.
+
+    .. doctest::
+
+        >>> from dateutil.tz import tzoffset
+        >>> from dateutil.parser import parse
+        >>> from dateutil.utils import default_tzinfo
+        >>> dflt_tz = tzoffset("EST", -18000)
+        >>> print(default_tzinfo(parse('2014-01-01 12:30 UTC'), dflt_tz))
+        2014-01-01 12:30:00+00:00
+        >>> print(default_tzinfo(parse('2014-01-01 12:30'), dflt_tz))
+        2014-01-01 12:30:00-05:00
+
     :param dt:
         The datetime on which to replace the time zone