Merge pull request #57 from kalaspuff/feature/utcnow-today

Added utcnow.get_today() / utcnow.as_date_string()

README.md

@@ -318,6 +318,36 @@ result = f"Current server time is: '{utcnow}'"
 # "Current server time is: '2021-02-18T08:24:48.382262Z'"
 ```
 
+### Get the date part as a string from a timestamp
+
+Not as common, but every now and then you might need to get the date part from a timestamp (or for example today's date), to use in some string concatenation, S3 object keys and what not.
+
+There's the long away around it, by generating a timestamp with `utcnow.get()` and then just keeping the first 10 characters of the timestamp – that's the date – `YYYY-MM-DD`. You could even use `datetime` and go `datetime.datetime.utcnow().date().isoformat()`, but it's not super clean.
+
+`utcnow` comes with a wrapper function `utcnow.as_date_string(value)` to fetch just the date part based on the input value's UTC timestamp. Note that the date string that is returned does not include timezone information.
+
+```python
+import utcnow
+
+timestamp = "2022-04-05T13:44:52.748994Z"
+utcnow.as_date_string(timestamp)
+# "2022-04-05"
+```
+
+Bonus 🎉🎉 – calling the `utcnow.as_date_string()` function without arguments will return today's date, _based on the current time in UTC_. For some sugar to your code, the same function is also available under the name `utcnow.get_today()`.
+
+To get the current date in another timezone use the keyword argument `tz` to the function call. The value for `tz` should be either a `datetime.tzinfo` object or an utcoffset represented as a string (for example "+01:00", "-06:00", etc.).
+
+```python
+import utcnow
+
+utcnow.get_today()
+# "2022-04-05" (it's the 5th of April when typing this)
+
+utcnow.get_today(tz="+12:00")
+# "2022-04-06" (time in UTC is currently 15:12 - adding 12 hours to that would yield 03:12 tomorrow)
+```
+
 ### How much time between timestamp A and timestamp B?
 
 The library also comes with a small utility function for calculating the number of seconds (usually) between two timestamps.It's called `utcnow.timediff` and works like this.

tests/test_dates.py

@@ -2,6 +2,8 @@
 
 import pytest
 
+import utcnow
+
 
 @pytest.mark.parametrize(
     "value, expect_error",
@@ -126,3 +128,45 @@ def test_dates(value: str, expect_error: bool) -> None:
             assert False
 
         assert True
+
+
+def test_as_date_string() -> None:
+    date_today_0 = datetime.datetime.utcnow().date().isoformat()
+    assert utcnow.get_today() == date_today_0 or utcnow.get_today() == datetime.datetime.utcnow().date().isoformat()
+
+    assert utcnow.as_date_string("2022-04-04") == "2022-04-04"
+    assert utcnow.as_date_string("2021-01-02T00:00:00.04000Z") == "2021-01-02"
+
+    assert utcnow.get_today(tz="+24:00") != utcnow.get_today()
+    assert utcnow.get_today(tz="-24:00") != utcnow.get_today()
+
+    assert (
+        utcnow.get_today(tz="UTC") == date_today_0
+        or utcnow.get_today(tz="UTC") == datetime.datetime.utcnow().date().isoformat()
+    )
+    assert (
+        utcnow.get_today(tz=datetime.timezone.utc) == date_today_0
+        or utcnow.get_today(tz=datetime.timezone.utc) == datetime.datetime.utcnow().date().isoformat()
+    )
+
+    assert utcnow.get_today(tz=datetime.timezone(datetime.timedelta(hours=24, microseconds=-1))) != utcnow.get_today()
+    assert utcnow.get_today(tz=datetime.timezone(datetime.timedelta(hours=24, microseconds=-1))) == utcnow.get_today(
+        tz="+24:00"
+    ) or utcnow.get_today(tz=datetime.timezone(datetime.timedelta(hours=24, microseconds=-1))) == utcnow.get_today(
+        tz="+24:00"
+    )
+
+    with pytest.raises(ValueError):
+        utcnow.get_today(tz="UnknownTimezone")
+
+    with pytest.raises(ValueError):
+        utcnow.get_today(tz=datetime.timezone)  # type:ignore
+
+    with pytest.raises(ValueError):
+        utcnow.get_today(tz="+32:00")
+
+    with pytest.raises(ValueError):
+        utcnow.get_today(tz="-32:00")
+
+    with pytest.raises(ValueError):
+        utcnow.get_today(tz="+TEST")

tests/test_module_calls.py

@@ -140,14 +140,15 @@ def test_module() -> None:
     )
 
     # Testing function imports
-    from utcnow import as_str, as_string
+    from utcnow import as_date_string, as_str, as_string
     from utcnow import str as str_
     from utcnow import string
 
     assert as_string("1984-08-01") == "1984-08-01T00:00:00.000000Z"
     assert as_str("1984-08-01") == "1984-08-01T00:00:00.000000Z"
     assert string("1984-08-01") == "1984-08-01T00:00:00.000000Z"
     assert str_("1984-08-01") == "1984-08-01T00:00:00.000000Z"
+    assert as_date_string("1984-08-01") == "1984-08-01"
     assert datetime.datetime.strptime(as_string(), "%Y-%m-%dT%H:%M:%S.%f%z")
     assert datetime.datetime.strptime(as_str(), "%Y-%m-%dT%H:%M:%S.%f%z")
     assert datetime.datetime.strptime(string(), "%Y-%m-%dT%H:%M:%S.%f%z")
@@ -161,6 +162,8 @@ def test_module() -> None:
     assert utcnow_.as_str("1984-08-01") == "1984-08-01T00:00:00.000000Z"
     assert utcnow_.string("1984-08-01") == "1984-08-01T00:00:00.000000Z"
     assert utcnow_.str("1984-08-01") == "1984-08-01T00:00:00.000000Z"
+    assert utcnow_.as_date_string("1984-08-01") == "1984-08-01"
+    assert utcnow_.get_today()
     assert datetime.datetime.strptime(utcnow_(), "%Y-%m-%dT%H:%M:%S.%f%z")
     assert datetime.datetime.strptime(utcnow_.as_string(), "%Y-%m-%dT%H:%M:%S.%f%z")
     assert datetime.datetime.strptime(utcnow_.as_str(), "%Y-%m-%dT%H:%M:%S.%f%z")