Introduce VietnamVehiclePlateField for Django

README.rst

@@ -2,7 +2,9 @@
 BienSoXe
 ========
 
-Library to parse and validate Vietnamese vehicle plate
+Library to validate and parse Vietnamese vehicle plate.
+
+This library is not a computer-vision-based license plate recognition software. It instead is used for validating output of such computer vision software. Imagine that you use camera to track all cars coming in and out of your parking lot, but you don't want to save false data generated from recognition process (due to wrong angle of canera, for example).
 
 Install
 -------
@@ -38,3 +40,24 @@ To format the plate number as in daily life, pass ``VietnamVehiclePlate`` to ``s
 
     >>> str(plate)
     '72-E1 011.30'
+
+Django
+~~~~~~
+
+This library provides a field type, ``VietnamVehiclePlateField``, for Django model. The field will return value as ``VietnamVehiclePlate`` object. Here is example:
+
+.. code-block:: python
+
+    from biensoxe.django import VietnamVehiclePlateField
+
+    class Vehicle(models.Model):
+        plate_number = VietnamVehiclePlateField(max_length=20, default='10A 00001', unique=True)
+
+    def __str__(self):
+        return str(self.plate_number) or self.pk
+
+Note that this field stores value internally as PostgeSQL ``CIText`` data type, so you can only use this field with PostgreSQL.
+You also need to activate CITextExtension_ your self.
+
+
+.. _CITextExtension: https://docs.djangoproject.com/en/2.2/ref/contrib/postgres/operations/#citextextension

biensoxe/__init__.py

@@ -1,3 +1,3 @@
-__version__ = '0.8.2'
+__version__ = '0.8.3'
 
 from .core import VietnamVehiclePlate, VehicleType   # NOQA

biensoxe/django/__init__.py

@@ -0,0 +1 @@
+from .fields import VietnamVehiclePlateField  # NOQA

biensoxe/django/fields.py

@@ -0,0 +1,47 @@
+"""Django model field to return VietnamVehiclePlate object."""
+
+from typing import Union, Optional
+
+from django.db.models import Expression
+from django.db.backends.postgresql.base import DatabaseWrapper
+from django.core.exceptions import ValidationError
+from django.contrib.postgres.fields import CICharField
+from django.utils.translation import gettext_lazy as _
+from biensoxe import VietnamVehiclePlate
+
+
+def parse_vehicleplate(number_string: str) -> VietnamVehiclePlate:
+    """Validate and parse input string to VietnamVehiclePlate object."""
+    try:
+        return VietnamVehiclePlate.from_string(number_string)
+    except ValueError:
+        raise ValidationError(_('Input string does not look like Vietname plate number'))
+
+
+class VietnamVehiclePlateField(CICharField):
+    """Field to store Vietnamese vehicle plate. Stored in PostgreSQL as CIText data type, to enable case-insensitive search.
+
+    Return data as VietnamVehiclePlate type from biensoxe library.
+    """
+
+    description = _('Field to store Vietnamese vehicle plate')
+
+    def from_db_value(self, value: Optional[str],
+                      expression: Expression, connection: DatabaseWrapper):
+        # Called in all circumstances when the data is loaded from the database,
+        # including in aggregates and values() calls.
+        if value is None:
+            return value
+        return parse_vehicleplate(value)
+
+    def to_python(self, value: Union[str, VietnamVehiclePlate, None]):
+        # Called by deserialization and during the clean() method used from forms.
+        if isinstance(value, VietnamVehiclePlate):
+            return value
+        if value is None:
+            return value
+        return parse_vehicleplate(value)
+
+    def get_prep_value(self, value: VietnamVehiclePlate):
+        # Convert Python object back to query value
+        return value.compact

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "biensoxe"
-version = "0.8.2"
+version = "0.8.3"
 description = "Library to parse and validate Vietnamese vehicle plate"
 authors = ["Nguyễn Hồng Quân <[email protected]>"]
 license = "MIT"
@@ -19,6 +19,7 @@ classifiers = [
     'Topic :: Software Development :: Libraries :: Python Modules',
     'Development Status :: 4 - Beta',
     'Intended Audience :: Developers',
+    'Framework :: Django :: 2.2',
 ]