Implementing DateTimePropery in ndb. (#6448)

Author: dhermes

ndb/MIGRATION_NOTES.md

@@ -96,7 +96,8 @@ The primary differences come from:
 - The `BlobProperty` constructor only sets `_compressed` if explicitly
   passed. The original set `_compressed` always (and used `False` as default).
   In the exact same fashion the `JsonProperty` constructor only sets
-  `_json_type` if explicitly passed.
+  `_json_type` if explicitly passed. Similarly, the `DateTimeProperty`
+  constructor only sets `_auto_now` and `_auto_now_add` if explicitly passed.
 - `TextProperty(indexed=True)` and `StringProperty(indexed=False)` are no
   longer supported (see docstrings for more info)
 - `model.GeoPt` is an alias for `google.cloud.datastore.helpers.GeoPoint`

ndb/src/google/cloud/ndb/model.py

@@ -15,6 +15,7 @@
 """Model classes for datastore objects and properties for models."""
 
 
+import datetime
 import inspect
 import json
 import pickle
@@ -470,6 +471,11 @@ def _from_base_type(self, value):
       original value is kept. (Returning a different value not equal to
       :data:`None` will substitute the different value.)
 
+    Additionally, :meth:`_prepare_for_put` can be used to integrate with
+    datastore save hooks used by :class:`Model` instances.
+
+    .. automethod:: _prepare_for_put
+
     Args:
         name (str): The name of the property.
         indexed (bool): Indicates if the value should be indexed.
@@ -1749,8 +1755,8 @@ class BlobProperty(Property):
     def __init__(
         self,
         name=None,
-        compressed=None,
         *,
+        compressed=None,
         indexed=None,
         repeated=None,
         required=None,
@@ -2249,9 +2255,154 @@ def __init__(self, *args, **kwargs):
 
 
 class DateTimeProperty(Property):
-    __slots__ = ()
+    """A property that contains :class:`~datetime.datetime` values.
 
-    def __init__(self, *args, **kwargs):
+    This property expects "naive" datetime stamps, i.e. no timezone can
+    be set. Furthermore, the assumption is that naive datetime stamps
+    represent UTC.
+
+    .. note::
+
+        Unlike Django, ``auto_now_add`` can be overridden by setting the
+        value before writing the entity. And unlike the legacy
+        ``google.appengine.ext.db``, ``auto_now`` does not supply a default
+        value. Also unlike legacy ``db``, when the entity is written, the
+        property values are updated to match what was written. Finally, beware
+        that this also updates the value in the in-process cache, **and** that
+        ``auto_now_add`` may interact weirdly with transaction retries (a retry
+        of a property with ``auto_now_add`` set will reuse the value that was
+        set on the first try).
+
+    .. automethod:: _validate
+    .. automethod:: _prepare_for_put
+
+    Args:
+        name (str): The name of the property.
+        auto_now (bool): Indicates that the property should be set to the
+            current datetime when an entity is created and whenever it is
+            updated.
+        auto_now_add (bool): Indicates that the property should be set to the
+            current datetime when an entity is created.
+        indexed (bool): Indicates if the value should be indexed.
+        repeated (bool): Indicates if this property is repeated, i.e. contains
+            multiple values.
+        required (bool): Indicates if this property is required on the given
+            model type.
+        default (bytes): The default value for this property.
+        choices (Iterable[bytes]): A container of allowed values for this
+            property.
+        validator (Callable[[~google.cloud.ndb.model.Property, Any], bool]): A
+            validator to be used to check values.
+        verbose_name (str): A longer, user-friendly name for this property.
+        write_empty_list (bool): Indicates if an empty list should be written
+            to the datastore.
+
+    Raises:
+        ValueError: If ``repeated=True`` and ``auto_now=True``.
+        ValueError: If ``repeated=True`` and ``auto_now_add=True``.
+    """
+
+    _auto_now = False
+    _auto_now_add = False
+
+    def __init__(
+        self,
+        name=None,
+        *,
+        auto_now=None,
+        auto_now_add=None,
+        indexed=None,
+        repeated=None,
+        required=None,
+        default=None,
+        choices=None,
+        validator=None,
+        verbose_name=None,
+        write_empty_list=None
+    ):
+        super(DateTimeProperty, self).__init__(
+            name=name,
+            indexed=indexed,
+            repeated=repeated,
+            required=required,
+            default=default,
+            choices=choices,
+            validator=validator,
+            verbose_name=verbose_name,
+            write_empty_list=write_empty_list,
+        )
+        if self._repeated:
+            if auto_now:
+                raise ValueError(
+                    "DateTimeProperty {} could use auto_now and be "
+                    "repeated, but there would be no point.".format(self._name)
+                )
+            elif auto_now_add:
+                raise ValueError(
+                    "DateTimeProperty {} could use auto_now_add and be "
+                    "repeated, but there would be no point.".format(self._name)
+                )
+        if auto_now is not None:
+            self._auto_now = auto_now
+        if auto_now_add is not None:
+            self._auto_now_add = auto_now_add
+
+    def _validate(self, value):
+        """Validate a ``value`` before setting it.
+
+        Args:
+            value (~datetime.datetime): The value to check.
+
+        Raises:
+            .BadValueError: If ``value`` is not a :class:`~datetime.datetime`.
+        """
+        if not isinstance(value, datetime.datetime):
+            raise exceptions.BadValueError(
+                "Expected datetime, got {!r}".format(value)
+            )
+
+    @staticmethod
+    def _now():
+        """datetime.datetime: Return current time.
+
+        This is in place so it can be patched in tests.
+        """
+        return datetime.datetime.utcnow()
+
+    def _prepare_for_put(self, entity):
+        """Sets the current timestamp when "auto" is set.
+
+        If one of the following scenarios occur
+
+        * ``auto_now=True``
+        * ``auto_now_add=True`` and the ``entity`` doesn't have a value set
+
+        then this hook will run before the ``entity`` is ``put()`` into
+        the datastore.
+
+        Args:
+            entity (Model): An entity with values.
+        """
+        if self._auto_now or (
+            self._auto_now_add and not self._has_value(entity)
+        ):
+            value = self._now()
+            self._store_value(entity, value)
+
+    def _db_set_value(self, v, p, value):
+        """Helper for :meth:`_serialize`.
+
+        Raises:
+            NotImplementedError: Always. This method is virtual.
+        """
+        raise NotImplementedError
+
+    def _db_get_value(self, v, unused_p):
+        """Helper for :meth:`_deserialize`.
+
+        Raises:
+            NotImplementedError: Always. This method is virtual.
+        """
         raise NotImplementedError
 
 

ndb/tests/unit/test_model.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import datetime
 import pickle
 import types
 import unittest.mock
@@ -1797,9 +1798,121 @@ def test_constructor():
 
 class TestDateTimeProperty:
     @staticmethod
-    def test_constructor():
+    def test_constructor_defaults():
+        prop = model.DateTimeProperty()
+        # Check that none of the constructor defaults were used.
+        assert prop.__dict__ == {}
+
+    @staticmethod
+    def test_constructor_explicit():
+        now = datetime.datetime.utcnow()
+        prop = model.DateTimeProperty(
+            name="dt_val",
+            auto_now=True,
+            auto_now_add=False,
+            indexed=False,
+            repeated=False,
+            required=True,
+            default=now,
+            validator=TestProperty._example_validator,
+            verbose_name="VALUE FOR READING",
+            write_empty_list=False,
+        )
+        assert prop._name == b"dt_val" and prop._name != "dt_val"
+        assert prop._auto_now
+        assert not prop._auto_now_add
+        assert not prop._indexed
+        assert not prop._repeated
+        assert prop._required
+        assert prop._default == now
+        assert prop._choices is None
+        assert prop._validator is TestProperty._example_validator
+        assert prop._verbose_name == "VALUE FOR READING"
+        assert not prop._write_empty_list
+
+    @staticmethod
+    def test_constructor_repeated():
+        with pytest.raises(ValueError):
+            model.DateTimeProperty(name="dt_val", auto_now=True, repeated=True)
+        with pytest.raises(ValueError):
+            model.DateTimeProperty(
+                name="dt_val", auto_now_add=True, repeated=True
+            )
+
+        prop = model.DateTimeProperty(name="dt_val", repeated=True)
+        assert prop._repeated
+
+    @staticmethod
+    def test__validate():
+        prop = model.DateTimeProperty(name="dt_val")
+        value = datetime.datetime.utcnow()
+        assert prop._validate(value) is None
+
+    @staticmethod
+    def test__validate_invalid():
+        prop = model.DateTimeProperty(name="dt_val")
+        with pytest.raises(exceptions.BadValueError):
+            prop._validate(None)
+
+    @staticmethod
+    def test__now():
+        dt_val = model.DateTimeProperty._now()
+        assert isinstance(dt_val, datetime.datetime)
+
+    @staticmethod
+    def test__prepare_for_put():
+        prop = model.DateTimeProperty(name="dt_val")
+        entity = unittest.mock.Mock(_values={}, spec=("_values",))
+
+        with unittest.mock.patch.object(prop, "_now") as _now:
+            prop._prepare_for_put(entity)
+        assert entity._values == {}
+        _now.assert_not_called()
+
+    @staticmethod
+    def test__prepare_for_put_auto_now():
+        prop = model.DateTimeProperty(name="dt_val", auto_now=True)
+        values1 = {}
+        values2 = {prop._name: unittest.mock.sentinel.dt}
+        for values in (values1, values2):
+            entity = unittest.mock.Mock(_values=values, spec=("_values",))
+
+            with unittest.mock.patch.object(prop, "_now") as _now:
+                prop._prepare_for_put(entity)
+            assert entity._values == {prop._name: _now.return_value}
+            _now.assert_called_once_with()
+
+    @staticmethod
+    def test__prepare_for_put_auto_now_add():
+        prop = model.DateTimeProperty(name="dt_val", auto_now_add=True)
+        values1 = {}
+        values2 = {prop._name: unittest.mock.sentinel.dt}
+        for values in (values1, values2):
+            entity = unittest.mock.Mock(
+                _values=values.copy(), spec=("_values",)
+            )
+
+            with unittest.mock.patch.object(prop, "_now") as _now:
+                prop._prepare_for_put(entity)
+            if values:
+                assert entity._values == values
+                _now.assert_not_called()
+            else:
+                assert entity._values != values
+                assert entity._values == {prop._name: _now.return_value}
+                _now.assert_called_once_with()
+
+    @staticmethod
+    def test__db_set_value():
+        prop = model.DateTimeProperty(name="dt_val")
         with pytest.raises(NotImplementedError):
-            model.DateTimeProperty()
+            prop._db_set_value(None, None, None)
+
+    @staticmethod
+    def test__db_get_value():
+        prop = model.DateTimeProperty(name="dt_val")
+        with pytest.raises(NotImplementedError):
+            prop._db_get_value(None, None)
 
 
 class TestDateProperty: