feat(api core): simplify from_rfc3339 methods

api_core/google/api_core/datetime_helpers.py

@@ -17,6 +17,7 @@
 import calendar
 import datetime
 import re
+import warnings
 
 import pytz
 
@@ -115,20 +116,8 @@ def from_iso8601_time(value):
 
 
 def from_rfc3339(value):
-    """Convert a microsecond-precision timestamp to datetime.
-
-    Args:
-        value (str): The RFC3339 string to convert.
-
-    Returns:
-        datetime.datetime: The datetime object equivalent to the timestamp in
-            UTC.
-    """
-    return datetime.datetime.strptime(value, _RFC3339_MICROS).replace(tzinfo=pytz.utc)
-
-
-def from_rfc3339_nanos(value):
-    """Convert a nanosecond-precision timestamp to a native datetime.
+    """Convert a nanosecond-precision or if nanoseconds are missing
+    microsecond-precision timestamp to a native datetime.
 
     .. note::
         Python datetimes do not support nanosecond precision; this function
@@ -138,12 +127,9 @@ def from_rfc3339_nanos(value):
         value (str): The RFC3339 string to convert.
 
     Returns:
-        datetime.datetime: The datetime object equivalent to the timestamp in
-            UTC.
+        datetime.datetime: The datetime object equivalent to the timestamp
+        in UTC.
 
-    Raises:
-        ValueError: If the timestamp does not match the RFC 3339
-            regular expression.
     """
     with_nanos = _RFC3339_NANOS.match(value)
 
@@ -169,6 +155,34 @@ def from_rfc3339_nanos(value):
     return bare_seconds.replace(microsecond=micros, tzinfo=pytz.utc)
 
 
+def from_rfc3339_nanos(value):
+    """DEPRECATED. Convert a nanosecond-precision timestamp to a native datetime.
+
+    .. note::
+        Python datetimes do not support nanosecond precision; this
+        function therefore truncates such values to microseconds.
+
+    Args:
+        value (str): The RFC3339 string to convert.
+
+    Returns:
+        datetime.datetime: The datetime object equivalent to the
+        timestamp in UTC.
+
+    Raises:
+        ValueError: If the timestamp does not match the RFC3339
+            regular expression.
+    """
+    # Raise deprecation warnings for things we want to go away.
+    warnings.warn(
+        "The `from_rfc3339_nanos` function is deprecated"
+        " use `from_rfc3339` instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return from_rfc3339(value)
+
+
 def to_rfc3339(value, ignore_zone=True):
     """Convert a datetime to an RFC3339 timestamp string.
 
@@ -215,22 +229,22 @@ def nanosecond(self):
         return self._nanosecond
 
     def rfc3339(self):
-        """Return an RFC 3339-compliant timestamp.
+        """Return an RFC3339-compliant timestamp.
 
         Returns:
-            (str): Timestamp string according to RFC 3339 spec.
+            (str): Timestamp string according to RFC3339 spec.
         """
         if self._nanosecond == 0:
             return to_rfc3339(self)
-        nanos = str(self._nanosecond).rjust(9, '0').rstrip("0")
+        nanos = str(self._nanosecond).rjust(9, "0").rstrip("0")
         return "{}.{}Z".format(self.strftime(_RFC3339_NO_FRACTION), nanos)
 
     @classmethod
     def from_rfc3339(cls, stamp):
-        """Parse RFC 3339-compliant timestamp, preserving nanoseconds.
+        """Parse RFC3339-compliant timestamp, preserving nanoseconds.
 
         Args:
-            stamp (str): RFC 3339 stamp, with up to nanosecond precision
+            stamp (str): RFC3339 stamp, with up to nanosecond precision
 
         Returns:
             :class:`DatetimeWithNanoseconds`:
@@ -280,7 +294,7 @@ def timestamp_pb(self):
 
     @classmethod
     def from_timestamp_pb(cls, stamp):
-        """Parse RFC 3339-compliant timestamp, preserving nanoseconds.
+        """Parse RFC3339-compliant timestamp, preserving nanoseconds.
 
         Args:
             stamp (:class:`~google.protobuf.timestamp_pb2.Timestamp`): timestamp message

api_core/tests/unit/test_datetime_helpers.py

@@ -15,6 +15,7 @@
 import calendar
 import datetime
 
+import mock
 import pytest
 import pytz
 
@@ -23,6 +24,9 @@
 
 
 ONE_MINUTE_IN_MICROSECONDS = 60 * 1e6
+MESSAGE = (
+    "The `from_rfc3339_nanos` function is deprecated" " use `from_rfc3339` instead."
+)
 
 
 def test_utcnow():
@@ -82,18 +86,18 @@ def test_from_rfc3339():
     )
 
 
-def test_from_rfc3339_with_bad_tz():
-    value = "2009-12-17T12:44:32.123456BAD"
-
-    with pytest.raises(ValueError):
-        datetime_helpers.from_rfc3339(value)
-
+def test_from_rfc3339_nanos():
+    value = "2009-12-17T12:44:32.123456Z"
+    assert datetime_helpers.from_rfc3339_nanos(value) == datetime.datetime(
+        2009, 12, 17, 12, 44, 32, 123456, pytz.utc
+    )
 
-def test_from_rfc3339_with_nanos():
-    value = "2009-12-17T12:44:32.123456789Z"
 
-    with pytest.raises(ValueError):
-        datetime_helpers.from_rfc3339(value)
+def test_from_rfc3339_without_nanos():
+    value = "2009-12-17T12:44:32Z"
+    assert datetime_helpers.from_rfc3339(value) == datetime.datetime(
+        2009, 12, 17, 12, 44, 32, 0, pytz.utc
+    )
 
 
 def test_from_rfc3339_nanos_without_nanos():
@@ -103,11 +107,37 @@ def test_from_rfc3339_nanos_without_nanos():
     )
 
 
-def test_from_rfc3339_nanos_with_bad_tz():
-    value = "2009-12-17T12:44:32.123456789BAD"
+@pytest.mark.parametrize(
+    "truncated, micros",
+    [
+        ("12345678", 123456),
+        ("1234567", 123456),
+        ("123456", 123456),
+        ("12345", 123450),
+        ("1234", 123400),
+        ("123", 123000),
+        ("12", 120000),
+        ("1", 100000),
+    ],
+)
+def test_from_rfc3339_with_truncated_nanos(truncated, micros):
+    value = "2009-12-17T12:44:32.{}Z".format(truncated)
+    assert datetime_helpers.from_rfc3339(value) == datetime.datetime(
+        2009, 12, 17, 12, 44, 32, micros, pytz.utc
+    )
 
-    with pytest.raises(ValueError):
-        datetime_helpers.from_rfc3339_nanos(value)
+
+def test_from_rfc3339_nanos_is_deprecated():
+    from_rfc3339_patch = mock.patch("google.api_core.datetime_helpers.from_rfc3339")
+    warnings_patch = mock.patch("warnings.warn")
+    value = "2009-12-17T12:44:32.123456Z"
+
+    with from_rfc3339_patch as from_rfc3339, warnings_patch as warn:
+        result = datetime_helpers.from_rfc3339_nanos(value)
+
+    assert result is from_rfc3339.return_value
+    from_rfc3339.assert_called_once_with(value)
+    warn.assert_called_once_with(MESSAGE, DeprecationWarning, stacklevel=2)
 
 
 @pytest.mark.parametrize(
@@ -130,6 +160,18 @@ def test_from_rfc3339_nanos_with_truncated_nanos(truncated, micros):
     )
 
 
+def test_from_rfc3339_wo_nanos_raise_exception():
+    value = "2009-12-17T12:44:32"
+    with pytest.raises(ValueError):
+        datetime_helpers.from_rfc3339(value)
+
+
+def test_from_rfc3339_w_nanos_raise_exception():
+    value = "2009-12-17T12:44:32.123456"
+    with pytest.raises(ValueError):
+        datetime_helpers.from_rfc3339(value)
+
+
 def test_to_rfc3339():
     value = datetime.datetime(2016, 4, 5, 13, 30, 0)
     expected = "2016-04-05T13:30:00.000000Z"
@@ -157,10 +199,11 @@ def test_to_rfc3339_with_non_utc_ignore_zone():
 
 
 class Test_DateTimeWithNanos(object):
-
     @staticmethod
     def test_ctor_wo_nanos():
-        stamp = datetime_helpers.DatetimeWithNanoseconds(2016, 12, 20, 21, 13, 47, 123456)
+        stamp = datetime_helpers.DatetimeWithNanoseconds(
+            2016, 12, 20, 21, 13, 47, 123456
+        )
         assert stamp.year == 2016
         assert stamp.month == 12
         assert stamp.day == 20
@@ -200,7 +243,9 @@ def test_ctor_w_micros_keyword_and_nanos():
 
     @staticmethod
     def test_rfc3339_wo_nanos():
-        stamp = datetime_helpers.DatetimeWithNanoseconds(2016, 12, 20, 21, 13, 47, 123456)
+        stamp = datetime_helpers.DatetimeWithNanoseconds(
+            2016, 12, 20, 21, 13, 47, 123456
+        )
         assert stamp.rfc3339() == "2016-12-20T21:13:47.123456Z"
 
     @staticmethod
@@ -285,12 +330,16 @@ def test_from_rfc3339_w_full_precision():
     )
     def test_from_rfc3339_test_nanoseconds(fractional, nanos):
         value = "2009-12-17T12:44:32.{}Z".format(fractional)
-        assert datetime_helpers.DatetimeWithNanoseconds.from_rfc3339(value).nanosecond == nanos
+        assert (
+            datetime_helpers.DatetimeWithNanoseconds.from_rfc3339(value).nanosecond
+            == nanos
+        )
 
     @staticmethod
     def test_timestamp_pb_wo_nanos_naive():
         stamp = datetime_helpers.DatetimeWithNanoseconds(
-            2016, 12, 20, 21, 13, 47, 123456)
+            2016, 12, 20, 21, 13, 47, 123456
+        )
         delta = stamp.replace(tzinfo=pytz.UTC) - datetime_helpers._UTC_EPOCH
         seconds = int(delta.total_seconds())
         nanos = 123456000
@@ -304,7 +353,8 @@ def test_timestamp_pb_w_nanos():
         )
         delta = stamp - datetime_helpers._UTC_EPOCH
         timestamp = timestamp_pb2.Timestamp(
-            seconds=int(delta.total_seconds()), nanos=123456789)
+            seconds=int(delta.total_seconds()), nanos=123456789
+        )
         assert stamp.timestamp_pb() == timestamp
 
     @staticmethod
@@ -314,8 +364,7 @@ def test_from_timestamp_pb_wo_nanos():
         seconds = int(delta.total_seconds())
         timestamp = timestamp_pb2.Timestamp(seconds=seconds)
 
-        stamp = datetime_helpers.DatetimeWithNanoseconds.from_timestamp_pb(
-            timestamp)
+        stamp = datetime_helpers.DatetimeWithNanoseconds.from_timestamp_pb(timestamp)
 
         assert _to_seconds(when) == _to_seconds(stamp)
         assert stamp.microsecond == 0
@@ -329,8 +378,7 @@ def test_from_timestamp_pb_w_nanos():
         seconds = int(delta.total_seconds())
         timestamp = timestamp_pb2.Timestamp(seconds=seconds, nanos=123456789)
 
-        stamp = datetime_helpers.DatetimeWithNanoseconds.from_timestamp_pb(
-            timestamp)
+        stamp = datetime_helpers.DatetimeWithNanoseconds.from_timestamp_pb(timestamp)
 
         assert _to_seconds(when) == _to_seconds(stamp)
         assert stamp.microsecond == 123456