Improve doc and tests for Decimal128Field

Author: bagerard

docs/changelog.rst

@@ -15,7 +15,9 @@ Development
 - Added meta ``auto_create_index_on_save`` so you can enable index creation
   on :meth:`~mongoengine.Document.save()` (as it was < 0.26.0).
 - BREAKING CHANGE: remove deprecated method ``ensure_index`` (replaced by ``create_index`` long time ago).
-
+- Addition of Decimal128Field: :class:`~mongoengine.fields.Decimal128Field` for accurate representation of Decimals (much better than the legacy field DecimalField).
+  Although it could work to switch an existing DecimalField to Decimal128Field without applying a migration script,
+  it is not recommended to do so (DecimalField uses float/str to store the value, Decimal128Field uses Decimal128).
 
 Changes in 0.25.0
 =================

mongoengine/fields.py

@@ -440,7 +440,10 @@ def prepare_query_value(self, op, value):
 
 
 class DecimalField(BaseField):
-    """Fixed-point decimal number field. Stores the value as a float by default unless `force_string` is used.
+    """Disclaimer: This field is kept for historical reason but since it converts the values to float, it
+    is not suitable for true decimal storage. Consider using :class:`~mongoengine.fields.Decimal128Field`.
+
+    Fixed-point decimal number field. Stores the value as a float by default unless `force_string` is used.
     If using floats, beware of Decimal to float conversion (potential precision loss)
     """
 
@@ -2655,6 +2658,11 @@ def to_mongo(self, document):
 
 
 class Decimal128Field(BaseField):
+    """
+    128-bit decimal-based floating-point field capable of emulating decimal
+    rounding with exact precision. This field will expose decimal.Decimal but stores the value as a
+    `bson.Decimal128` behind the scene, this field is intended for monetary data, scientific computations, etc.
+    """
 
     DECIMAL_CONTEXT = create_decimal128_context()
 
@@ -2663,13 +2671,6 @@ def __init__(self, min_value=None, max_value=None, **kwargs):
         self.max_value = max_value
         super().__init__(**kwargs)
 
-    """
-        128-bit decimal-based floating-point field capable of emulating decimal
-        rounding with exact precision. Stores the value as a `Decimal128`
-        intended for monetary data, such as financial, tax, and scientific
-        computations.
-    """
-
     def to_mongo(self, value):
         if value is None:
             return None

tests/fields/test_decimal128_field.py

@@ -5,7 +5,7 @@
 import pytest
 from bson.decimal128 import Decimal128
 
-from mongoengine import *
+from mongoengine import Decimal128Field, Document, ValidationError
 from tests.utils import MongoDBTestCase, get_as_pymongo
 
 
@@ -24,8 +24,6 @@ def generate_test_cls() -> Document:
 
 class TestDecimal128Field(MongoDBTestCase):
     def test_decimal128_validation_good(self):
-        """Ensure that invalid values cannot be assigned."""
-
         doc = Decimal128Document()
 
         doc.dec128_fld = Decimal(0)
@@ -37,7 +35,7 @@ def test_decimal128_validation_good(self):
         doc.dec128_fld = Decimal(110)
         doc.validate()
 
-        doc.dec128_fld = Decimal(110)
+        doc.dec128_fld = Decimal("110")
         doc.validate()
 
     def test_decimal128_validation_invalid(self):
@@ -76,22 +74,30 @@ def test_decimal128_validation_max(self):
 
     def test_eq_operator(self):
         cls = generate_test_cls()
-        assert 1 == cls.objects(dec128_fld=1.0).count()
-        assert 0 == cls.objects(dec128_fld=2.0).count()
+        assert cls.objects(dec128_fld=1.0).count() == 1
+        assert cls.objects(dec128_fld=2.0).count() == 0
 
     def test_ne_operator(self):
         cls = generate_test_cls()
-        assert 1 == cls.objects(dec128_fld__ne=None).count()
-        assert 1 == cls.objects(dec128_fld__ne=1).count()
-        assert 1 == cls.objects(dec128_fld__ne=1.0).count()
+        assert cls.objects(dec128_fld__ne=None).count() == 1
+        assert cls.objects(dec128_fld__ne=1).count() == 1
+        assert cls.objects(dec128_fld__ne=1.0).count() == 1
 
     def test_gt_operator(self):
         cls = generate_test_cls()
-        assert 1 == cls.objects(dec128_fld__gt=0.5).count()
+        assert cls.objects(dec128_fld__gt=0.5).count() == 1
 
     def test_lt_operator(self):
         cls = generate_test_cls()
-        assert 1 == cls.objects(dec128_fld__lt=1.5).count()
+        assert cls.objects(dec128_fld__lt=1.5).count() == 1
+
+    def test_field_exposed_as_python_Decimal(self):
+        # from int
+        model = Decimal128Document(dec128_fld=100).save()
+        assert isinstance(model.dec128_fld, Decimal)
+        model = Decimal128Document.objects.get(id=model.id)
+        assert isinstance(model.dec128_fld, Decimal)
+        assert model.dec128_fld == Decimal("100")
 
     def test_storage(self):
         # from int
@@ -101,6 +107,13 @@ def test_storage(self):
             "dec128_fld": Decimal128("100"),
         }
 
+        # from str
+        model = Decimal128Document(dec128_fld="100.0").save()
+        assert get_as_pymongo(model) == {
+            "_id": model.id,
+            "dec128_fld": Decimal128("100.0"),
+        }
+
         # from float
         model = Decimal128Document(dec128_fld=100.0).save()
         assert get_as_pymongo(model) == {
@@ -114,6 +127,11 @@ def test_storage(self):
             "_id": model.id,
             "dec128_fld": Decimal128("100"),
         }
+        model = Decimal128Document(dec128_fld=Decimal("100.0")).save()
+        assert get_as_pymongo(model) == {
+            "_id": model.id,
+            "dec128_fld": Decimal128("100.0"),
+        }
 
         # from Decimal128
         model = Decimal128Document(dec128_fld=Decimal128("100")).save()