Fix docs on timezone of naive date(time) strings (#306)

Co-authored-by: Adam Johnson <[email protected]>

CHANGELOG.rst

@@ -6,6 +6,10 @@ Changelog
 
   Thanks to Nate Dudenhoeffer in `PR #298 <https://github.com/adamchainz/time-machine/pull/298>`__.
 
+* Fix documentation about using local time for naive date(time) strings.
+
+  Thanks to Stefaan Lippens in `PR #306 <https://github.com/adamchainz/time-machine/pull/306>`__.
+
 * Add ``shift()`` method to the ``time_machine`` pytest fixture.
 
   Thanks to Stefaan Lippens in `PR #312 <https://github.com/adamchainz/time-machine/pull/312>`__.

README.rst

@@ -82,7 +82,7 @@ It may be:
   If already within a ``travel()`` block, the ``shift()`` method is easier to use (documented below).
 * A ``float`` or ``int`` specifying a `Unix timestamp <https://en.m.wikipedia.org/wiki/Unix_time>`__
 * A string, which will be parsed with `dateutil.parse <https://dateutil.readthedocs.io/en/stable/parser.html>`__ and converted to a timestamp.
-  Again, if the result is naive, it will be assumed to have the UTC time zone.
+  If the result is naive, it will be assumed to be local time.
 
 .. |zoneinfo-instance| replace:: ``zoneinfo.ZoneInfo`` instance
 .. _zoneinfo-instance: https://docs.python.org/3/library/zoneinfo.html#zoneinfo.ZoneInfo

tests/test_time_machine.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import datetime as dt
 import os
 import sys
 import time
+import typing
 import uuid
 from importlib.util import module_from_spec
 from importlib.util import spec_from_file_location
@@ -467,6 +469,33 @@ def test_destination_string():
     assert time.time() == EPOCH + 60.0
 
 
+@contextlib.contextmanager
+def change_local_timezone(local_tz: str) -> typing.Iterator[None]:
+    orig_tz = os.environ["TZ"]
+    os.environ["TZ"] = local_tz
+    time.tzset()
+    try:
+        yield
+    finally:
+        os.environ["TZ"] = orig_tz
+        time.tzset()
+
+
+@pytest.mark.parametrize(
+    ["local_tz", "expected_offset"],
+    [
+        ("UTC", 0),
+        ("Europe/Amsterdam", -3600),
+        ("US/Eastern", 5 * 3600),
+    ],
+)
+@pytest.mark.parametrize("destination", ["1970-01-01 00:00", "1970-01-01"])
+def test_destination_string_naive(local_tz, expected_offset, destination):
+    with change_local_timezone(local_tz):
+        with time_machine.travel(destination):
+            assert time.time() == EPOCH + expected_offset
+
+
 @time_machine.travel(lambda: EPOCH + 140.0)
 def test_destination_callable_lambda_float():
     assert time.time() == EPOCH + 140.0