Added ComplexDateTimeField

Thanks to @pelletier for the code.
Refs #187

docs/apireference.rst

@@ -53,6 +53,8 @@ Fields
 
 .. autoclass:: mongoengine.DateTimeField
 
+.. autoclass:: mongoengine.ComplexDateTimeField
+
 .. autoclass:: mongoengine.EmbeddedDocumentField
 
 .. autoclass:: mongoengine.DictField

mongoengine/fields.py

@@ -18,8 +18,9 @@ import gridfs
 __all__ = ['StringField', 'IntField', 'FloatField', 'BooleanField',
            'DateTimeField', 'EmbeddedDocumentField', 'ListField', 'DictField',
            'ObjectIdField', 'ReferenceField', 'ValidationError', 'MapField',
-           'DecimalField', 'URLField', 'GenericReferenceField', 'FileField',
+           'DecimalField', 'ComplexDateTimeField', 'URLField',
-           'BinaryField', 'SortedListField', 'EmailField', 'GeoPointField']
+           'GenericReferenceField', 'FileField', 'BinaryField',
+           'SortedListField', 'EmailField', 'GeoPointField']
 
 RECURSIVE_REFERENCE_CONSTANT = 'self'
 
@@ -273,6 +274,98 @@ class DateTimeField(BaseField):
                     return None
 
 
+class ComplexDateTimeField(StringField):
+    """
+    ComplexDateTimeField handles microseconds exactly instead of rounding
+    like DateTimeField does.
+
+    Derives from a StringField so you can do `gte` and `lte` filtering by
+    using lexicographical comparison when filtering / sorting strings.
+
+    The stored string has the following format:
+
+        YYYY,MM,DD,HH,MM,SS,NNNNNN
+
+    Where NNNNNN is the number of microseconds of the represented `datetime`.
+    The `,` as the separator can be easily modified by passing the `separator`
+    keyword when initializing the field.
+    """
+
+    def __init__(self, separator=',', **kwargs):
+        self.names = ['year', 'month', 'day', 'hour', 'minute', 'second',
+                      'microsecond']
+        self.separtor = separator
+        super(ComplexDateTimeField, self).__init__(**kwargs)
+
+    def _leading_zero(self, number):
+        """
+        Converts the given number to a string.
+
+        If it has only one digit, a leading zero so as it has always at least
+        two digits.
+        """
+        if int(number) < 10:
+            return "0%s" % number
+        else:
+            return str(number)
+
+    def _convert_from_datetime(self, val):
+        """
+        Convert a `datetime` object to a string representation (which will be
+        stored in MongoDB). This is the reverse function of
+        `_convert_from_string`.
+
+        >>> a = datetime(2011, 6, 8, 20, 26, 24, 192284)
+        >>> RealDateTimeField()._convert_from_datetime(a)
+        '2011,06,08,20,26,24,192284'
+        """
+        data = []
+        for name in self.names:
+            data.append(self._leading_zero(getattr(val, name)))
+        return ','.join(data)
+
+    def _convert_from_string(self, data):
+        """
+        Convert a string representation to a `datetime` object (the object you
+        will manipulate). This is the reverse function of
+        `_convert_from_datetime`.
+
+        >>> a = '2011,06,08,20,26,24,192284'
+        >>> ComplexDateTimeField()._convert_from_string(a)
+        datetime.datetime(2011, 6, 8, 20, 26, 24, 192284)
+        """
+        data = data.split(',')
+        data = map(int, data)
+        values = {}
+        for i in range(7):
+            values[self.names[i]] = data[i]
+        return datetime.datetime(**values)
+
+    def __get__(self, instance, owner):
+        data = super(ComplexDateTimeField, self).__get__(instance, owner)
+        if data == None:
+            return datetime.datetime.now()
+        return self._convert_from_string(data)
+
+    def __set__(self, obj, val):
+        data = self._convert_from_datetime(val)
+        return super(ComplexDateTimeField, self).__set__(obj, data)
+
+    def validate(self, value):
+        if not isinstance(value, datetime.datetime):
+            raise ValidationError('Only datetime objects may used in a \
+                                   ComplexDateTimeField')
+
+    def to_python(self, value):
+        return self._convert_from_string(value)
+
+    def to_mongo(self, value):
+        return self._convert_from_datetime(value)
+
+    def prepare_query_value(self, op, value):
+        return self._convert_from_datetime(value)
+
+
 class EmbeddedDocumentField(BaseField):
     """An embedded document field. Only valid values are subclasses of
     :class:`~mongoengine.EmbeddedDocument`.

tests/fields.py

@@ -247,6 +247,107 @@ class FieldTest(unittest.TestCase):
 
         LogEntry.drop_collection()
 
+    def test_complexdatetime_storage(self):
+        """Tests for complex datetime fields - which can handle microseconds
+        without rounding.
+        """
+        class LogEntry(Document):
+            date = ComplexDateTimeField()
+
+        LogEntry.drop_collection()
+
+        # Post UTC - microseconds are rounded (down) nearest millisecond and dropped - with default datetimefields
+        d1 = datetime.datetime(1970, 01, 01, 00, 00, 01, 999)
+        log = LogEntry()
+        log.date = d1
+        log.save()
+        log.reload()
+        self.assertEquals(log.date, d1)
+
+        # Post UTC - microseconds are rounded (down) nearest millisecond - with default datetimefields
+        d1 = datetime.datetime(1970, 01, 01, 00, 00, 01, 9999)
+        log.date = d1
+        log.save()
+        log.reload()
+        self.assertEquals(log.date, d1)
+
+        # Pre UTC dates microseconds below 1000 are dropped - with default datetimefields
+        d1 = datetime.datetime(1969, 12, 31, 23, 59, 59, 999)
+        log.date = d1
+        log.save()
+        log.reload()
+        self.assertEquals(log.date, d1)
+
+        # Pre UTC microseconds above 1000 is wonky - with default datetimefields
+        # log.date has an invalid microsecond value so I can't construct
+        # a date to compare.
+        for i in xrange(1001, 3113, 33):
+            d1 = datetime.datetime(1969, 12, 31, 23, 59, 59, i)
+            log.date = d1
+            log.save()
+            log.reload()
+            self.assertEquals(log.date, d1)
+            log1 = LogEntry.objects.get(date=d1)
+            self.assertEqual(log, log1)
+
+        LogEntry.drop_collection()
+
+    def test_complexdatetime_usage(self):
+        """Tests for complex datetime fields - which can handle microseconds
+        without rounding.
+        """
+        class LogEntry(Document):
+            date = ComplexDateTimeField()
+
+        LogEntry.drop_collection()
+
+        d1 = datetime.datetime(1970, 01, 01, 00, 00, 01, 999)
+        log = LogEntry()
+        log.date = d1
+        log.save()
+
+        log1 = LogEntry.objects.get(date=d1)
+        self.assertEquals(log, log1)
+
+        LogEntry.drop_collection()
+
+        # create 60 log entries
+        for i in xrange(1950, 2010):
+            d = datetime.datetime(i, 01, 01, 00, 00, 01, 999)
+            LogEntry(date=d).save()
+
+        self.assertEqual(LogEntry.objects.count(), 60)
+
+        # Test ordering
+        logs = LogEntry.objects.order_by("date")
+        count = logs.count()
+        i = 0
+        while i == count-1:
+            self.assertTrue(logs[i].date <= logs[i+1].date)
+            i +=1
+
+        logs = LogEntry.objects.order_by("-date")
+        count = logs.count()
+        i = 0
+        while i == count-1:
+            self.assertTrue(logs[i].date >= logs[i+1].date)
+            i +=1
+
+        # Test searching
+        logs = LogEntry.objects.filter(date__gte=datetime.datetime(1980,1,1))
+        self.assertEqual(logs.count(), 30)
+
+        logs = LogEntry.objects.filter(date__lte=datetime.datetime(1980,1,1))
+        self.assertEqual(logs.count(), 30)
+
+        logs = LogEntry.objects.filter(
+            date__lte=datetime.datetime(2011,1,1),
+            date__gte=datetime.datetime(2000,1,1),
+        )
+        self.assertEqual(logs.count(), 10)
+
+        LogEntry.drop_collection()
+
     def test_list_validation(self):
         """Ensure that a list field only accepts lists with valid elements.
         """