Docs updates and code cleanups

docs/index.md

@@ -728,9 +728,9 @@ wedding_date: Our big day is ${{date_between(start_date="2022-01-31", end_date="
 
 ### `datetime_between`
 
-`datetime_between` is similar to `date_between` but relates to datetimes.
+`datetime_between` is similar to `date_between` but relates to [datetimes](#datetime).
 
-Some example of datetimes are below:
+Some example of randomized datetimes:
 
 ```yaml
 # tests/test_fake_datetimes.yml
@@ -755,7 +755,7 @@ Some example of datetimes are below:
     westerly:
       datetime_between:
         start_date: 1999-12-31 11:59:00
-        end_date: 1999-12-31 11:59:00
+        end_date: now
         timezone:
           relativedelta:
             hours: +8
@@ -1199,14 +1199,20 @@ The `datetime` function can generate
 a new datetime object from year/month/day parts, from a string
 or from a date object.
 
+A `datetime` combines both a date and a time into a single value. E.g. 11:03:21 on February 14, 2024. We can express that `datetime` as
+`2024-02-14 11:03:21`
+
+Datetimes default to using the UTC time-zone, but you can control that by
+adding a timezone after a plus sign: `2008-04-25 21:18:29+08:00`
+
 ```yaml
 # tests/test_datetime.yml
 - snowfakery_version: 3
 - object: Datetimes
   fields:
     from_date_fields: ${{datetime(year=2000, month=1, day=1)}}
-    from_datetime: ${{datetime(year=2000, month=1, day=1, hour=1, minute=1, second=1)}}
-    some_date:
+    from_datetime_fields: ${{datetime(year=2000, month=1, day=1, hour=1, minute=1, second=1)}}
+    some_date: # a date, not a datetime, for conversion later
       date_between:
         start_date: today
         end_date: +1y

snowfakery/output_streams.py

@@ -282,7 +282,7 @@ class SqlDbOutputStream(OutputStream):
 
     encoders: Mapping[type, Callable] = {
         **OutputStream.encoders,
-        datetime.datetime: format_datetime,
+        datetime.datetime: format_datetime,  # format into Salesforce-friendly syntax
     }
 
     should_close_session = False

snowfakery/template_funcs.py

@@ -60,6 +60,7 @@ def parse_date(d: Union[str, datetime, date]) -> date:
 
 @lru_cache(maxsize=512)
 def parse_datetimespec(d: Union[str, datetime, date]) -> datetime:
+    """Parse a string, datetime or date into a datetime."""
     if isinstance(d, datetime):
         return d
     elif isinstance(d, str):
@@ -128,25 +129,21 @@ def datetime(
             """A YAML-embeddable function to construct a datetime from strings or integers"""
             timezone = _normalize_timezone(timezone)
             if datetimespec:
+                if any((day, month, year, hour, minute, second, microsecond)):
+                    raise DataGenError(
+                        "Should not specify a date specification and also other parameters."
+                    )
                 dt = parse_datetimespec(datetimespec)
+                dt = dt.replace(tzinfo=timezone)
             elif not (any((year, month, day, hour, minute, second, microsecond))):
+                # no dt specification provided at all...just use now()
                 dt = datetime.now(timezone)
             else:
                 dt = datetime(
                     year, month, day, hour, minute, second, microsecond, timezone
                 )
 
-            year = year or dt.year
-            month = month or dt.month
-            day = day or dt.day
-            hour = hour or dt.hour
-            minute = minute or dt.minute
-            second = second or dt.second
-            microsecond = microsecond or dt.microsecond
-
-            return datetime(
-                year, month, day, hour, minute, second, microsecond, tzinfo=timezone
-            )
+            return dt
 
         def date_between(self, *, start_date, end_date, timezone=UTCAsRelDelta):
             """A YAML-embeddable function to pick a date between two ranges"""

tests/test_datetime.yml

@@ -2,8 +2,8 @@
 - object: Datetimes
   fields:
     from_date_fields: ${{datetime(year=2000, month=1, day=1)}}
-    from_datetime: ${{datetime(year=2000, month=1, day=1, hour=1, minute=1, second=1)}}
-    some_date:
+    from_datetime_fields: ${{datetime(year=2000, month=1, day=1, hour=1, minute=1, second=1)}}
+    some_date: # a date, not a datetime, for conversion later
       date_between:
         start_date: today
         end_date: +1y

tests/test_fake_datetimes.yml

@@ -19,7 +19,7 @@
     westerly:
       datetime_between:
         start_date: 1999-12-31 11:59:00
-        end_date: 1999-12-31 11:59:00
+        end_date: now
         timezone:
           relativedelta:
             hours: +8

tests/test_faker.py

@@ -150,9 +150,9 @@ def test_datetime_parsing(self, generated_rows):
             assert values["from_date_fields"].tzinfo == timezone.utc
             assert values["from_date_fields"].second == 0
             # from_datetime: ${{datetime(year=2000, month=1, day=1, hour=1, minute=1, second=1)}}
-            assert values["from_datetime"].year == 2000
-            assert values["from_datetime"].tzinfo == timezone.utc
-            assert values["from_datetime"].second == 1
+            assert values["from_datetime_fields"].year == 2000
+            assert values["from_datetime_fields"].tzinfo == timezone.utc
+            assert values["from_datetime_fields"].second == 1
 
             # from_date: ${{datetime(some_date)}}
             assert values["from_date"].year >= 2022