Merge pull request #508 from MongoEngine/boolean_field

New model form generator: Support of BooleanField

Author: insspb

.sourcery.yaml

@@ -2,7 +2,8 @@ ignore: []
 
 refactor:
   include: []
-  skip: []
+  skip:
+    - use-contextlib-suppress
   rule_types:
     - refactoring
     - suggestion

docs/forms.md

@@ -85,7 +85,119 @@ Not yet documented. Please help us with new pull request.
 
 ### BooleanField
 
-Not yet documented. Please help us with new pull request.
+- API: {class}`.db_fields.BooleanField`
+- Default form field class: {class}`~.MongoBooleanField`
+
+#### Form generation behaviour
+
+BooleanField is very complicated in terms of Mongo database support. In
+Flask-Mongoengine before version **2.0.0+** database BooleanField used
+{class}`wtforms.fields.BooleanField` as form representation, this raised several not
+clear problems, that was related to how {class}`wtforms.fields.BooleanField` parse
+and work with form values. Known problems in version, before **2.0.0+**:
+
+- Default value of field, specified in database definition was ignored, if default
+  is `None` and nulls allowed, i.e. {attr}`null=True` (Value was always `False`).
+- Field was always created in database document, even if not checked, as there is
+  impossible to split `None` and `False` values, when only checkbox available.
+
+To fix all these issues, and do not create database field by default, Flask-Mongoengine
+**2.0.0+** uses dropdown field by default.
+
+By default, database BooleanField not allowing `None` value, meaning that field can
+be `True`, `False` or not created in database at all. If database field configuration
+allowing `None` values, i.e. {attr}`null=True`, then, when nothing selected in
+dropdown, the field will be created with `None` value.
+
+```{important}
+It is responsobility of developer, to correctly setup database field definition and
+make proper tests before own application release. BooleanField can create unexpected
+application behavior in if checks. Developer, should recheck all if checks like:
+
+- `if filed_value:` this will match `True` database value
+- `if not filed_value:` this will match `False` or `None` database value or not existing
+  document key
+- `if field_value is None:` this will match `None` database value or not existing
+  document key
+- `if field_value is True:` this will match `True` database value
+- `if field_value is False:` this will match `False` database value
+- `if field_value is not None:` this will match `True`, `False` database value
+- `if field_value is not True:` this will match `False`, `None` database value or not
+  existing document key
+- `if filed_value is not False:` this will match `True`, `None` database value or not
+  existing document key
+```
+
+#### Examples
+
+##### BooleanField with default dropdown
+
+Such definition will not create any field in document, if dropdown not selected.
+
+```python
+"""boolean_demo.py"""
+from example_app.models import db
+
+
+class BooleanDemoModel(db.Document):
+    """Documentation example model."""
+
+    boolean_field = db.BooleanField()
+```
+
+##### BooleanField with allowed `None` value
+
+Such definition will create document field, even if nothing selected. The value will
+be `None`. If, during edit, `yes` or `no` dropdown values replaced to `---`, then
+saved value in document will be aslo changed to `None`.
+
+By default, `None` value represented as `---` text in dropdown.
+
+```python
+"""boolean_demo.py"""
+from example_app.models import db
+
+
+class BooleanDemoModel(db.Document):
+    """Documentation example model."""
+
+    boolean_field_with_null = db.BooleanField(null=True)
+```
+
+##### BooleanField with replaced dropdown text
+
+Dropdown text can be easily replaced, there is only one requirement: New choices,
+should be correctly coerced by {func}`~.coerce_boolean`, or function should be
+replaced too.
+
+```python
+"""boolean_demo.py"""
+from example_app.models import db
+
+
+class BooleanDemoModel(db.Document):
+    """Documentation example model."""
+
+    boolean_field_with_as_choices_replace = db.BooleanField(
+        wtf_options={
+            "choices": [("", "Not selected"), ("yes", "Positive"), ("no", "Negative")]
+        }
+    )
+
+```
+
+##### BooleanField with default `True` value, but with allowed nulls
+
+```python
+"""boolean_demo.py"""
+from example_app.models import db
+
+
+class BooleanDemoModel(db.Document):
+    """Documentation example model."""
+
+    true_boolean_field_with_allowed_null = db.BooleanField(default=True, null=True)
+```
 
 ### ComplexDateTimeField
 
@@ -174,6 +286,8 @@ done, during field generation. Field is fully controllable by [global transforms
 dates_demo.py in example app contain basic non-requirement example. You can adjust
 it to any provided example for test purposes.
 
+##### Not limited DateField
+
 ```python
 """dates_demo.py"""
 from example_app.models import db
@@ -185,12 +299,6 @@ class DateTimeModel(db.Document):
     date = db.DateField()
 ```
 
-##### Not limited DateField
-
-```python
-pass
-```
-
 ### DateTimeField
 
 - API: {class}`.db_fields.DateTimeField`

example_app/app.py

@@ -3,6 +3,7 @@
 from pymongo import monitoring
 
 from example_app import views
+from example_app.boolean_demo import boolean_demo_view
 from example_app.dates_demo import dates_demo_view
 from example_app.models import db
 from example_app.numbers_demo import numbers_demo_view
@@ -49,6 +50,8 @@
 app.add_url_rule("/numbers/<pk>/", view_func=numbers_demo_view, methods=["GET", "POST"])
 app.add_url_rule("/dates", view_func=dates_demo_view, methods=["GET", "POST"])
 app.add_url_rule("/dates/<pk>/", view_func=dates_demo_view, methods=["GET", "POST"])
+app.add_url_rule("/bool", view_func=boolean_demo_view, methods=["GET", "POST"])
+app.add_url_rule("/bool/<pk>/", view_func=boolean_demo_view, methods=["GET", "POST"])
 
 if __name__ == "__main__":
     app.run(host="0.0.0.0", port=8000)

example_app/boolean_demo.py

@@ -0,0 +1,48 @@
+"""Booleans fields demo model."""
+
+from flask import render_template, request
+
+from example_app.models import db
+
+
+class BooleanDemoModel(db.Document):
+    """Documentation example model."""
+
+    simple_sting_name = db.StringField()
+    boolean_field = db.BooleanField()
+    boolean_field_with_null = db.BooleanField(null=True)
+    true_boolean_field_with_allowed_null = db.BooleanField(null=True, default=True)
+    boolean_field_with_as_choices_replace = db.BooleanField(
+        wtf_options={
+            "choices": [("", "Not selected"), ("yes", "Positive"), ("no", "Negative")]
+        }
+    )
+
+
+BooleanDemoForm = BooleanDemoModel.to_wtf_form()
+
+
+def boolean_demo_view(pk=None):
+    """Return all fields demonstration."""
+    form = BooleanDemoForm()
+    obj = None
+    if pk:
+        obj = BooleanDemoModel.objects.get(pk=pk)
+        form = BooleanDemoForm(obj=obj)
+
+    if request.method == "POST" and form.validate_on_submit():
+        if pk:
+            form.populate_obj(obj)
+            obj.save()
+        else:
+            form.save()
+    page_num = int(request.args.get("page") or 1)
+    page = BooleanDemoModel.objects.paginate(page=page_num, per_page=100)
+
+    return render_template(
+        "form_demo.html",
+        view=boolean_demo_view.__name__,
+        page=page,
+        form=form,
+        model=BooleanDemoModel,
+    )

example_app/templates/layout.html

@@ -21,6 +21,7 @@
     <li><a href="{{ url_for("strings_demo_view") }}">Strings demo</a></li>
     <li><a href="{{ url_for("numbers_demo_view") }}">Numbers demo</a></li>
     <li><a href="{{ url_for("dates_demo_view") }}">DateTime demo</a></li>
+    <li><a href="{{ url_for("boolean_demo_view") }}">Booleans demo</a></li>
   </ul>
 </nav>
 <div>

example_app/views.py

@@ -4,6 +4,7 @@
 from mongoengine.context_managers import switch_db
 
 from example_app import models
+from example_app.boolean_demo import BooleanDemoModel
 from example_app.dates_demo import DateTimeModel
 from example_app.numbers_demo import NumbersDemoModel
 from example_app.strings_demo import StringsDemoModel
@@ -50,6 +51,7 @@ def delete_data():
     """Clear database."""
     with switch_db(models.Todo, "default"):
         models.Todo.objects().delete()
+        BooleanDemoModel.objects().delete()
         DateTimeModel.objects().delete()
         StringsDemoModel.objects().delete()
         NumbersDemoModel.objects().delete()

flask_mongoengine/db_fields.py

@@ -329,21 +329,7 @@ class BooleanField(WtfFieldMixin, fields.BooleanField):
     All arguments should be passed as keyword arguments, to exclude unexpected behaviour.
     """
 
-    DEFAULT_WTF_FIELD = wtf_fields.BooleanField if wtf_fields else None
-    DEFAULT_WTF_CHOICES_COERCE = bool
-
-    def to_wtf_field(
-        self,
-        *,
-        model: Optional[Type] = None,
-        field_kwargs: Optional[dict] = None,
-    ):
-        """
-        Protection from execution of :func:`to_wtf_field` in form generation.
-
-        :raises NotImplementedError: Field converter to WTForm Field not implemented.
-        """
-        raise NotImplementedError("Field converter to WTForm Field not implemented.")
+    DEFAULT_WTF_FIELD = custom_fields.MongoBooleanField if custom_fields else None
 
 
 class CachedReferenceField(WtfFieldMixin, fields.CachedReferenceField):

flask_mongoengine/wtf/fields.py

@@ -6,6 +6,7 @@
     "QuerySetSelectField",
 ]
 from gettext import gettext as _
+from typing import Optional
 
 from flask import json
 from mongoengine.queryset import DoesNotExist
@@ -14,6 +15,23 @@
 from wtforms import widgets as wtf_widgets
 
 
+def coerce_boolean(value: Optional[str]) -> Optional[bool]:
+    """Transform SelectField boolean value from string and in reverse direction."""
+    try:
+        value = value.lower()
+    except AttributeError:
+        pass
+
+    if value is None or value in {"", "none", "null"}:
+        return None
+    elif value is False or value in {"no", "n", "false"}:
+        return False
+    elif value is True or value in {"yes", "y", "true"}:
+        return True
+    else:
+        raise ValueError("Unexpected string value.")
+
+
 # noinspection PyAttributeOutsideInit,PyAbstractClass
 class QuerySetSelectField(wtf_fields.SelectFieldBase):
     """
@@ -291,6 +309,40 @@ def process_formdata(self, valuelist):
             super().process_formdata(valuelist)
 
 
+class MongoBooleanField(wtf_fields.SelectField):
+    """Mongo SelectField field for BooleanFields, that correctly coerce values."""
+
+    def __init__(
+        self,
+        label=None,
+        validators=None,
+        coerce=None,
+        choices=None,
+        validate_choice=True,
+        **kwargs,
+    ):
+        """
+        Replaces defaults of :class:`wtforms.fields.SelectField` with for Boolean values.
+
+        Fully compatible with :class:`wtforms.fields.SelectField` and have same parameters.
+
+
+        """
+        if coerce is None:
+            coerce = coerce_boolean
+        if choices is None:
+            choices = [("", "---"), ("yes", "yes"), ("no", "no")]
+
+        super().__init__(
+            label=label,
+            validators=validators,
+            coerce=coerce,
+            choices=choices,
+            validate_choice=validate_choice,
+            **kwargs,
+        )
+
+
 class MongoEmailField(EmptyStringIsNoneMixin, wtf_fields.EmailField):
     """
     Regular :class:`wtforms.fields.EmailField`, that transform empty string to `None`.

tests/test_db_fields.py

@@ -149,7 +149,6 @@ def test__ensure_callable_or_list__raise_error_if_argument_not_callable_and_not_
         "FieldClass",
         [
             db_fields.BinaryField,
-            db_fields.BooleanField,
             db_fields.CachedReferenceField,
             db_fields.DictField,
             db_fields.DynamicField,

tests/test_forms_v2.py

@@ -18,6 +18,37 @@ def local_app(app):
         yield app
 
 
+@pytest.mark.parametrize(
+    ["value", "expected_value"],
+    [
+        ("", None),
+        ("none", None),
+        ("nOne", None),
+        ("None", None),
+        ("null", None),
+        (None, None),
+        ("no", False),
+        ("N", False),
+        ("n", False),
+        ("false", False),
+        ("False", False),
+        (False, False),
+        ("yes", True),
+        ("y", True),
+        ("true", True),
+        (True, True),
+    ],
+)
+def test_coerce_boolean__return_correct_value(value, expected_value):
+    assert mongo_fields.coerce_boolean(value) == expected_value
+
+
+def test_coerce_boolean__raise_on_unexpected_value():
+    with pytest.raises(ValueError) as error:
+        mongo_fields.coerce_boolean("some")
+    assert str(error.value) == "Unexpected string value."
+
+
 def test__full_document_form__does_not_create_any_unexpected_data_in_database(db):
     """
     Test to ensure that we are following own promise in documentation, read: