Docs

wtftz/converter.py

@@ -17,6 +17,16 @@ def convert(timestamp, to_tz="utc", from_tz="utc", naive=True):
         naive: If True, then strip the tzinfo from the converted timestamp,
                if False then leave it.
     Returns a timestamp in the requested timezone.
+
+    An important caveat is that if you include a timezone offset in the
+    "timestamp" string, the `from_tz` parameter will be ignored. For example
+    if you do the following:
+
+    >>> wtftz.convert(
+    ... '2012-12-23T14:23:03.826437-05:00', to_tz='utc', from_tz='pst')
+
+    Then wtftz will use US/Eastern standard time and ignore the 'pst' value
+    for `from_tz`.
     """
     if not to_tz:
         to_tz = "utc"
@@ -35,6 +45,15 @@ def convert(timestamp, to_tz="utc", from_tz="utc", naive=True):
 
 
 def convert_free(query):
+    """Parse a string and convert the found timestamp with the found tz.
+
+    Args:
+        query - A string with a time, and a source and destination timezone.
+
+    EG:
+    >>> wtftz.convert_free("2012-12-23T14:23:03.826437-05:00 to pst")
+    datetime(2012, 12, 23, 11, 23, 03, 826437)
+    """
     ts, fromz, toz = free_text(query)
     return convert(ts, toz, fromz)