Bump version to 6.8b5

In Django 4.2, `process_lhs()` is called for IsNull lookups,
which is how this bug came to appear. It was already there
and could be reproduced on Django 3.2.

The issue is when `LocalizedRef` is combined with a localized
lookup. The lookup is unaware of the existing localized ref
and adds another transform on top. This results in the
expression becoming:

```
field->'en'->'en'
```

.circleci/config.yml

@@ -1,31 +1,9 @@
 version: 2
 jobs:
-    test-python35:
-        docker:
-            - image: python:3.5-alpine
-            - image: postgres:11.0
-              environment:
-                  POSTGRES_DB: 'localizedfields'
-                  POSTGRES_USER: 'localizedfields'
-                  POSTGRES_PASSWORD: 'localizedfields'
-        steps:
-            - checkout
-            - run:
-                name: Install packages
-                command: apk add postgresql-libs gcc musl-dev postgresql-dev git
-            - run:
-                name: Install Python packages
-                command: pip install -r requirements/test.txt
-            - run:
-                name: Run tests
-                command: tox -e 'py35-dj{111,20,21}'
-                environment:
-                    DATABASE_URL: 'postgres://localizedfields:localizedfields@localhost:5432/localizedfields'
-
     test-python36:
         docker:
             - image: python:3.6-alpine
-            - image: postgres:11.0
+            - image: postgres:12.0
               environment:
                   POSTGRES_DB: 'localizedfields'
                   POSTGRES_USER: 'localizedfields'
@@ -35,19 +13,23 @@ jobs:
             - run:
                   name: Install packages
                   command: apk add postgresql-libs gcc musl-dev postgresql-dev git
+
             - run:
                   name: Install Python packages
-                command: pip install -r requirements/test.txt
+                  command: pip install --progress-bar off .[test]
+
             - run:
                   name: Run tests
-                command: tox -e 'py36-dj{111,20,21}'
+                  command: tox -e 'py36-dj{20,21,22,30,31,32}'
                   environment:
                       DATABASE_URL: 'postgres://localizedfields:localizedfields@localhost:5432/localizedfields'
 
+            - store_test_results:
+                  path: reports
     test-python37:
         docker:
             - image: python:3.7-alpine
-            - image: postgres:11.0
+            - image: postgres:12.0
               environment:
                   POSTGRES_DB: 'localizedfields'
                   POSTGRES_USER: 'localizedfields'
@@ -57,36 +39,152 @@ jobs:
             - run:
                   name: Install packages
                   command: apk add postgresql-libs gcc musl-dev postgresql-dev git
+
             - run:
                   name: Install Python packages
-                command: pip install -r requirements/test.txt
+                  command: pip install --progress-bar off .[test]
+
             - run:
                   name: Run tests
-                command: tox -e 'py37-dj{111,20,21}'
+                  command: tox -e 'py37-dj{20,21,22,30,31,32}'
                   environment:
                       DATABASE_URL: 'postgres://localizedfields:localizedfields@localhost:5432/localizedfields'
 
-    lint:
+            - store_test_results:
+                  path: reports
+    test-python38:
         docker:
-            - image: python:3.5-alpine
+            - image: python:3.8-alpine
+            - image: postgres:12.0
+              environment:
+                  POSTGRES_DB: 'localizedfields'
+                  POSTGRES_USER: 'localizedfields'
+                  POSTGRES_PASSWORD: 'localizedfields'
         steps:
             - checkout
             - run:
                 name: Install packages
                 command: apk add postgresql-libs gcc musl-dev postgresql-dev git
+
             - run:
                 name: Install Python packages
-                command: pip install -r requirements/test.txt
+                command: pip install --progress-bar off .[test]
+
             - run:
-                name: Lint code
-                command: python setup.py lint
+                name: Run tests
+                command: tox -e 'py38-dj{20,21,22,30,31,32,40,41,42}'
+                environment:
+                    DATABASE_URL: 'postgres://localizedfields:localizedfields@localhost:5432/localizedfields'
+
+            - store_test_results:
+                path: reports
+
+    test-python39:
+        docker:
+            - image: python:3.9-alpine
+            - image: postgres:12.0
+              environment:
+                  POSTGRES_DB: 'localizedfields'
+                  POSTGRES_USER: 'localizedfields'
+                  POSTGRES_PASSWORD: 'localizedfields'
+        steps:
+            - checkout
+            - run:
+                name: Install packages
+                command: apk add postgresql-libs gcc musl-dev postgresql-dev git
+
+            - run:
+                name: Install Python packages
+                command: pip install --progress-bar off .[test]
+
+            - run:
+                name: Run tests
+                command: tox -e 'py39-dj{30,31,32,40,41,42}'
+                environment:
+                    DATABASE_URL: 'postgres://localizedfields:localizedfields@localhost:5432/localizedfields'
+
+            - store_test_results:
+                path: reports
+
+    test-python310:
+        docker:
+            - image: python:3.10-alpine
+            - image: postgres:12.0
+              environment:
+                  POSTGRES_DB: 'localizedfields'
+                  POSTGRES_USER: 'localizedfields'
+                  POSTGRES_PASSWORD: 'localizedfields'
+        steps:
+            - checkout
+            - run:
+                  name: Install packages
+                  command: apk add postgresql-libs gcc musl-dev postgresql-dev git
+
+            - run:
+                  name: Install Python packages
+                  command: pip install --progress-bar off .[test]
+
+            - run:
+                  name: Run tests
+                  command: tox -e 'py310-dj{32,40,41,42,50}'
+                  environment:
+                      DATABASE_URL: 'postgres://localizedfields:localizedfields@localhost:5432/localizedfields'
+
+            - store_test_results:
+                  path: reports
+    test-python311:
+        docker:
+            - image: python:3.11-alpine
+            - image: postgres:12.0
+              environment:
+                  POSTGRES_DB: 'localizedfields'
+                  POSTGRES_USER: 'localizedfields'
+                  POSTGRES_PASSWORD: 'localizedfields'
+        steps:
+            - checkout
+            - run:
+                  name: Install packages
+                  command: apk add postgresql-libs gcc musl-dev postgresql-dev git
+
+            - run:
+                  name: Install Python packages
+                  command: pip install --progress-bar off .[test]
+
+            - run:
+                  name: Run tests
+                  command: tox -e 'py311-dj{42,50}'
+                  environment:
+                      DATABASE_URL: 'postgres://localizedfields:localizedfields@localhost:5432/localizedfields'
+
+            - store_test_results:
+                  path: reports
+
+    analysis:
+        docker:
+            - image: python:3.8-alpine
+        steps:
+            - checkout
+            - run:
+                name: Install packages
+                command: apk add postgresql-libs gcc musl-dev postgresql-dev git
+
+            - run:
+                name: Install Python packages
+                command: pip install --progress-bar off .[analysis]
+
+            - run:
+                name: Verify formatting / linting
+                command: python setup.py verify
 
 
 workflows:
     version: 2
     build:
         jobs:
-            - test-python35
             - test-python36
             - test-python37
-            - lint
+            - test-python38
+            - test-python39
+            - test-python310
+            - test-python311
+            - analysis

.gitignore

@@ -1,6 +1,7 @@
 # Ignore virtual environments
 env/
 .env/
+venv/
 
 # Ignore Python byte code cache
 *.pyc
@@ -9,11 +10,13 @@ __pycache__
 
 # Ignore coverage reports
 .coverage
-htmlcov
+reports/
 
 # Ignore build results
 *.egg-info/
 dist/
+build/
+pip-wheel-metadata
 
 # Ignore stupid .DS_Store
 .DS_Store

.readthedocs.yml

@@ -0,0 +1,10 @@
+version: 2
+
+sphinx:
+  builder: html
+  configuration: docs/source/conf.py
+
+python:
+  version: 3.7
+  install:
+    - requirements: requirements/docs.txt

README.md

@@ -0,0 +1,58 @@
+|  |  |                                                                                                                                                                             |
+|--------------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| :white_check_mark: | **Tests** | [![CircleCI](https://circleci.com/gh/SectorLabs/django-localized-fields/tree/master.svg?style=svg)](https://circleci.com/gh/SectorLabs/django-localized-fields/tree/master) |
+| :memo: | **License** | [![License](https://img.shields.io/:license-mit-blue.svg)](http://doge.mit-license.org)                                                                                     |
+| :package: | **PyPi** | [![PyPi](https://badge.fury.io/py/django-localized-fields.svg)](https://pypi.python.org/pypi/django-localized-fields)                                                       |
+| <img src="https://cdn.iconscout.com/icon/free/png-256/django-1-282754.png" width="22px" height="22px" align="center" /> | **Django Versions** | 2.0, 2.1, 2.2, 3.0, 3.1, 3.2, 4.0, 4.1, 4.2, 5.0                                                                                                                            |
+| <img src="http://www.iconarchive.com/download/i73027/cornmanthe3rd/plex/Other-python.ico" width="22px" height="22px" align="center" /> | **Python Versions** | 3.6, 3.7, 3.8, 3.9, 3.10, 3.11                                                                                                                                              |
+| :book: | **Documentation** | [Read The Docs](https://django-localized-fields.readthedocs.io)                                                                                                             |
+| :warning: | **Upgrade** | [Upgrade fom v5.x](https://django-localized-fields.readthedocs.io/en/latest/releases.html#v6-0)                                                                             
+| :checkered_flag: | **Installation** | [Installation Guide](https://django-localized-fields.readthedocs.io/en/latest/installation.html)                                                                            |
+
+`django-localized-fields` is an implementation of a field class for Django models that allows the field's value to be set in multiple languages. It does this by utilizing the ``hstore`` type (PostgreSQL specific), which is available as `models.HStoreField` since Django 1.10.
+
+---
+
+:warning: **This README is for v6. See the `v5.x` branch for v5.x.**
+
+---
+
+## Working with the code
+### Prerequisites
+
+* PostgreSQL 12 or newer.
+* Django 2.0 or newer.
+* Python 3.6 or newer.
+
+### Getting started
+
+1. Clone the repository:
+
+       λ git clone https://github.com/SectorLabs/django-localized-fields.git
+
+2. Create a virtual environment:
+
+       λ cd django-localized-fields
+       λ virtualenv env
+       λ source env/bin/activate
+
+3. Create a postgres user for use in tests (skip if your default user is a postgres superuser):
+
+       λ createuser --superuser localized_fields --pwprompt
+       λ export DATABASE_URL=postgres://localized_fields:<password>@localhost/localized_fields
+
+   Hint: if you're using virtualenvwrapper, you might find it beneficial to put
+   the ``export`` line in ``$VIRTUAL_ENV/bin/postactivate`` so that it's always
+   available when using this virtualenv.
+
+4. Install the development/test dependencies:
+
+       λ pip install ".[test]" ".[analysis]"
+
+5. Run the tests:
+
+       λ tox
+
+7. Auto-format code, sort imports and auto-fix linting errors:
+
+       λ python setup.py fix

README.rst

@@ -1,408 +0,0 @@
-django-localized-fields
-=======================
-
-.. image:: https://circleci.com/gh/SectorLabs/django-localized-fields.svg?style=svg
-    :target: https://circleci.com/gh/SectorLabs/django-localized-fields
-
-.. image:: https://img.shields.io/github/license/SectorLabs/django-localized-fields.svg
-    :target: https://github.com/SectorLabs/django-localized-fields/blob/master/LICENSE.md
-
-.. image:: https://badge.fury.io/py/django-localized-fields.svg
-    :target: https://pypi.python.org/pypi/django-localized-fields
-
-``django-localized-fields`` is an implementation of a field class for Django models that allows the field's value to be set in multiple languages. It does this by utilizing the ``hstore`` type (PostgreSQL specific), which is available as ``models.HStoreField`` since Django 1.10.
-
-This package requires Python 3.5 or newer, Django 1.11 or newer and PostgreSQL 9.6 or newer.
-
-Contributors
-------------
-
-* `seroy <https://github.com/seroy/>`_
-* `unaizalakain <https://github.com/unaizalakain/>`_
-
-Installation
-------------
-1. Install the package from PyPi:
-
-    .. code-block:: bash
-
-        $ pip install django-localized-fields
-
-2. Add ``localized_fields`` and ``django.contrib.postgres`` to your ``INSTALLED_APPS``:
-
-     .. code-block:: bash
-
-        INSTALLED_APPS = [
-            ...
-
-            'django.contrib.postgres',
-            'localized_fields.apps.LocalizedFieldsConfig'
-        ]
-
-3. Set the database engine to ``psqlextra.backend``:
-
-    .. code-block:: python
-
-        DATABASES = {
-            'default': {
-                ...
-                'ENGINE': 'psqlextra.backend'
-            }
-        }
-
-3. Set ``LANGUAGES` and `LANGUAGE_CODE`` in your settings:
-
-     .. code-block:: python
-
-         LANGUAGE_CODE = 'en' # default language
-         LANGUAGES = (
-             ('en', 'English'),
-             ('nl', 'Dutch'),
-             ('ro', 'Romanian')
-         )
-
-
-4. Apply migrations to enable the HStore extension:
-
-     .. code-block:: bash
-
-	 python manage.py migrate
-
-Usage
------
-
-Preparation
-^^^^^^^^^^^
-Declare fields on your model as ``LocalizedField``:
-
-.. code-block:: python
-
-     from localized_fields.fields import LocalizedField
-
-
-     class MyModel(models.Model):
-         title = LocalizedField()
-
-``django-localized-fields`` integrates with Django's i18n system, in order for certain languages to be available you have to correctly configure the ``LANGUAGES`` and ``LANGUAGE_CODE`` settings:
-
-.. code-block:: python
-
-     LANGUAGE_CODE = 'en' # default language
-     LANGUAGES = (
-          ('en', 'English'),
-          ('nl', 'Dutch'),
-          ('ro', 'Romanian')
-     )
-
-All the ``LocalizedField`` you define now will be available in the configured languages.
-
-Basic usage
-^^^^^^^^^^^
-.. code-block:: python
-
-     new = MyModel()
-     new.title.en = 'english title'
-     new.title.nl = 'dutch title'
-     new.title.ro = 'romanian title'
-     new.save()
-
-By changing the active language you can control which language is presented:
-
-.. code-block:: python
-
-     from django.utils import translation
-
-     translation.activate('nl')
-     print(new.title) # prints 'dutch title'
-
-     translation.activate('en')
-     print(new.title) # prints 'english title'
-
-Or get it in a specific language:
-
-.. code-block:: python
-
-     print(new.title.get('en')) # prints 'english title'
-     print(new.title.get('ro')) # prints 'romanian title'
-     print(new.title.get()) # whatever language is the primary one
-     print(new.title.get('ar', 'haha')) # prints 'haha' if there is no value in arabic
-
-You can also explicitly set a value in a certain language:
-
-.. code-block:: python
-
-     new.title.set('en', 'other english title')
-     new.title.set('nl', 'other dutch title')
-
-     new.title.ro = 'other romanian title'
-
-Constraints
-^^^^^^^^^^^
-
-**Required/Optional**
-
-Constraints are enforced on a database level.
-
-* Optional filling
-
-    .. code-block:: python
-
-        class MyModel(models.Model):
-            title = LocalizedField(blank=True, null=True, required=False)
-
-* Make translation required for any language
-
-    .. code-block:: python
-
-        class MyModel(models.Model):
-            title = LocalizedField(blank=False, null=False, required=False)
-
-* Make translation required for specific languages
-
-    .. code-block:: python
-
-        class MyModel(models.Model):
-            title = LocalizedField(blank=False, null=False, required=['en', 'ro'])
-
-* Make translation required for all languages
-
-    .. code-block:: python
-
-        class MyModel(models.Model):
-            title = LocalizedField(blank=False, null=False, required=True)
-
-* By default the primary language **required** and the others optional:
-
-    .. code-block:: python
-
-        class MyModel(models.Model):
-            title = LocalizedField()
-
-**Uniqueness**
-
-By default the values stored in a ``LocalizedField`` are *not unique*. You can enforce uniqueness for certain languages. This uniqueness constraint is enforced on a database level using a ``UNIQUE INDEX``.
-
-* Enforce uniqueness for one or more languages:
-
-    .. code-block:: python
-
-        class MyModel(models.Model):
-            title = LocalizedField(uniqueness=['en', 'ro'])
-
-* Enforce uniqueness for **all** languages:
-
-    .. code-block:: python
-
-        from localized_fields.util import get_language_codes
-
-        class MyModel(models.Model):
-            title = LocalizedField(uniqueness=get_language_codes())
-
-* Enforce uniqueness for one ore more languages **together** (similar to Django's ``unique_together``):
-
-    .. code-block:: python
-
-        class MyModel(models.Model):
-            title = LocalizedField(uniqueness=[('en', 'ro')])
-
-* Enforce uniqueness for **all** languages **together**:
-
-    .. code-block:: python
-
-        from localized_fields.util import get_language_codes
-
-        class MyModel(models.Model):
-            title = LocalizedField(uniqueness=[(*get_language_codes())])
-
-
-Other fields
-^^^^^^^^^^^^
-Besides ``LocalizedField``, there's also:
-
-* ``LocalizedUniqueSlugField``
-    Successor of ``LocalizedAutoSlugField`` that fixes concurrency issues and enforces
-    uniqueness of slugs on a database level. Usage is the exact same:
-
-          .. code-block:: python
-
-              from localized_fields.models import LocalizedModel
-              from localized_fields.fields import LocalizedField, LocalizedUniqueSlugField
-
-              class MyModel(LocalizedModel):
-                   title = LocalizedField()
-                   slug = LocalizedUniqueSlugField(populate_from='title')
-
-    ``populate_from`` can be:
-
-        - The name of a field.
-
-           .. code-block:: python
-
-               slug = LocalizedUniqueSlugField(populate_from='name', include_time=True)
-
-        - A callable.
-
-           .. code-block:: python
-
-               def generate_slug(instance):
-                   return instance.title
-
-               slug = LocalizedUniqueSlugField(populate_from=generate_slug, include_time=True)
-
-        - A tuple of names of fields.
-
-           .. code-block:: python
-
-               slug = LocalizedUniqueSlugField(populate_from=('name', 'beer') include_time=True)
-
-    By setting the option ``include_time=True``
-
-          .. code-block:: python
-
-               slug = LocalizedUniqueSlugField(populate_from='title', include_time=True)
-
-    You can instruct the field to include a part of the current time into
-    the resulting slug. This is useful if you're running into a lot of collisions.
-
-* ``LocalizedBleachField``
-     Automatically bleaches the content of the field.
-
-          * django-bleach
-
-     Example usage:
-
-           .. code-block:: python
-
-              from localized_fields.fields import LocalizedField, LocalizedBleachField
-
-              class MyModel(models.Model):
-                   title = LocalizedField()
-                   description = LocalizedBleachField()
-
-* ``LocalizedIntegerField``
-    This is an experimental field type introduced in version 5.0 and is subject to change. It also has
-    some pretty major downsides due to the fact that values are stored as strings and are converted
-    back and forth.
-
-    Allows storing integers in multiple languages. This works exactly like ``LocalizedField`` except that
-    all values must be integers. Do note that values are stored as strings in your database because
-    the backing field type is ``hstore``, which only allows storing strings. The ``LocalizedIntegerField``
-    takes care of ensuring that all values are integers and converts the stored strings back to integers
-    when retrieving them from the database. Do not expect to be able to do queries such as:
-
-        .. code-block:: python
-
-            MyModel.objects.filter(score__en__gt=1)
-
-
-* ``LocalizedCharField`` and ``LocalizedTextField``
-    These fields following the Django convention for string-based fields use the empty string as value for “no data”, not NULL.
-    ``LocalizedCharField`` uses ``TextInput`` (``<input type="text">``) widget for render.
-
-    Example usage:
-
-           .. code-block:: python
-
-              from localized_fields.fields import LocalizedCharField, LocalizedTextField
-
-              class MyModel(models.Model):
-                   title = LocalizedCharField()
-                   description = LocalizedTextField()
-
-* ``LocalizedFileField``
-    A file-upload field
-
-    Parameter ``upload_to`` supports ``lang`` parameter for string formatting or as function argument (in case if ``upload_to`` is callable).
-
-    Example usage:
-
-           .. code-block:: python
-
-              from localized_fields.fields import LocalizedFileField
-
-              def my_directory_path(instance, filename, lang):
-                # file will be uploaded to MEDIA_ROOT/<lang>/<id>_<filename>
-                return '{0}/{0}_{1}'.format(lang, instance.id, filename)
-
-              class MyModel(models.Model):
-                   file1 = LocalizedFileField(upload_to='uploads/{lang}/')
-                   file2 = LocalizedFileField(upload_to=my_directory_path)
-
-    In template you can access to file attributes:
-
-            .. code-block:: django
-
-              {# For current active language: #}
-
-              {{ model.file.url }}  {# output file url #}
-              {{ model.file.name }} {# output file name #}
-
-              {# Or get it in a specific language: #}
-
-              {{ model.file.ro.url }}  {# output file url for romanian language #}
-              {{ model.file.ro.name }} {# output file name for romanian language #}
-
-    To get access to file instance for current active language use ``localized`` method:
-
-            .. code-block:: python
-
-              model.file.localized()
-
-Experimental feature
-^^^^^^^^^^^^^^^^^^^^
-Enables the following experimental features:
-    * ``LocalizedField`` will return ``None`` instead of an empty ``LocalizedValue`` if there is no database value.
-    * ``LocalizedField`` lookups will lookup by currently active language instead of HStoreField
-
-.. code-block:: python
-
-     LOCALIZED_FIELDS_EXPERIMENTAL = True
-
-
-Django Admin Integration
-^^^^^^^^^^^^^^^^^^^^^^^^
-To enable widgets in the admin, you need to inherit from ``LocalizedFieldsAdminMixin``:
-
-.. code-block:: python
-
-    from django.contrib import admin
-    from myapp.models import MyLocalizedModel
-
-    from localized_fields.admin import LocalizedFieldsAdminMixin
-
-    class MyLocalizedModelAdmin(LocalizedFieldsAdminMixin, admin.ModelAdmin):
-        """Any admin options you need go here"""
-
-    admin.site.register(MyLocalizedModel, MyLocalizedModelAdmin)
-
-
-.. image:: ./images/admin-widget.png
-    :alt: The appearance of admin widget
-
-
-Frequently asked questions (FAQ)
---------------------------------
-
-1. Does this package work with Python 2?
-
-    No. Only Python 3.5 or newer is supported. We're using type hints. These do not work well under older versions of Python.
-
-2. With what Django versions does this package work?
-
-    Only Django 1.11 or newer is supported, this includes Django 2.X. This is because we rely on Django's ``HStoreField`` and template-based widget rendering.
-
-3. Does this package come with support for Django Admin?
-
-    Yes. Our custom fields come with a special form that will automatically be used in Django Admin if the field is of ``LocalizedField``.
-
-4. Why should I pick this over any of the other translation packages out there?
-
-    You should pick whatever you feel comfortable with. This package stores translations in your database without having to have translation tables. It however only works on PostgreSQL.
-
-5. I am using PostgreSQL <9.6, can I use this?
-
-    No. The ``hstore`` data type was introduced in PostgreSQL 9.6.
-
-6. I am using this package. Can I give you some beer?
-
-    Yes! If you're ever in the area of Cluj-Napoca, Romania, swing by :)

docs/.gitignore

@@ -0,0 +1 @@
+build/

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/conf.py

@@ -0,0 +1,10 @@
+import sphinx_rtd_theme
+
+project = 'django-localized-fields'
+copyright = '2019, Sector Labs'
+author = 'Sector Labs'
+extensions = ["sphinx_rtd_theme"]
+templates_path = ['_templates']
+exclude_patterns = []
+html_theme = "sphinx_rtd_theme"
+html_static_path = ['_static']

docs/source/constraints.rst

@@ -0,0 +1,100 @@
+.. _unique_together: https://docs.djangoproject.com/en/2.2/ref/models/options/#unique-together
+
+Constraints
+===========
+
+All constraints are enforced by PostgreSQL. Constraints can be applied to all fields documented in :ref:`Fields <fields>`.
+
+.. warning::
+
+    Don't forget to run ``python manage.py makemigrations`` after modifying constraints.
+
+Required/optional
+-----------------
+
+
+* Default language required and all other languages optional:
+
+
+    .. code-block:: python
+
+        class MyModel(models.Model):
+            title = LocalizedField()
+
+
+* All languages are optional and the field itself can be ``None``:
+
+    .. code-block:: python
+
+        class MyModel(models.Model):
+            title = LocalizedField(blank=True, null=True, required=False)
+
+* All languages are optional but the field itself cannot be ``None``:
+
+    .. code-block:: python
+
+        class MyModel(models.Model):
+            title = LocalizedField(blank=False, null=False, required=False)
+
+
+* Make specific languages required:
+
+    .. code-block:: python
+
+        class MyModel(models.Model):
+            title = LocalizedField(blank=False, null=False, required=['en', 'ro'])
+
+
+* Make all languages required:
+
+
+    .. code-block:: python
+
+        class MyModel(models.Model):
+            title = LocalizedField(blank=False, null=False, required=True)
+
+
+Uniqueness
+----------
+
+.. note::
+
+    Uniqueness is enforced by PostgreSQL by creating unique indexes on hstore keys. Keep this in mind when setting up unique constraints. If you already have a unique constraint in place, you do not have to add an additional index as uniqueness is enforced by creating an index.
+
+
+* Enforce uniqueness for one or more languages:
+
+    .. code-block:: python
+
+        class MyModel(models.Model):
+            title = LocalizedField(uniqueness=['en', 'ro'])
+
+
+* Enforce uniqueness for all languages:
+
+    .. code-block:: python
+
+        from localized_fields.util import get_language_codes
+
+        class MyModel(models.Model):
+            title = LocalizedField(uniqueness=get_language_codes())
+
+
+* Enforce uniqueness for one or more languages together:
+
+    .. code-block:: python
+
+        class MyModel(models.Model):
+            title = LocalizedField(uniqueness=[('en', 'ro')])
+
+    This is similar to Django's `unique_together`_.
+
+
+* Enforce uniqueness for all languages together:
+
+    .. code-block:: python
+
+        from localized_fields.util import get_language_codes
+
+        class MyModel(models.Model):
+            title = LocalizedField(uniqueness=[(*get_language_codes())])

docs/source/django_admin.rst

@@ -0,0 +1,19 @@
+Django Admin
+------------
+
+To display ``LocalizedFields`` as a tab bar in Django Admin; inherit your admin model class from ``LocalizedFieldsAdminMixin``:
+
+.. code-block:: python
+
+    from django.contrib import admin
+    from myapp.models import MyLocalizedModel
+
+    from localized_fields.admin import LocalizedFieldsAdminMixin
+
+    class MyLocalizedModelAdmin(LocalizedFieldsAdminMixin, admin.ModelAdmin):
+        """Any admin options you need go here"""
+
+    admin.site.register(MyLocalizedModel, MyLocalizedModelAdmin)
+
+
+.. image:: _static/django_admin_widget.png

docs/source/fields.rst

@@ -0,0 +1,99 @@
+.. _django.db.models.CharField: https://docs.djangoproject.com/en/2.2/ref/models/fields/#charfield
+.. _django.db.models.TextField: https://docs.djangoproject.com/en/2.2/ref/models/fields/#django.db.models.TextField
+.. _django.db.models.IntegerField: https://docs.djangoproject.com/en/2.2/ref/models/fields/#integerfield
+.. _django.db.models.FileField: https://docs.djangoproject.com/en/2.2/ref/models/fields/#filefield
+
+.. _fields:
+
+Localized fields
+================
+
+LocalizedField
+--------------
+
+Base localized fields. Stores content as strings of arbitrary lengths.
+
+.. code-block:: python
+
+    from localized_fields.fields import LocalizedField
+
+
+LocalizedCharField
+------------------
+
+Localized version of `django.db.models.CharField`_.
+
+Use this for single-line text content. Uses ``<input type="text" />`` when rendered as a widget.
+
+.. code-block:: python
+
+    from localized_fields.fields import LocalizedCharField
+
+Follows the same convention as `django.db.models.CharField`_ to store empty strings for "no data" and not NULL.
+
+
+LocalizedTextField
+------------------
+
+Localized version of `django.db.models.TextField`_.
+
+Use this for multi-line text content.
+
+.. code-block:: python
+
+    from localized_fields.fields import LocalizedTextField
+
+Follows the same convention as `django.db.models.TextField`_ to store empty strings for "no data" and not NULL.
+
+
+LocalizedFileField
+------------------
+
+Localized version of `django.db.models.FileField`_.
+
+.. code-block:: python
+
+    from localized_fields.fields import LocalizedFileField
+
+    def my_directory_path(instance, filename, lang):
+      # file will be uploaded to MEDIA_ROOT/<lang>/<id>_<filename>
+      return '{0}/{0}_{1}'.format(lang, instance.id, filename)
+
+    class MyModel(models.Model):
+         file1 = LocalizedFileField(upload_to='uploads/{lang}/')
+         file2 = LocalizedFileField(upload_to=my_directory_path)
+
+
+The ``upload_to`` supports the ``{lang}}`` placeholder for string formatting or as function argument (in case if upload_to is a callable).
+
+In a template, you can access the files for different languages:
+
+.. code-block:: html
+
+    {# For current active language: #}
+
+    {{ model.file.url }}  {# output file url #}
+    {{ model.file.name }} {# output file name #}
+
+    {# Or get it in a specific language: #}
+
+    {{ model.file.ro.url }}  {# output file url for romanian language #}
+    {{ model.file.ro.name }} {# output file name for romanian language #}
+
+To get the file instance for the current language:
+
+.. code-block:: python
+
+    model.file.localized()
+
+
+LocalizedIntegerField
+---------------------
+
+Localized version of `django.db.models.IntegerField`_.
+
+.. code-block:: python
+
+    from localized_fields.fields import LocalizedIntegerField
+
+Although the underlying PostgreSQL data type for ``LocalizedField`` is hstore (which only stores strings). ``LocalizedIntegerField`` takes care of making sure that input values are integers and casts the values back to integers when querying them.

docs/source/filtering.rst

@@ -0,0 +1,44 @@
+Filtering localized content
+===========================
+
+.. note::
+
+    All examples below assume a model declared like this:
+
+    .. code-block:: python
+
+        from localized_fields.models import LocalizedModel
+        from localized_fields.fields import LocalizedField
+
+
+        class MyModel(LocalizedModel):
+            title = LocalizedField()
+
+
+Active language
+----------------
+
+.. code-block:: python
+
+    from django.utils import translation
+
+    # filter in english
+    translation.activate("en")
+    MyModel.objects.filter(title="test")
+
+    # filter in dutch
+    translation.activate("nl")
+    MyModel.objects.filter(title="test")
+
+
+Specific language
+-----------------
+
+.. code-block:: python
+
+    MyModel.objects.filter(title__en="test")
+    MyModel.objects.filter(title__nl="test")
+
+    # do it dynamically, where the language code is a var
+    lang_code = "nl"
+    MyModel.objects.filter(**{"title_%s" % lang_code: "test"})

docs/source/index.rst

@@ -0,0 +1,22 @@
+Welcome
+=======
+
+``django-localized-fields`` is a Django library that provides fields to store localized content (content in various languages) in a PostgreSQL database. It does this by utilizing the PostgreSQL ``hstore`` type, which is available in Django as ``HStoreField`` since Django 1.10.
+
+This package requires Python 3.6 or newer, Django 2.0 or newer and PostgreSQL 10 or newer.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Overview
+
+   installation
+   quick_start
+   constraints
+   fields
+   saving
+   querying
+   filtering
+   localized_value
+   django_admin
+   settings
+   releases

docs/source/installation.rst

@@ -0,0 +1,73 @@
+.. _installation:
+
+Installation
+============
+
+1. Install the package from PyPi:
+
+    .. code-block:: bash
+
+        $ pip install django-localized-fields
+
+2. Add ``django.contrib.postgres``, ``psqlextra`` and ``localized_fields`` to your ``INSTALLED_APPS``:
+
+    .. code-block:: python
+
+        INSTALLED_APPS = [
+            ...
+            "django.contrib.postgres",
+            "psqlextra",
+            "localized_fields",
+        ]
+
+
+3. Set the database engine to ``psqlextra.backend``:
+
+    .. code-block:: python
+
+        DATABASES = {
+            "default": {
+                ...
+                "ENGINE": "psqlextra.backend",
+            ],
+        }
+
+    .. note::
+
+        Already using a custom back-end? Set ``POSTGRES_EXTRA_DB_BACKEND_BASE`` to your custom back-end. See django-postgres-extra's documentation for more details: `Using a custom database back-end <https://django-postgres-extra.readthedocs.io/en/latest/db-engine/#using-a-custom-database-back-end>`_.
+
+4. Set ``LANGUAGES`` and ``LANGUAGE_CODE``:
+
+    .. code-block:: python
+
+        LANGUAGE_CODE = "en" # default language
+        LANGUAGES = (
+            ("en", "English"), # default language
+            ("ar", "Arabic"),
+            ("ro", "Romanian"),
+        )
+
+
+    .. warning::
+
+        Make sure that the language specified in ``LANGUAGE_CODE`` is the first language in the ``LANGUAGES`` list. Django and many third party packages assume that the default language is the first one in the list.
+
+5. Apply migrations to enable the HStore extension:
+
+    .. code-block:: bash
+
+        $ python manage.py migrate
+
+    .. note::
+
+        Migrations might fail to be applied if the PostgreSQL user applying the migration is not a super user. Enabling/creating extensions requires superuser permission. Not a superuser? Ask your database administrator to create the ``hstore`` extension on your PostgreSQL server manually using the following statement:
+
+            .. code-block:: sql
+
+                CREATE EXTENSION IF NOT EXISTS hstore;
+
+        Then, fake apply the migration to tell Django that the migration was applied already:
+
+            .. code-block:: bash
+
+                python manage.py migrate localized_fields --fake

docs/source/localized_value.rst

@@ -0,0 +1,79 @@
+Working with localized values
+=============================
+
+.. note::
+
+    All examples below assume a model declared like this:
+
+    .. code-block:: python
+
+        from localized_fields.models import LocalizedModel
+        from localized_fields.fields import LocalizedField
+
+
+        class MyModel(LocalizedModel):
+            title = LocalizedField()
+
+Localized content is represented by ``localized_fields.value.LocalizedValue``. Which is essentially a dictionary where the key is the language and the value the content in the respective language.
+
+.. code-block:: python
+
+    from localized_fields.value import LocalizedValue
+
+    obj = MyModel.objects.first()
+    assert isistance(obj.title, LocalizedValue) # True
+
+
+With fallback
+-------------
+
+.. seealso::
+
+    Configure :ref:`LOCALIZED_FIELDS_FALLBACKS <LOCALIZED_FIELDS_FALLBACKS>` to control the fallback behaviour.
+
+
+Active language
+***************
+
+.. code-block:: python
+
+    # gets content in Arabic, falls back to next language
+    # if not availble
+    translation.activate('ar')
+    obj.title.translate()
+
+    # alternative: cast to string
+    title_ar = str(obj.title)
+
+
+Specific language
+*****************
+
+.. code-block:: python
+
+    # gets content in Arabic, falls back to next language
+    # if not availble
+    obj.title.translate('ar')
+
+
+Without fallback
+----------------
+
+Specific language
+*****************
+
+.. code-block:: python
+
+    # gets content in Dutch, None if not available
+    # no fallback to secondary languages here!
+    obj.title.nl
+
+
+Specific language dynamically
+*****************************
+
+.. code-block:: python
+
+    # gets content in Dutch, None if not available
+    # no fallback to secondary languages here!
+    obj.title.get('nl')

docs/source/querying.rst

@@ -0,0 +1,59 @@
+Querying localized content
+==========================
+
+.. note::
+
+    All examples below assume a model declared like this:
+
+    .. code-block:: python
+
+        from localized_fields.models import LocalizedModel
+        from localized_fields.fields import LocalizedField
+
+
+        class MyModel(LocalizedModel):
+            title = LocalizedField()
+
+
+Active language
+---------------
+
+Only need a value in a specific language? Use the ``LocalizedRef`` expression to query a value in the currently active language:
+
+.. code-block:: python
+
+    from localized_fields.expressions import LocalizedRef
+
+    MyModel.objects.create(title=dict(en="Hello", nl="Hallo"))
+
+    translation.activate("nl")
+    english_title = (
+        MyModel
+        .objects
+        .annotate(title=LocalizedRef("title"))
+        .values_list("title", flat=True)
+        .first()
+    )
+
+    print(english_title) # prints "Hallo"
+
+
+Specific language
+-----------------
+
+.. code-block:: python
+
+    from localized_fields.expressions import LocalizedRef
+
+    result = (
+        MyModel
+        .objects
+        .values(
+            'title__en',
+            'title__nl',
+        )
+        .first()
+    )
+
+    print(result['title__en'])
+    print(result['title__nl'])

docs/source/quick_start.rst

@@ -0,0 +1,140 @@
+.. _django.utils.translation.override: https://docs.djangoproject.com/en/2.2/ref/utils/#django.utils.translation.override
+.. _django.db.models.TextField: https://docs.djangoproject.com/en/2.2/ref/models/fields/#django.db.models.TextField
+.. _LANGUAGES: https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-LANGUAGE_CODE
+.. _LANGUAGE_CODE: https://docs.djangoproject.com/en/2.2/ref/settings/#languages
+
+Quick start
+===========
+
+.. warning::
+
+    This assumes you have followed the :ref:`Installation guide <installation>`.
+
+``django-localized-fields`` provides various model field types to store content in multiple languages. The most basic of them all is ``LocalizedField`` which stores text of arbitrary length (like `django.db.models.TextField`_).
+
+Declaring a model
+-----------------
+
+.. code-block:: python
+
+    from localized_fields.models import LocalizedModel
+    from localized_fields.fields import LocalizedField
+
+
+    class MyModel(LocalizedModel):
+        title = LocalizedField()
+
+
+This creates a model with one localized field. Inside the ``LocalizedField``, strings can be stored in multiple languages. There are more fields like this for different data types (integers, images etc). ``LocalizedField`` is the most basic of them all.
+
+Saving localized content
+------------------------
+
+You can now save text in ``MyModel.title`` in all languages you defined in the `LANGUAGES`_ setting. A short example:
+
+.. code-block:: python
+
+    newobj = MyModel()
+    newobj.title.en = "Hello"
+    newobj.title.ar = "مرحبا"
+    newobj.title.nl = "Hallo"
+    newobj.save()
+
+There are various other ways of saving localized content. For example, all fields can be set at once by assigning a ``dict``:
+
+.. code-block:: python
+
+    newobj = MyModel()
+    newobj.title = dict(en="Hello", ar="مرحبا", nl="Hallo")
+    newobj.save()
+
+This also works when using the ``create`` function:
+
+.. code-block:: python
+
+    newobj = MyModel.objects.create(title=dict(en="Hello", ar="مرحبا", nl="Hallo"))
+
+Need to set the content dynamically? Use the ``set`` function:
+
+.. code-block:: python
+
+    newobj = MyModel()
+    newobj.title.set("en", "Hello")
+
+.. note::
+
+    Localized field values (``localized_fields.value.LocalizedValue``) act like dictionaries. In fact, ``LocalizedValue`` extends ``dict``. Anything that works on a ``dict`` works on ``LocalizedValue``.
+
+Retrieving localized content
+----------------------------
+
+When querying, the currently active language is taken into account. If there is no active language set, the default language is returned (set by the `LANGUAGE_CODE`_ setting).
+
+.. code-block:: python
+
+    from django.utils import translation
+
+    obj = MyModel.objects.first()
+
+    print(obj.title) # prints "Hello"
+
+    translation.activate("ar")
+    print(obj.title) # prints "مرحبا"
+    str(obj.title) # same as printing, forces translation to active language
+
+    translation.activate("nl")
+    print(obj.title) # prints "Hallo"
+
+
+.. note::
+
+    Use `django.utils.translation.override`_ to change the language for just a block of code rather than setting the language globally:
+
+    .. code-block:: python
+
+        from django.utils import translation
+
+        with translation.override("nl"):
+            print(obj.title) # prints "Hallo"
+
+
+Fallback
+********
+
+If there is no content for the currently active language, a fallback kicks in where the content will be returned in the next language. The fallback order is controlled by the order set in the `LANGUAGES`_ setting.
+
+.. code-block:: python
+
+    obj = MyModel.objects.create(dict(en="Hallo", ar="مرحبا"))
+
+    translation.activate("nl")
+    print(obj.title) # prints "مرحبا" because there"s no content in NL
+
+.. seealso::
+
+    Use the :ref:`LOCALIZED_FIELDS_FALLBACKS <LOCALIZED_FIELDS_FALLBACKS>` setting to control the fallback behaviour.
+
+
+Cast to str
+***********
+
+Want to get the value in the currently active language without casting to ``str``? (For null-able fields for example). Use the ``.translate()`` function:
+
+.. code-block:: python
+
+    obj = MyModel.objects.create(dict(en="Hallo", ar="مرحبا"))
+
+    str(obj.title) == obj.title.translate() # True
+
+.. note::
+
+    ``str(..)`` is guarenteed to return a string. If the value is ``None``, ``str(..)`` returns an empty string. ``translate()`` would return ``None``. This is because Python forces the ``__str__`` function to return a string.
+
+    .. code-block:: python
+
+        obj = MyModel.objects.create(dict(en="Hallo"))
+
+        translation.activate('nl')
+
+        str(obj.title) # ""
+        obj.title.translate() # None

docs/source/releases.rst

@@ -0,0 +1,22 @@
+Releases
+========
+
+v6.0
+----
+
+Breaking changes
+****************
+
+* Removes support for Python 3.6 and earlier.
+* Removes support for PostgreSQL 9.6 and earlier.
+* Sets ``LOCALIZED_FIELDS_EXPERIMENTAL`` to ``True`` by default.
+
+Bug fixes
+*********
+
+* Fixes a bug where ``LocalizedIntegerField`` could not be used in ``order_by``.
+
+Other
+*****
+
+* ``LocalizedValue.translate()`` can now takes an optional ``language`` parameter.

docs/source/saving.rst

@@ -0,0 +1,82 @@
+Saving localized content
+========================
+
+.. note::
+
+    All examples below assume a model declared like this:
+
+    .. code-block:: python
+
+        from localized_fields.models import LocalizedModel
+        from localized_fields.fields import LocalizedField
+
+
+        class MyModel(LocalizedModel):
+            title = LocalizedField()
+
+
+Individual assignment
+*********************
+
+.. code-block:: python
+
+    obj = MyModel()
+    obj.title.en = 'Hello'
+    obj.title.nl = 'Hallo'
+    obj.save()
+
+
+Individual dynamic assignment
+*****************************
+
+.. code-block:: python
+
+    obj = MyModel()
+    obj.title.set('en', 'Hello')
+    obj.title.set('nl', 'Hallo')
+    obj.save()
+
+
+Multiple assignment
+*******************
+
+.. code-block:: python
+
+    obj = MyModel()
+    obj.title = dict(en='Hello', nl='Hallo')
+    obj.save()
+
+    obj = MyModel(title=dict(en='Hello', nl='Hallo'))
+    obj.save()
+
+    obj = MyModel.objects.create(title=dict(en='Hello', nl='Hallo'))
+
+
+Default language assignment
+***************************
+
+.. code-block:: python
+
+    obj = MyModel()
+    obj.title = 'Hello' # assumes value is in default language
+    obj.save()
+
+    obj = MyModel(title='Hello') # assumes value is in default language
+    obj.save()
+
+    obj = MyModel.objects.create(title='title') # assumes value is in default language
+
+
+Array assignment
+****************
+
+.. code-block:: python
+
+    obj = MyModel()
+    obj.title = ['Hello', 'Hallo'] # order according to LANGUAGES
+    obj.save()
+
+    obj = MyModel(title=['Hello', 'Hallo']) # order according to LANGUAGES
+    obj.save()
+
+    obj = MyModel.objects.create(title=['Hello', 'Hallo']) # order according to LANGUAGES

docs/source/settings.rst

@@ -0,0 +1,39 @@
+.. _LANGUAGES: https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-LANGUAGE_CODE
+.. _LANGUAGE_CODE: https://docs.djangoproject.com/en/2.2/ref/settings/#languages
+
+Settings
+========
+
+.. LOCALIZED_FIELDS_EXPERIMENTAL:
+
+* ``LOCALIZED_FIELDS_EXPERIMENTAL``
+
+    .. note::
+
+        Disabled in v5.x and earlier. Enabled by default since v6.0.
+
+    When enabled:
+
+    * ``LocalizedField`` will return ``None`` instead of an empty ``LocalizedValue`` if there is no database value.
+    * ``LocalizedField`` lookups will by the currently active language instead of an exact match by dict.
+
+
+.. _LOCALIZED_FIELDS_FALLBACKS:
+
+* ``LOCALIZED_FIELDS_FALLBACKS``
+
+    List of language codes which define the order in which fallbacks should happen. If a value is not available in a specific language, we'll try to pick the value in the next language in the list.
+
+    .. warning::
+
+        If this setting is not configured, the default behaviour is to fall back to the value in the **default language**. It is recommended to configure this setting to get predictible fallback behaviour that suits your use case.
+
+        Use the same language codes as you used for configuring the `LANGUAGES`_ and `LANGUAGE_CODE`_ setting.
+
+    .. code-block:: python
+
+        LOCALIZED_FIELDS_FALLBACKS = {
+            "en": ["nl", "ar"], # if trying to get EN, but not available, try NL and then AR
+            "nl": ["en", "ar"], # if trying to get NL, but not available, try EN and then AR
+            "ar": ["en", "nl"], # if trying to get AR, but not available, try EN and then NL
+        }

localized_fields/__init__.py

@@ -1 +1,4 @@
-default_app_config = 'localized_fields.apps.LocalizedFieldsConfig'
+import django
+
+if django.VERSION < (3, 2):
+    default_app_config = "localized_fields.apps.LocalizedFieldsConfig"

localized_fields/admin.py

@@ -1,13 +1,18 @@
 from . import widgets
-from .fields import LocalizedField, LocalizedCharField, LocalizedTextField, \
-    LocalizedFileField
-
+from .fields import (
+    LocalizedBooleanField,
+    LocalizedCharField,
+    LocalizedField,
+    LocalizedFileField,
+    LocalizedTextField,
+)
 
 FORMFIELD_FOR_LOCALIZED_FIELDS_DEFAULTS = {
-    LocalizedField: {'widget': widgets.AdminLocalizedFieldWidget},
-    LocalizedCharField: {'widget': widgets.AdminLocalizedCharFieldWidget},
-    LocalizedTextField: {'widget': widgets.AdminLocalizedFieldWidget},
-    LocalizedFileField: {'widget': widgets.AdminLocalizedFileFieldWidget},
+    LocalizedField: {"widget": widgets.AdminLocalizedFieldWidget},
+    LocalizedCharField: {"widget": widgets.AdminLocalizedCharFieldWidget},
+    LocalizedTextField: {"widget": widgets.AdminLocalizedFieldWidget},
+    LocalizedFileField: {"widget": widgets.AdminLocalizedFileFieldWidget},
+    LocalizedBooleanField: {"widget": widgets.AdminLocalizedBooleanFieldWidget},
 }
 
 
@@ -15,15 +20,11 @@ class LocalizedFieldsAdminMixin:
     """Mixin for making the fancy widgets work in Django Admin."""
 
     class Media:
-        css = {
-            'all': (
-                'localized_fields/localized-fields-admin.css',
-            )
-        }
+        css = {"all": ("localized_fields/localized-fields-admin.css",)}
 
         js = (
-            'admin/js/jquery.init.js',
-            'localized_fields/localized-fields-admin.js',
+            "admin/js/jquery.init.js",
+            "localized_fields/localized-fields-admin.js",
         )
 
     def __init__(self, *args, **kwargs):

localized_fields/apps.py

@@ -9,10 +9,10 @@ from .lookups import LocalizedLookupMixin
 
 
 class LocalizedFieldsConfig(AppConfig):
-    name = 'localized_fields'
+    name = "localized_fields"
 
     def ready(self):
-        if getattr(settings, 'LOCALIZED_FIELDS_EXPERIMENTAL', False):
+        if getattr(settings, "LOCALIZED_FIELDS_EXPERIMENTAL", True):
             for _, clazz in inspect.getmembers(lookups):
                 if not inspect.isclass(clazz) or clazz is LocalizedLookupMixin:
                     continue

localized_fields/descriptor.py

@@ -1,10 +1,9 @@
 from django.conf import settings
-from django.utils import six, translation
+from django.utils import translation
 
 
 class LocalizedValueDescriptor:
-    """
-    The descriptor for the localized value attribute on the model instance.
+    """The descriptor for the localized value attribute on the model instance.
     Returns a :see:LocalizedValue when accessed so you can do stuff like::
 
         >>> from myapp.models import MyModel
@@ -58,8 +57,10 @@ class LocalizedValueDescriptor:
         return instance.__dict__[self.field.name]
 
     def __set__(self, instance, value):
-        if isinstance(value, six.string_types):
+        if isinstance(value, str):
             language = translation.get_language() or settings.LANGUAGE_CODE
-            self.__get__(instance).set(language, value)  # pylint: disable=no-member
+            self.__get__(instance).set(
+                language, value
+            )  # pylint: disable=no-member
         else:
             instance.__dict__[self.field.name] = value

localized_fields/expressions.py

@@ -1,12 +1,11 @@
 from django.conf import settings
 from django.utils import translation
-
 from psqlextra import expressions
 
 
 class LocalizedRef(expressions.HStoreRef):
-    """Expression that selects the value in a field only in
-    the currently active language."""
+    """Expression that selects the value in a field only in the currently
+    active language."""
 
     def __init__(self, name: str, lang: str = None):
         """Initializes a new instance of :see:LocalizedRef.

localized_fields/fields/__init__.py

@@ -1,26 +1,28 @@
-from .field import LocalizedField
 from .autoslug_field import LocalizedAutoSlugField
-from .uniqueslug_field import LocalizedUniqueSlugField
+from .boolean_field import LocalizedBooleanField
 from .char_field import LocalizedCharField
-from .text_field import LocalizedTextField
+from .field import LocalizedField
 from .file_field import LocalizedFileField
+from .float_field import LocalizedFloatField
 from .integer_field import LocalizedIntegerField
-
+from .text_field import LocalizedTextField
+from .uniqueslug_field import LocalizedUniqueSlugField
 
 __all__ = [
-    'LocalizedField',
-    'LocalizedAutoSlugField',
-    'LocalizedUniqueSlugField',
-    'LocalizedCharField',
-    'LocalizedTextField',
-    'LocalizedFileField',
-    'LocalizedIntegerField'
+    "LocalizedField",
+    "LocalizedAutoSlugField",
+    "LocalizedUniqueSlugField",
+    "LocalizedCharField",
+    "LocalizedTextField",
+    "LocalizedFileField",
+    "LocalizedIntegerField",
+    "LocalizedFloatField",
+    "LocalizedBooleanField",
 ]
 
 try:
     from .bleach_field import LocalizedBleachField
-    __all__ += [
-        'LocalizedBleachField'
-    ]
+
+    __all__ += ["LocalizedBleachField"]
 except ImportError:
     pass

localized_fields/fields/autoslug_field.py

@@ -1,60 +1,53 @@
 import warnings
 
-from typing import Callable, Tuple, Union
 from datetime import datetime
+from typing import Callable, Tuple, Union
 
 from django import forms
 from django.conf import settings
 from django.utils import translation
 from django.utils.text import slugify
 
-from .field import LocalizedField
-from ..value import LocalizedValue
 from ..util import resolve_object_property
+from ..value import LocalizedValue
+from .field import LocalizedField
 
 
 class LocalizedAutoSlugField(LocalizedField):
-    """Automatically provides slugs for a localized
-    field upon saving."""
-
-    warnings.warn(
-        'LocalizedAutoSlug is deprecated and will be removed in the next major version.',
-        DeprecationWarning
-    )
+    """Automatically provides slugs for a localized field upon saving."""
 
     def __init__(self, *args, **kwargs):
         """Initializes a new instance of :see:LocalizedAutoSlugField."""
 
-        self.populate_from = kwargs.pop('populate_from', None)
-        self.include_time = kwargs.pop('include_time', False)
-
-        super(LocalizedAutoSlugField, self).__init__(
-            *args,
-            **kwargs
+        warnings.warn(
+            "LocalizedAutoSlug is deprecated and will be removed in the next major version.",
+            DeprecationWarning,
         )
 
+        self.populate_from = kwargs.pop("populate_from", None)
+        self.include_time = kwargs.pop("include_time", False)
+
+        super(LocalizedAutoSlugField, self).__init__(*args, **kwargs)
+
     def deconstruct(self):
-        """Deconstructs the field into something the database
-        can store."""
+        """Deconstructs the field into something the database can store."""
 
         name, path, args, kwargs = super(
-            LocalizedAutoSlugField, self).deconstruct()
+            LocalizedAutoSlugField, self
+        ).deconstruct()
 
-        kwargs['populate_from'] = self.populate_from
-        kwargs['include_time'] = self.include_time
+        kwargs["populate_from"] = self.populate_from
+        kwargs["include_time"] = self.include_time
         return name, path, args, kwargs
 
     def formfield(self, **kwargs):
         """Gets the form field associated with this field.
 
-        Because this is a slug field which is automatically
-        populated, it should be hidden from the form.
+        Because this is a slug field which is automatically populated,
+        it should be hidden from the form.
         """
 
-        defaults = {
-            'form_class': forms.CharField,
-            'required': False
-        }
+        defaults = {"form_class": forms.CharField, "required": False}
 
         defaults.update(kwargs)
 
@@ -64,8 +57,7 @@ class LocalizedAutoSlugField(LocalizedField):
         return form_field
 
     def pre_save(self, instance, add: bool):
-        """Ran just before the model is saved, allows us to built
-        the slug.
+        """Ran just before the model is saved, allows us to built the slug.
 
         Arguments:
             instance:
@@ -83,21 +75,19 @@ class LocalizedAutoSlugField(LocalizedField):
                 continue
 
             if self.include_time:
-                value += '-%s' % datetime.now().microsecond
+                value += "-%s" % datetime.now().microsecond
 
             def is_unique(slug: str, language: str) -> bool:
                 """Gets whether the specified slug is unique."""
 
-                unique_filter = {
-                    '%s__%s' % (self.name, language): slug
-                }
+                unique_filter = {"%s__%s" % (self.name, language): slug}
 
-                return not type(instance).objects.filter(**unique_filter).exists()
+                return (
+                    not type(instance).objects.filter(**unique_filter).exists()
+                )
 
             slug = self._make_unique_slug(
-                slugify(value, allow_unicode=True),
-                lang_code,
-                is_unique
+                slugify(value, allow_unicode=True), lang_code, is_unique
             )
 
             slugs.set(lang_code, slug)
@@ -106,9 +96,11 @@ class LocalizedAutoSlugField(LocalizedField):
         return slugs
 
     @staticmethod
-    def _make_unique_slug(slug: str, language: str, is_unique: Callable[[str], bool]) -> str:
-        """Guarentees that the specified slug is unique by appending
-        a number until it is unique.
+    def _make_unique_slug(
+        slug: str, language: str, is_unique: Callable[[str], bool]
+    ) -> str:
+        """Guarentees that the specified slug is unique by appending a number
+        until it is unique.
 
         Arguments:
             slug:
@@ -126,14 +118,14 @@ class LocalizedAutoSlugField(LocalizedField):
         unique_slug = slug
 
         while not is_unique(unique_slug, language):
-            unique_slug = '%s-%d' % (slug, index)
+            unique_slug = "%s-%d" % (slug, index)
             index += 1
 
         return unique_slug
 
     def _get_populate_values(self, instance) -> Tuple[str, str]:
-        """Gets all values (for each language) from the
-        specified's instance's `populate_from` field.
+        """Gets all values (for each language) from the specified's instance's
+        `populate_from` field.
 
         Arguments:
             instance:
@@ -147,16 +139,16 @@ class LocalizedAutoSlugField(LocalizedField):
             (
                 lang_code,
                 self._get_populate_from_value(
-                    instance,
-                    self.populate_from,
-                    lang_code
+                    instance, self.populate_from, lang_code
                 ),
             )
             for lang_code, _ in settings.LANGUAGES
         ]
 
     @staticmethod
-    def _get_populate_from_value(instance, field_name: Union[str, Tuple[str]], language: str):
+    def _get_populate_from_value(
+        instance, field_name: Union[str, Tuple[str]], language: str
+    ):
         """Gets the value to create a slug from in the specified language.
 
         Arguments:
@@ -182,11 +174,13 @@ class LocalizedAutoSlugField(LocalizedField):
                 return str(value)
 
         if isinstance(field_name, tuple) or isinstance(field_name, list):
-            value = '-'.join([
+            value = "-".join(
+                [
                     value
                     for value in [get_field_value(name) for name in field_name]
                     if value
-            ])
+                ]
+            )
             return value
 
         return get_field_value(field_name)

localized_fields/fields/bleach_field.py

@@ -1,18 +1,33 @@
-import bleach
+import html
 
 from django.conf import settings
-from django_bleach.utils import get_bleach_default_options
 
 from .field import LocalizedField
 
 
 class LocalizedBleachField(LocalizedField):
-    """Custom version of :see:BleachField that
-    is actually a :see:LocalizedField."""
+    """Custom version of :see:BleachField that is actually a
+    :see:LocalizedField."""
+
+    DEFAULT_SHOULD_ESCAPE = True
+
+    def __init__(self, *args, escape=True, **kwargs):
+        """Initializes a new instance of :see:LocalizedBleachField."""
+
+        self.escape = escape
+
+        super().__init__(*args, **kwargs)
+
+    def deconstruct(self):
+        name, path, args, kwargs = super().deconstruct()
+
+        if self.escape != self.DEFAULT_SHOULD_ESCAPE:
+            kwargs["escape"] = self.escape
+
+        return name, path, args, kwargs
 
     def pre_save(self, instance, add: bool):
-        """Ran just before the model is saved, allows us to built
-        the slug.
+        """Ran just before the model is saved, allows us to built the slug.
 
         Arguments:
             instance:
@@ -23,6 +38,20 @@ class LocalizedBleachField(LocalizedField):
                 to the database or an update.
         """
 
+        # the bleach library vendors dependencies and the html5lib
+        # dependency is incompatible with python 3.9, until that's
+        # fixed, you cannot use LocalizedBleachField with python 3.9
+        # sympton:
+        #   ImportError: cannot import name 'Mapping' from 'collections'
+        try:
+            import bleach
+
+            from django_bleach.utils import get_bleach_default_options
+        except ImportError:
+            raise UserWarning(
+                "LocalizedBleachField is not compatible with Python 3.9 yet."
+            )
+
         localized_value = getattr(instance, self.attname)
         if not localized_value:
             return None
@@ -32,9 +61,14 @@ class LocalizedBleachField(LocalizedField):
             if not value:
                 continue
 
+            cleaned_value = bleach.clean(
+                value if self.escape else html.unescape(value),
+                **get_bleach_default_options()
+            )
+
             localized_value.set(
                 lang_code,
-                bleach.clean(value, **get_bleach_default_options())
+                cleaned_value if self.escape else html.unescape(cleaned_value),
             )
 
         return localized_value

localized_fields/fields/boolean_field.py

@@ -0,0 +1,110 @@
+from typing import Dict, Optional, Union
+
+from django.conf import settings
+from django.db.utils import IntegrityError
+
+from ..forms import LocalizedBooleanFieldForm
+from ..value import LocalizedBooleanValue, LocalizedValue
+from .field import LocalizedField
+
+
+class LocalizedBooleanField(LocalizedField):
+    """Stores booleans as a localized value."""
+
+    attr_class = LocalizedBooleanValue
+
+    @classmethod
+    def from_db_value(cls, value, *_) -> Optional[LocalizedBooleanValue]:
+        db_value = super().from_db_value(value)
+
+        if db_value is None:
+            return db_value
+
+        if isinstance(db_value, str):
+            if db_value.lower() == "true":
+                return True
+            return False
+
+        if not isinstance(db_value, LocalizedValue):
+            return db_value
+
+        return cls._convert_localized_value(db_value)
+
+    def to_python(
+        self, value: Union[Dict[str, str], str, None]
+    ) -> LocalizedBooleanValue:
+        """Converts the value from a database value into a Python value."""
+
+        db_value = super().to_python(value)
+        return self._convert_localized_value(db_value)
+
+    def get_prep_value(self, value: LocalizedBooleanValue) -> dict:
+        """Gets the value in a format to store into the database."""
+
+        # apply default values
+        default_values = LocalizedBooleanValue(self.default)
+        if isinstance(value, LocalizedBooleanValue):
+            for lang_code, _ in settings.LANGUAGES:
+                local_value = value.get(lang_code)
+                if local_value is None:
+                    value.set(lang_code, default_values.get(lang_code, None))
+
+        prepped_value = super().get_prep_value(value)
+        if prepped_value is None:
+            return None
+
+        # make sure all values are proper values to be converted to bool
+        for lang_code, _ in settings.LANGUAGES:
+            local_value = prepped_value[lang_code]
+
+            if local_value is not None and local_value.lower() not in (
+                "false",
+                "true",
+            ):
+                raise IntegrityError(
+                    'non-boolean value in column "%s.%s" violates '
+                    "boolean constraint" % (self.name, lang_code)
+                )
+
+            # convert to a string before saving because the underlying
+            # type is hstore, which only accept strings
+            prepped_value[lang_code] = (
+                str(local_value) if local_value is not None else None
+            )
+
+        return prepped_value
+
+    def formfield(self, **kwargs):
+        """Gets the form field associated with this field."""
+        defaults = {"form_class": LocalizedBooleanFieldForm}
+
+        defaults.update(kwargs)
+        return super().formfield(**defaults)
+
+    @staticmethod
+    def _convert_localized_value(
+        value: LocalizedValue,
+    ) -> LocalizedBooleanValue:
+        """Converts from :see:LocalizedValue to :see:LocalizedBooleanValue."""
+
+        integer_values = {}
+        for lang_code, _ in settings.LANGUAGES:
+            local_value = value.get(lang_code, None)
+
+            if isinstance(local_value, str):
+                if local_value.lower() == "false":
+                    local_value = False
+                elif local_value.lower() == "true":
+                    local_value = True
+                else:
+                    raise ValueError(
+                        f"Could not convert value {local_value} to boolean."
+                    )
+
+                integer_values[lang_code] = local_value
+            elif local_value is not None:
+                raise TypeError(
+                    f"Expected value of type str instead of {type(local_value)}."
+                )
+
+        return LocalizedBooleanValue(integer_values)

localized_fields/fields/char_field.py

@@ -1,6 +1,6 @@
 from ..forms import LocalizedCharFieldForm
-from .field import LocalizedField
 from ..value import LocalizedStringValue
+from .field import LocalizedField
 
 
 class LocalizedCharField(LocalizedField):
@@ -8,9 +8,7 @@ class LocalizedCharField(LocalizedField):
 
     def formfield(self, **kwargs):
         """Gets the form field associated with this field."""
-        defaults = {
-            'form_class': LocalizedCharFieldForm
-        }
+        defaults = {"form_class": LocalizedCharFieldForm}
 
         defaults.update(kwargs)
         return super().formfield(**defaults)

localized_fields/fields/field.py

@@ -1,22 +1,22 @@
 import json
 
-from typing import Union, List, Optional
+from typing import List, Optional, Union
 
 from django.conf import settings
 from django.db.utils import IntegrityError
-
 from psqlextra.fields import HStoreField
 
+from ..descriptor import LocalizedValueDescriptor
 from ..forms import LocalizedFieldForm
 from ..value import LocalizedValue
-from ..descriptor import LocalizedValueDescriptor
 
 
 class LocalizedField(HStoreField):
     """A field that has the same value in multiple languages.
 
-    Internally this is stored as a :see:HStoreField where there
-    is a key for every language."""
+    Internally this is stored as a :see:HStoreField where there is a key
+    for every language.
+    """
 
     Meta = None
 
@@ -27,17 +27,27 @@ class LocalizedField(HStoreField):
     # The descriptor to use for accessing the attribute off of the class.
     descriptor_class = LocalizedValueDescriptor
 
-    def __init__(self, *args, required: Union[bool, List[str]]=None, **kwargs):
+    def __init__(
+        self,
+        *args,
+        required: Optional[Union[bool, List[str]]] = None,
+        blank: bool = False,
+        **kwargs
+    ):
         """Initializes a new instance of :see:LocalizedField."""
 
-        super(LocalizedField, self).__init__(*args, required=required, **kwargs)
-
-        if (self.required is None and self.blank) or self.required is False:
+        if (required is None and blank) or required is False:
             self.required = []
-        elif self.required is None and not self.blank:
+        elif required is None and not blank:
             self.required = [settings.LANGUAGE_CODE]
-        elif self.required is True:
+        elif required is True:
             self.required = [lang_code for lang_code, _ in settings.LANGUAGES]
+        else:
+            self.required = required
+
+        super(LocalizedField, self).__init__(
+            *args, required=self.required, blank=blank, **kwargs
+        )
 
     def contribute_to_class(self, model, name, **kwargs):
         """Adds this field to the specifed model.
@@ -54,8 +64,7 @@ class LocalizedField(HStoreField):
 
     @classmethod
     def from_db_value(cls, value, *_) -> Optional[LocalizedValue]:
-        """Turns the specified database value into its Python
-        equivalent.
+        """Turns the specified database value into its Python equivalent.
 
         Arguments:
             value:
@@ -68,7 +77,7 @@ class LocalizedField(HStoreField):
         """
 
         if not value:
-            if getattr(settings, 'LOCALIZED_FIELDS_EXPERIMENTAL', False):
+            if getattr(settings, "LOCALIZED_FIELDS_EXPERIMENTAL", True):
                 return None
             else:
                 return cls.attr_class()
@@ -98,8 +107,7 @@ class LocalizedField(HStoreField):
         return cls.attr_class(value)
 
     def to_python(self, value: Union[dict, str, None]) -> LocalizedValue:
-        """Turns the specified database value into its Python
-        equivalent.
+        """Turns the specified database value into its Python equivalent.
 
         Arguments:
             value:
@@ -124,8 +132,7 @@ class LocalizedField(HStoreField):
         return self.attr_class(deserialized_value)
 
     def get_prep_value(self, value: LocalizedValue) -> dict:
-        """Turns the specified value into something the database
-        can store.
+        """Turns the specified value into something the database can store.
 
         If an illegal value (non-LocalizedValue instance) is
         specified, we'll treat it as an empty :see:LocalizedValue
@@ -161,8 +168,8 @@ class LocalizedField(HStoreField):
         )
 
     def clean(self, value, *_):
-        """Cleans the specified value into something we
-        can store in the database.
+        """Cleans the specified value into something we can store in the
+        database.
 
         For example, when all the language fields are
         left empty, and the field is allowed to be null,
@@ -195,7 +202,7 @@ class LocalizedField(HStoreField):
 
     def validate(self, value: LocalizedValue, *_):
         """Validates that the values has been filled in for all required
-        languages
+        languages.
 
         Exceptions are raises in order to notify the user
         of invalid values.
@@ -212,15 +219,17 @@ class LocalizedField(HStoreField):
             lang_val = getattr(value, settings.LANGUAGE_CODE)
 
             if lang_val is None:
-                raise IntegrityError('null value in column "%s.%s" violates '
-                                     'not-null constraint' % (self.name, lang))
+                raise IntegrityError(
+                    'null value in column "%s.%s" violates '
+                    "not-null constraint" % (self.name, lang)
+                )
 
     def formfield(self, **kwargs):
         """Gets the form field associated with this field."""
 
         defaults = dict(
             form_class=LocalizedFieldForm,
-            required=False if self.blank else self.required
+            required=False if self.blank else self.required,
         )
         defaults.update(kwargs)
         return super().formfield(**defaults)

localized_fields/fields/file_field.py

@@ -1,31 +1,30 @@
-import json
 import datetime
+import json
 import posixpath
 
 from django.core.files import File
-from django.db.models.fields.files import FieldFile
-from django.utils import six
 from django.core.files.storage import default_storage
-from django.utils.encoding import force_str, force_text
+from django.db.models.fields.files import FieldFile
+from django.utils.encoding import force_str
 
 from localized_fields.fields import LocalizedField
 from localized_fields.fields.field import LocalizedValueDescriptor
 from localized_fields.value import LocalizedValue
 
-from ..value import LocalizedFileValue
 from ..forms import LocalizedFileFieldForm
+from ..value import LocalizedFileValue
 
 
 class LocalizedFieldFile(FieldFile):
-
     def __init__(self, instance, field, name, lang):
         super().__init__(instance, field, name)
         self.lang = lang
 
     def save(self, name, content, save=True):
         name = self.field.generate_filename(self.instance, name, self.lang)
-        self.name = self.storage.save(name, content,
-                                      max_length=self.field.max_length)
+        self.name = self.storage.save(
+            name, content, max_length=self.field.max_length
+        )
         self._committed = True
 
         if save:
@@ -37,7 +36,7 @@ class LocalizedFieldFile(FieldFile):
         if not self:
             return
 
-        if hasattr(self, '_file'):
+        if hasattr(self, "_file"):
             self.close()
             del self.file
 
@@ -56,28 +55,33 @@ class LocalizedFileValueDescriptor(LocalizedValueDescriptor):
     def __get__(self, instance, cls=None):
         value = super().__get__(instance, cls)
         for lang, file in value.__dict__.items():
-            if isinstance(file, six.string_types) or file is None:
+            if isinstance(file, str) or file is None:
                 file = self.field.value_class(instance, self.field, file, lang)
                 value.set(lang, file)
 
-            elif isinstance(file, File) and \
-                    not isinstance(file, LocalizedFieldFile):
-                file_copy = self.field.value_class(instance, self.field,
-                                                   file.name, lang)
+            elif isinstance(file, File) and not isinstance(
+                file, LocalizedFieldFile
+            ):
+                file_copy = self.field.value_class(
+                    instance, self.field, file.name, lang
+                )
                 file_copy.file = file
                 file_copy._committed = False
                 value.set(lang, file_copy)
 
-            elif isinstance(file, LocalizedFieldFile) and \
-                    not hasattr(file, 'field'):
+            elif isinstance(file, LocalizedFieldFile) and not hasattr(
+                file, "field"
+            ):
                 file.instance = instance
                 file.field = self.field
                 file.storage = self.field.storage
                 file.lang = lang
 
             # Make sure that the instance is correct.
-            elif isinstance(file, LocalizedFieldFile) \
-                    and instance is not file.instance:
+            elif (
+                isinstance(file, LocalizedFieldFile)
+                and instance is not file.instance
+            ):
                 file.instance = instance
                 file.lang = lang
         return value
@@ -88,8 +92,9 @@ class LocalizedFileField(LocalizedField):
     attr_class = LocalizedFileValue
     value_class = LocalizedFieldFile
 
-    def __init__(self, verbose_name=None, name=None, upload_to='', storage=None,
-                 **kwargs):
+    def __init__(
+        self, verbose_name=None, name=None, upload_to="", storage=None, **kwargs
+    ):
 
         self.storage = storage or default_storage
         self.upload_to = upload_to
@@ -98,9 +103,9 @@ class LocalizedFileField(LocalizedField):
 
     def deconstruct(self):
         name, path, args, kwargs = super().deconstruct()
-        kwargs['upload_to'] = self.upload_to
+        kwargs["upload_to"] = self.upload_to
         if self.storage is not default_storage:
-            kwargs['storage'] = self.storage
+            kwargs["storage"] = self.storage
         return name, path, args, kwargs
 
     def get_prep_value(self, value):
@@ -110,11 +115,11 @@ class LocalizedFileField(LocalizedField):
             prep_value = LocalizedValue()
             for k, v in value.__dict__.items():
                 if v is None:
-                    prep_value.set(k, '')
+                    prep_value.set(k, "")
                 else:
                     # Need to convert File objects provided via a form to
                     # unicode for database insertion
-                    prep_value.set(k, six.text_type(v))
+                    prep_value.set(k, str(v))
             return super().get_prep_value(prep_value)
         return super().get_prep_value(value)
 
@@ -132,7 +137,7 @@ class LocalizedFileField(LocalizedField):
             filename = self.upload_to(instance, filename, lang)
         else:
             now = datetime.datetime.now()
-            dirname = force_text(now.strftime(force_str(self.upload_to)))
+            dirname = force_str(now.strftime(force_str(self.upload_to)))
             dirname = dirname.format(lang=lang)
             filename = posixpath.join(dirname, filename)
         return self.storage.generate_filename(filename)
@@ -141,18 +146,17 @@ class LocalizedFileField(LocalizedField):
         if isinstance(data, LocalizedValue):
             for k, v in data.__dict__.items():
                 if v is not None and not v:
-                    data.set(k, '')
+                    data.set(k, "")
             setattr(instance, self.name, data)
 
     def formfield(self, **kwargs):
-        defaults = {'form_class': LocalizedFileFieldForm}
+        defaults = {"form_class": LocalizedFileFieldForm}
         defaults.update(kwargs)
         return super().formfield(**defaults)
 
     def value_to_string(self, obj):
         value = self.value_from_object(obj)
         if isinstance(value, LocalizedFileValue):
-            return json.dumps({k: v.name for k, v
-                               in value.__dict__.items()})
+            return json.dumps({k: v.name for k, v in value.__dict__.items()})
         else:
             return super().value_to_string(obj)

localized_fields/fields/float_field.py

@@ -0,0 +1,95 @@
+from typing import Dict, Optional, Union
+
+from django.conf import settings
+from django.db.utils import IntegrityError
+
+from ..forms import LocalizedIntegerFieldForm
+from ..value import LocalizedFloatValue, LocalizedValue
+from .field import LocalizedField
+
+
+class LocalizedFloatField(LocalizedField):
+    """Stores float as a localized value."""
+
+    attr_class = LocalizedFloatValue
+
+    @classmethod
+    def from_db_value(cls, value, *_) -> Optional[LocalizedFloatValue]:
+        db_value = super().from_db_value(value)
+        if db_value is None:
+            return db_value
+
+        # if we were used in an expression somehow then it might be
+        # that we're returning an individual value or an array, so
+        # we should not convert that into an :see:LocalizedFloatValue
+        if not isinstance(db_value, LocalizedValue):
+            return db_value
+
+        return cls._convert_localized_value(db_value)
+
+    def to_python(
+        self, value: Union[Dict[str, int], int, None]
+    ) -> LocalizedFloatValue:
+        """Converts the value from a database value into a Python value."""
+
+        db_value = super().to_python(value)
+        return self._convert_localized_value(db_value)
+
+    def get_prep_value(self, value: LocalizedFloatValue) -> dict:
+        """Gets the value in a format to store into the database."""
+
+        # apply default values
+        default_values = LocalizedFloatValue(self.default)
+        if isinstance(value, LocalizedFloatValue):
+            for lang_code, _ in settings.LANGUAGES:
+                local_value = value.get(lang_code)
+                if local_value is None:
+                    value.set(lang_code, default_values.get(lang_code, None))
+
+        prepped_value = super().get_prep_value(value)
+        if prepped_value is None:
+            return None
+
+        # make sure all values are proper floats
+        for lang_code, _ in settings.LANGUAGES:
+            local_value = prepped_value[lang_code]
+            try:
+                if local_value is not None:
+                    float(local_value)
+            except (TypeError, ValueError):
+                raise IntegrityError(
+                    'non-float value in column "%s.%s" violates '
+                    "float constraint" % (self.name, lang_code)
+                )
+
+            # convert to a string before saving because the underlying
+            # type is hstore, which only accept strings
+            prepped_value[lang_code] = (
+                str(local_value) if local_value is not None else None
+            )
+
+        return prepped_value
+
+    def formfield(self, **kwargs):
+        """Gets the form field associated with this field."""
+        defaults = {"form_class": LocalizedIntegerFieldForm}
+
+        defaults.update(kwargs)
+        return super().formfield(**defaults)
+
+    @staticmethod
+    def _convert_localized_value(value: LocalizedValue) -> LocalizedFloatValue:
+        """Converts from :see:LocalizedValue to :see:LocalizedFloatValue."""
+
+        float_values = {}
+        for lang_code, _ in settings.LANGUAGES:
+            local_value = value.get(lang_code, None)
+            if local_value is None or local_value.strip() == "":
+                local_value = None
+
+            try:
+                float_values[lang_code] = float(local_value)
+            except (ValueError, TypeError):
+                float_values[lang_code] = None
+
+        return LocalizedFloatValue(float_values)

localized_fields/fields/integer_field.py

@@ -1,11 +1,21 @@
-from typing import Optional, Union, Dict
+from typing import Dict, Optional, Union
 
 from django.conf import settings
+from django.contrib.postgres.fields.hstore import KeyTransform
 from django.db.utils import IntegrityError
 
-from .field import LocalizedField
-from ..value import LocalizedValue, LocalizedIntegerValue
 from ..forms import LocalizedIntegerFieldForm
+from ..value import LocalizedIntegerValue, LocalizedValue
+from .field import LocalizedField
+
+
+class LocalizedIntegerFieldKeyTransform(KeyTransform):
+    """Transform that selects a single key from a hstore value and casts it to
+    an integer."""
+
+    def as_sql(self, compiler, connection):
+        sql, params = super().as_sql(compiler, connection)
+        return f"{sql}::integer", params
 
 
 class LocalizedIntegerField(LocalizedField):
@@ -13,12 +23,28 @@ class LocalizedIntegerField(LocalizedField):
 
     attr_class = LocalizedIntegerValue
 
+    def get_transform(self, name):
+        """Gets the transformation to apply when selecting this value.
+
+        This is where the SQL expression to grab a single is added and
+        the cast to integer so that sorting by a hstore value works as
+        expected.
+        """
+
+        def _transform(*args, **kwargs):
+            return LocalizedIntegerFieldKeyTransform(name, *args, **kwargs)
+
+        return _transform
+
     @classmethod
     def from_db_value(cls, value, *_) -> Optional[LocalizedIntegerValue]:
         db_value = super().from_db_value(value)
         if db_value is None:
             return db_value
 
+        if isinstance(db_value, str):
+            return int(db_value)
+
         # if we were used in an expression somehow then it might be
         # that we're returning an individual value or an array, so
         # we should not convert that into an :see:LocalizedIntegerValue
@@ -27,7 +53,9 @@ class LocalizedIntegerField(LocalizedField):
 
         return cls._convert_localized_value(db_value)
 
-    def to_python(self, value: Union[Dict[str, int], int, None]) -> LocalizedIntegerValue:
+    def to_python(
+        self, value: Union[Dict[str, int], int, None]
+    ) -> LocalizedIntegerValue:
         """Converts the value from a database value into a Python value."""
 
         db_value = super().to_python(value)
@@ -55,32 +83,36 @@ class LocalizedIntegerField(LocalizedField):
                 if local_value is not None:
                     int(local_value)
             except (TypeError, ValueError):
-                raise IntegrityError('non-integer value in column "%s.%s" violates '
-                                     'integer constraint' % (self.name, lang_code))
+                raise IntegrityError(
+                    'non-integer value in column "%s.%s" violates '
+                    "integer constraint" % (self.name, lang_code)
+                )
 
             # convert to a string before saving because the underlying
             # type is hstore, which only accept strings
-            prepped_value[lang_code] = str(local_value) if local_value is not None else None
+            prepped_value[lang_code] = (
+                str(local_value) if local_value is not None else None
+            )
 
         return prepped_value
 
     def formfield(self, **kwargs):
         """Gets the form field associated with this field."""
-        defaults = {
-            'form_class': LocalizedIntegerFieldForm
-        }
+        defaults = {"form_class": LocalizedIntegerFieldForm}
 
         defaults.update(kwargs)
         return super().formfield(**defaults)
 
     @staticmethod
-    def _convert_localized_value(value: LocalizedValue) -> LocalizedIntegerValue:
+    def _convert_localized_value(
+        value: LocalizedValue,
+    ) -> LocalizedIntegerValue:
         """Converts from :see:LocalizedValue to :see:LocalizedIntegerValue."""
 
         integer_values = {}
         for lang_code, _ in settings.LANGUAGES:
             local_value = value.get(lang_code, None)
-            if local_value is None or local_value.strip() == '':
+            if local_value is None or local_value.strip() == "":
                 local_value = None
 
             try:

localized_fields/fields/text_field.py

@@ -6,9 +6,7 @@ class LocalizedTextField(LocalizedCharField):
     def formfield(self, **kwargs):
         """Gets the form field associated with this field."""
 
-        defaults = {
-            'form_class': LocalizedTextFieldForm
-        }
+        defaults = {"form_class": LocalizedTextFieldForm}
 
         defaults.update(kwargs)
         return super().formfield(**defaults)

localized_fields/fields/uniqueslug_field.py

@@ -1,17 +1,16 @@
 from datetime import datetime
 
-from django.utils.text import slugify
 from django.core.exceptions import ImproperlyConfigured
+from django.utils.text import slugify
 
-from .autoslug_field import LocalizedAutoSlugField
-from ..util import get_language_codes
 from ..mixins import AtomicSlugRetryMixin
+from ..util import get_language_codes
 from ..value import LocalizedValue
+from .autoslug_field import LocalizedAutoSlugField
 
 
 class LocalizedUniqueSlugField(LocalizedAutoSlugField):
-    """Automatically provides slugs for a localized
-    field upon saving."
+    """Automatically provides slugs for a localized field upon saving.".
 
     An improved version of :see:LocalizedAutoSlugField,
     which adds:
@@ -22,35 +21,45 @@ class LocalizedUniqueSlugField(LocalizedAutoSlugField):
     When in doubt, use this over :see:LocalizedAutoSlugField.
     Inherit from :see:AtomicSlugRetryMixin in your model to
     make this field work properly.
+
+    By default, this creates a new slug if the field(s) specified
+    in `populate_from` are changed. Set `immutable=True` to get
+    immutable slugs.
     """
 
     def __init__(self, *args, **kwargs):
         """Initializes a new instance of :see:LocalizedUniqueSlugField."""
 
-        kwargs['uniqueness'] = kwargs.pop('uniqueness', get_language_codes())
+        kwargs["uniqueness"] = kwargs.pop("uniqueness", get_language_codes())
 
-        super(LocalizedUniqueSlugField, self).__init__(
-            *args,
-            **kwargs
-        )
+        self.enabled = kwargs.pop("enabled", True)
+        self.immutable = kwargs.pop("immutable", False)
 
-        self.populate_from = kwargs.pop('populate_from')
-        self.include_time = kwargs.pop('include_time', False)
+        super(LocalizedUniqueSlugField, self).__init__(*args, **kwargs)
+
+        self.populate_from = kwargs.pop("populate_from")
+        self.include_time = kwargs.pop("include_time", False)
 
     def deconstruct(self):
-        """Deconstructs the field into something the database
-        can store."""
+        """Deconstructs the field into something the database can store."""
 
         name, path, args, kwargs = super(
-            LocalizedUniqueSlugField, self).deconstruct()
+            LocalizedUniqueSlugField, self
+        ).deconstruct()
+
+        kwargs["populate_from"] = self.populate_from
+        kwargs["include_time"] = self.include_time
+
+        if self.enabled is False:
+            kwargs["enabled"] = self.enabled
+
+        if self.immutable is True:
+            kwargs["immutable"] = self.immutable
 
-        kwargs['populate_from'] = self.populate_from
-        kwargs['include_time'] = self.include_time
         return name, path, args, kwargs
 
     def pre_save(self, instance, add: bool):
-        """Ran just before the model is saved, allows us to built
-        the slug.
+        """Ran just before the model is saved, allows us to built the slug.
 
         Arguments:
             instance:
@@ -64,11 +73,17 @@ class LocalizedUniqueSlugField(LocalizedAutoSlugField):
             The localized slug that was generated.
         """
 
+        if not self.enabled:
+            return getattr(instance, self.name)
+
         if not isinstance(instance, AtomicSlugRetryMixin):
-            raise ImproperlyConfigured((
-                'Model \'%s\' does not inherit from AtomicSlugRetryMixin. '
-                'Without this, the LocalizedUniqueSlugField will not work.'
-            ) % type(instance).__name__)
+            raise ImproperlyConfigured(
+                (
+                    "Model '%s' does not inherit from AtomicSlugRetryMixin. "
+                    "Without this, the LocalizedUniqueSlugField will not work."
+                )
+                % type(instance).__name__
+            )
 
         slugs = LocalizedValue()
 
@@ -78,25 +93,30 @@ class LocalizedUniqueSlugField(LocalizedAutoSlugField):
 
             slug = slugify(value, allow_unicode=True)
 
+            current_slug = getattr(instance, self.name).get(lang_code)
+            if current_slug and self.immutable:
+                slugs.set(lang_code, current_slug)
+                continue
+
             # verify whether it's needed to re-generate a slug,
             # if not, re-use the same slug
             if instance.pk is not None:
-                current_slug = getattr(instance, self.name).get(lang_code)
                 if current_slug is not None:
-                    stripped_slug = current_slug[0:current_slug.rfind('-')]
+                    current_slug_end_index = current_slug.rfind("-")
+                    stripped_slug = current_slug[0:current_slug_end_index]
                     if slug == stripped_slug:
                         slugs.set(lang_code, current_slug)
                         continue
 
             if self.include_time:
-                slug += '-%d' % datetime.now().microsecond
+                slug += "-%d" % datetime.now().microsecond
 
-            retries = getattr(instance, 'retries', 0)
+            retries = getattr(instance, "retries", 0)
             if retries > 0:
                 # do not add another - if we already added time
                 if not self.include_time:
-                    slug += '-'
-                slug += '%d' % retries
+                    slug += "-"
+                slug += "%d" % retries
 
             slugs.set(lang_code, slug)
 

localized_fields/forms.py

@@ -5,30 +5,46 @@ from django.conf import settings
 from django.core.exceptions import ValidationError
 from django.forms.widgets import FILE_INPUT_CONTRADICTION
 
-from .value import LocalizedValue, LocalizedStringValue, \
-    LocalizedFileValue, LocalizedIntegerValue
-from .widgets import LocalizedFieldWidget, LocalizedCharFieldWidget, \
-    LocalizedFileWidget, AdminLocalizedIntegerFieldWidget
+from .value import (
+    LocalizedBooleanValue,
+    LocalizedFileValue,
+    LocalizedIntegerValue,
+    LocalizedStringValue,
+    LocalizedValue,
+)
+from .widgets import (
+    AdminLocalizedBooleanFieldWidget,
+    AdminLocalizedIntegerFieldWidget,
+    LocalizedCharFieldWidget,
+    LocalizedFieldWidget,
+    LocalizedFileWidget,
+)
 
 
 class LocalizedFieldForm(forms.MultiValueField):
-    """Form for a localized field, allows editing
-    the field in multiple languages."""
+    """Form for a localized field, allows editing the field in multiple
+    languages."""
 
     widget = LocalizedFieldWidget
     field_class = forms.fields.CharField
     value_class = LocalizedValue
 
-    def __init__(self, *args, required: Union[bool, List[str]]=False, **kwargs):
+    def __init__(
+        self, *args, required: Union[bool, List[str]] = False, **kwargs
+    ):
         """Initializes a new instance of :see:LocalizedFieldForm."""
 
         fields = []
 
+        # Do not print initial value in html in the form of a hidden input. This will result in loss of information
+        kwargs["show_hidden_initial"] = False
+
         for lang_code, _ in settings.LANGUAGES:
             field_options = dict(
-                required=required if type(required) is bool else (lang_code in
-                                                                  required),
-                label=lang_code
+                required=required
+                if type(required) is bool
+                else (lang_code in required),
+                label=lang_code,
             )
             fields.append(self.field_class(**field_options))
 
@@ -36,16 +52,17 @@ class LocalizedFieldForm(forms.MultiValueField):
             fields,
             required=required if type(required) is bool else True,
             require_all_fields=False,
-            *args, **kwargs
+            *args,
+            **kwargs
         )
 
         # set 'required' attribute for each widget separately
         for field, widget in zip(self.fields, self.widget.widgets):
             widget.is_required = field.required
 
-    def compress(self, value: List[str]) -> value_class:
-        """Compresses the values from individual fields
-        into a single :see:LocalizedValue instance.
+    def compress(self, value: List[str]) -> LocalizedValue:
+        """Compresses the values from individual fields into a single
+        :see:LocalizedValue instance.
 
         Arguments:
             value:
@@ -65,41 +82,50 @@ class LocalizedFieldForm(forms.MultiValueField):
 
 
 class LocalizedCharFieldForm(LocalizedFieldForm):
-    """Form for a localized char field, allows editing
-    the field in multiple languages."""
+    """Form for a localized char field, allows editing the field in multiple
+    languages."""
 
     widget = LocalizedCharFieldWidget
     value_class = LocalizedStringValue
 
 
 class LocalizedTextFieldForm(LocalizedFieldForm):
-    """Form for a localized text field, allows editing
-    the field in multiple languages."""
+    """Form for a localized text field, allows editing the field in multiple
+    languages."""
 
     value_class = LocalizedStringValue
 
 
 class LocalizedIntegerFieldForm(LocalizedFieldForm):
-    """Form for a localized integer field, allows editing
-    the field in multiple languages."""
+    """Form for a localized integer field, allows editing the field in multiple
+    languages."""
 
     widget = AdminLocalizedIntegerFieldWidget
     value_class = LocalizedIntegerValue
 
 
+class LocalizedBooleanFieldForm(LocalizedFieldForm, forms.BooleanField):
+    """Form for a localized boolean field, allows editing the field in multiple
+    languages."""
+
+    widget = AdminLocalizedBooleanFieldWidget
+    field_class = forms.fields.BooleanField
+    value_class = LocalizedBooleanValue
+
+
 class LocalizedFileFieldForm(LocalizedFieldForm, forms.FileField):
-    """Form for a localized file field, allows editing
-    the field in multiple languages."""
+    """Form for a localized file field, allows editing the field in multiple
+    languages."""
 
     widget = LocalizedFileWidget
     field_class = forms.fields.FileField
     value_class = LocalizedFileValue
 
     def clean(self, value, initial=None):
-        """
-        Most part of this method is a copy of
-        django.forms.MultiValueField.clean, with the exception of initial
-        value handling (this need for correct processing FileField's).
+        """Most part of this method is a copy of
+        django.forms.MultiValueField.clean, with the exception of initial value
+        handling (this need for correct processing FileField's).
+
         All original comments saved.
         """
         if initial is None:
@@ -111,40 +137,44 @@ class LocalizedFileFieldForm(LocalizedFieldForm, forms.FileField):
         clean_data = []
         errors = []
         if not value or isinstance(value, (list, tuple)):
-            if (not value or not [v for v in value if
-                                  v not in self.empty_values]) \
-                    and (not initial or not [v for v in initial if
-                                             v not in self.empty_values]):
+            is_empty = [v for v in value if v not in self.empty_values]
+            if (not value or not is_empty) and (not initial or not is_empty):
                 if self.required:
-                    raise ValidationError(self.error_messages['required'],
-                                          code='required')
+                    raise ValidationError(
+                        self.error_messages["required"], code="required"
+                    )
         else:
-            raise ValidationError(self.error_messages['invalid'],
-                                  code='invalid')
+            raise ValidationError(
+                self.error_messages["invalid"], code="invalid"
+            )
         for i, field in enumerate(self.fields):
             try:
                 field_value = value[i]
             except IndexError:
                 field_value = None
+
             try:
                 field_initial = initial[i]
             except IndexError:
                 field_initial = None
 
-            if field_value in self.empty_values and \
-                    field_initial in self.empty_values:
+            if (
+                field_value in self.empty_values
+                and field_initial in self.empty_values
+            ):
                 if self.require_all_fields:
                     # Raise a 'required' error if the MultiValueField is
                     # required and any field is empty.
                     if self.required:
-                        raise ValidationError(self.error_messages['required'],
-                                              code='required')
+                        raise ValidationError(
+                            self.error_messages["required"], code="required"
+                        )
                 elif field.required:
                     # Otherwise, add an 'incomplete' error to the list of
                     # collected errors and skip field cleaning, if a required
                     # field is empty.
-                    if field.error_messages['incomplete'] not in errors:
-                        errors.append(field.error_messages['incomplete'])
+                    if field.error_messages["incomplete"] not in errors:
+                        errors.append(field.error_messages["incomplete"])
                     continue
             try:
                 clean_data.append(field.clean(field_value, field_initial))

localized_fields/lookups.py

@@ -1,22 +1,72 @@
 from django.conf import settings
 from django.contrib.postgres.fields.hstore import KeyTransform
-from django.contrib.postgres.lookups import (SearchLookup, TrigramSimilar,
-                                             Unaccent)
-from django.db.models.expressions import Col
-from django.db.models.lookups import (Contains, EndsWith, Exact, IContains,
-                                      IEndsWith, IExact, In, IRegex, IsNull,
-                                      IStartsWith, Regex, StartsWith)
+from django.contrib.postgres.lookups import (
+    SearchLookup,
+    TrigramSimilar,
+    Unaccent,
+)
+from django.db.models import TextField, Transform
+from django.db.models.expressions import Col, Func, Value
+from django.db.models.functions import Coalesce
+from django.db.models.lookups import (
+    Contains,
+    EndsWith,
+    Exact,
+    IContains,
+    IEndsWith,
+    IExact,
+    In,
+    IRegex,
+    IsNull,
+    IStartsWith,
+    Regex,
+    StartsWith,
+)
 from django.utils import translation
+from psqlextra.expressions import HStoreColumn
+
+from .fields import LocalizedField
+
+try:
+    from django.db.models.functions import NullIf
+except ImportError:
+    # for Django < 2.2
+    class NullIf(Func):
+        function = "NULLIF"
+        arity = 2
 
 
-class LocalizedLookupMixin():
+class LocalizedLookupMixin:
     def process_lhs(self, qn, connection):
-        if isinstance(self.lhs, Col):
+        # If the LHS is already a reference to a specific hstore key, there
+        # is nothing to be done since it already references as specific language.
+        if isinstance(self.lhs, HStoreColumn) or isinstance(
+            self.lhs, KeyTransform
+        ):
+            return super().process_lhs(qn, connection)
+
+        # If this is something custom expression, we don't really know how to
+        # handle that, so we better do nothing.
+        if not isinstance(self.lhs, Col):
+            return super().process_lhs(qn, connection)
+
+        # Select the key for the current language. We do this so that
+        #
+        # myfield__<lookup>=
+        #
+        # Is converted into:
+        #
+        # myfield__<lookup>__<current language>=
         language = translation.get_language() or settings.LANGUAGE_CODE
         self.lhs = KeyTransform(language, self.lhs)
+
         return super().process_lhs(qn, connection)
 
     def get_prep_lookup(self):
+        # Django 4.0 removed the ability for isnull fields to be something
+        # other than a bool We should NOT convert them to strings
+        if isinstance(self.rhs, bool):
+            return self.rhs
         return str(self.rhs)
 
 
@@ -78,3 +128,43 @@ class LocalizedRegexWith(LocalizedLookupMixin, Regex):
 
 class LocalizedIRegexWith(LocalizedLookupMixin, IRegex):
     pass
+
+
+@LocalizedField.register_lookup
+class ActiveRefLookup(Transform):
+    output_field = TextField()
+    lookup_name = "active_ref"
+    arity = None
+
+    def as_sql(self, compiler, connection):
+        language = translation.get_language() or settings.LANGUAGE_CODE
+        return KeyTransform(language, self.lhs).as_sql(compiler, connection)
+
+
+@LocalizedField.register_lookup
+class TranslatedRefLookup(Transform):
+    output_field = TextField()
+    lookup_name = "translated_ref"
+    arity = None
+
+    def as_sql(self, compiler, connection):
+        language = translation.get_language()
+        fallback_config = getattr(settings, "LOCALIZED_FIELDS_FALLBACKS", {})
+        target_languages = fallback_config.get(language, [])
+        if not target_languages and language != settings.LANGUAGE_CODE:
+            target_languages.append(settings.LANGUAGE_CODE)
+
+        if language:
+            target_languages.insert(0, language)
+
+        if len(target_languages) > 1:
+            return Coalesce(
+                *[
+                    NullIf(KeyTransform(language, self.lhs), Value(""))
+                    for language in target_languages
+                ]
+            ).as_sql(compiler, connection)
+
+        return KeyTransform(target_languages[0], self.lhs).as_sql(
+            compiler, connection
+        )

localized_fields/migrations/0001_initial.py

@@ -6,9 +6,6 @@ from django.db import migrations
 
 class Migration(migrations.Migration):
 
-    dependencies = [
-    ]
+    dependencies = []
 
-    operations = [
-        HStoreExtension(),
-    ]
+    operations = [HStoreExtension()]

localized_fields/mixins.py

@@ -1,22 +1,18 @@
-from django.db import transaction
 from django.conf import settings
+from django.db import transaction
 from django.db.utils import IntegrityError
 
 
 class AtomicSlugRetryMixin:
-    """Makes :see:LocalizedUniqueSlugField work by retrying upon
-    violation of the UNIQUE constraint."""
+    """Makes :see:LocalizedUniqueSlugField work by retrying upon violation of
+    the UNIQUE constraint."""
 
     def save(self, *args, **kwargs):
         """Saves this model instance to the database."""
 
-        max_retries = getattr(
-            settings,
-            'LOCALIZED_FIELDS_MAX_RETRIES',
-            100
-        )
+        max_retries = getattr(settings, "LOCALIZED_FIELDS_MAX_RETRIES", 100)
 
-        if not hasattr(self, 'retries'):
+        if not hasattr(self, "retries"):
             self.retries = 0
 
         with transaction.atomic():
@@ -28,7 +24,7 @@ class AtomicSlugRetryMixin:
                 # field class... we can also not only catch exceptions
                 # that apply to slug fields... so yea.. this is as
                 # retarded as it gets... i am sorry :(
-                if 'slug' not in str(ex):
+                if "slug" not in str(ex):
                     raise ex
 
                 if self.retries >= max_retries:

localized_fields/models.py

@@ -10,7 +10,8 @@ class LocalizedModel(AtomicSlugRetryMixin, PostgresModel):
     from LocalizedModel. However, for certain features, this is required.
 
     It is definitely needed for :see:LocalizedUniqueSlugField, unless you
-    manually inherit from AtomicSlugRetryMixin."""
+    manually inherit from AtomicSlugRetryMixin.
+    """
 
     class Meta:
         abstract = True

localized_fields/static/localized_fields/localized-fields-admin.css

@@ -34,10 +34,11 @@
 
 .localized-fields-widget.tabs .localized-fields-widget.tab label {
     padding: 5px 10px;
-    display: inline-block;
+    display: inline;
     text-decoration: none;
     color: #fff;
     width: initial;
+    cursor: pointer;
 }
 
 .localized-fields-widget.tabs .localized-fields-widget.tab.active,

localized_fields/util.py

@@ -15,10 +15,7 @@ def get_language_codes() -> List[str]:
         in your project.
     """
 
-    return [
-        lang_code
-        for lang_code, _ in settings.LANGUAGES
-    ]
+    return [lang_code for lang_code, _ in settings.LANGUAGES]
 
 
 def resolve_object_property(obj, path: str):
@@ -38,7 +35,7 @@ def resolve_object_property(obj, path: str):
     """
 
     value = obj
-    for path_part in path.split('.'):
+    for path_part in path.split("."):
         value = getattr(value, path_part)
 
     return value

localized_fields/value.py

@@ -1,7 +1,7 @@
-import deprecation
-
-from typing import Optional
 from collections.abc import Iterable
+from typing import Optional
+
+import deprecation
 
 from django.conf import settings
 from django.utils import translation
@@ -9,6 +9,7 @@ from django.utils import translation
 
 class LocalizedValue(dict):
     """Represents the value of a :see:LocalizedField."""
+
     default_value = None
 
     def __init__(self, keys: dict = None):
@@ -25,8 +26,7 @@ class LocalizedValue(dict):
         self._interpret_value(keys)
 
     def get(self, language: str = None, default: str = None) -> str:
-        """Gets the underlying value in the specified or
-        primary language.
+        """Gets the underlying value in the specified or primary language.
 
         Arguments:
             language:
@@ -65,12 +65,12 @@ class LocalizedValue(dict):
             contained in this instance.
         """
 
-        path = 'localized_fields.value.%s' % self.__class__.__name__
+        path = "localized_fields.value.%s" % self.__class__.__name__
         return path, [self.__dict__], {}
 
     def _interpret_value(self, value):
-        """Interprets a value passed in the constructor as
-        a :see:LocalizedValue.
+        """Interprets a value passed in the constructor as a
+        :see:LocalizedValue.
 
         If string:
             Assumes it's the default language.
@@ -90,6 +90,9 @@ class LocalizedValue(dict):
         for lang_code, _ in settings.LANGUAGES:
             self.set(lang_code, self.default_value)
 
+        if callable(value):
+            value = value()
+
         if isinstance(value, str):
             self.set(settings.LANGUAGE_CODE, value)
 
@@ -102,34 +105,54 @@ class LocalizedValue(dict):
             for val in value:
                 self._interpret_value(val)
 
-    def translate(self) -> Optional[str]:
-        """Gets the value in the current language or falls
-        back to the next language if there's no value in the
-        current language."""
+    def translate(self, language: Optional[str] = None) -> Optional[str]:
+        """Gets the value in the specified language (or active language).
 
-        fallbacks = getattr(settings, 'LOCALIZED_FIELDS_FALLBACKS', {})
+        Arguments:
+            language:
+                The language to get the value in. If not specified,
+                the currently active language is used.
 
-        language = translation.get_language() or settings.LANGUAGE_CODE
-        languages = fallbacks.get(language, [settings.LANGUAGE_CODE])[:]
-        languages.insert(0, language)
+        Returns:
+            The value in the specified (or active) language. If no value
+            is available in the specified language, the value is returned
+            in one of the fallback languages.
+        """
 
-        for lang_code in languages:
+        target_language = (
+            language or translation.get_language() or settings.LANGUAGE_CODE
+        )
+
+        fallback_config = getattr(settings, "LOCALIZED_FIELDS_FALLBACKS", {})
+
+        target_languages = fallback_config.get(
+            target_language, [settings.LANGUAGE_CODE]
+        )
+
+        for lang_code in [target_language] + target_languages:
             value = self.get(lang_code)
             if value:
                 return value or None
 
         return None
 
-    def __str__(self) -> str:
-        """Gets the value in the current language or falls
-        back to the next language if there's no value in the
-        current language."""
+    def is_empty(self) -> bool:
+        """Gets whether all the languages contain the default value."""
 
-        return self.translate() or ''
+        for lang_code, _ in settings.LANGUAGES:
+            if self.get(lang_code) != self.default_value:
+                return False
+
+        return True
+
+    def __str__(self) -> str:
+        """Gets the value in the current language or falls back to the next
+        language if there's no value in the current language."""
+
+        return self.translate() or ""
 
     def __eq__(self, other):
-        """Compares :paramref:self to :paramref:other for
-        equality.
+        """Compares :paramref:self to :paramref:other for equality.
 
         Returns:
             True when :paramref:self is equal to :paramref:other.
@@ -148,8 +171,7 @@ class LocalizedValue(dict):
         return True
 
     def __ne__(self, other):
-        """Compares :paramref:self to :paramerf:other for
-        in-equality.
+        """Compares :paramref:self to :paramerf:other for in-equality.
 
         Returns:
             True when :paramref:self is not equal to :paramref:other.
@@ -174,56 +196,79 @@ class LocalizedValue(dict):
     def __repr__(self):  # pragma: no cover
         """Gets a textual representation of this object."""
 
-        return '%s<%s> 0x%s' % (self.__class__.__name__,
-                                self.__dict__, id(self))
+        return "%s<%s> 0x%s" % (
+            self.__class__.__name__,
+            self.__dict__,
+            id(self),
+        )
 
 
 class LocalizedStringValue(LocalizedValue):
-    default_value = ''
+    default_value = ""
 
 
 class LocalizedFileValue(LocalizedValue):
     def __getattr__(self, name: str):
-        """Proxies access to attributes to attributes of LocalizedFile"""
+        """Proxies access to attributes to attributes of LocalizedFile."""
 
         value = self.get(translation.get_language())
         if hasattr(value, name):
             return getattr(value, name)
-        raise AttributeError("'{}' object has no attribute '{}'".
-                             format(self.__class__.__name__, name))
+        raise AttributeError(
+            "'{}' object has no attribute '{}'".format(
+                self.__class__.__name__, name
+            )
+        )
 
     def __str__(self) -> str:
-        """Returns string representation of value"""
+        """Returns string representation of value."""
 
         return str(super().__str__())
 
-    @deprecation.deprecated(deprecated_in='4.6', removed_in='5.0',
-                            current_version='4.6',
-                            details='Use the translate() function instead.')
+    @deprecation.deprecated(
+        deprecated_in="4.6",
+        removed_in="5.0",
+        current_version="4.6",
+        details="Use the translate() function instead.",
+    )
     def localized(self):
-        """Returns value for current language"""
+        """Returns value for current language."""
 
         return self.get(translation.get_language())
 
 
-class LocalizedIntegerValue(LocalizedValue):
-    """All values are integers."""
-
-    default_value = None
-
+class LocalizedBooleanValue(LocalizedValue):
     def translate(self):
-        """Gets the value in the current language, or
-        in the configured fallbck language."""
+        """Gets the value in the current language, or in the configured fallbck
+        language."""
 
         value = super().translate()
-        if value is None or (isinstance(value, str) and value.strip() == ''):
+        if value is None or (isinstance(value, str) and value.strip() == ""):
             return None
 
-        return int(value)
+        if isinstance(value, bool):
+            return value
 
+        if value.lower() == "true":
+            return True
+        return False
+
+    def __bool__(self):
+        """Gets the value in the current language as a boolean."""
+        value = self.translate()
+
+        return value
+
+    def __str__(self):
+        """Returns string representation of value."""
+
+        value = self.translate()
+        return str(value) if value is not None else ""
+
+
+class LocalizedNumericValue(LocalizedValue):
     def __int__(self):
         """Gets the value in the current language as an integer."""
-
         value = self.translate()
         if value is None:
             return self.default_value
@@ -231,7 +276,46 @@ class LocalizedIntegerValue(LocalizedValue):
         return int(value)
 
     def __str__(self) -> str:
-        """Returns string representation of value"""
+        """Returns string representation of value."""
 
         value = self.translate()
-        return str(value) if value is not None else ''
+        return str(value) if value is not None else ""
+
+    def __float__(self):
+        """Gets the value in the current language as a float."""
+        value = self.translate()
+        if value is None:
+            return self.default_value
+
+        return float(value)
+
+
+class LocalizedIntegerValue(LocalizedNumericValue):
+    """All values are integers."""
+
+    default_value = None
+
+    def translate(self):
+        """Gets the value in the current language, or in the configured fallbck
+        language."""
+
+        value = super().translate()
+        if value is None or (isinstance(value, str) and value.strip() == ""):
+            return None
+
+        return int(value)
+
+
+class LocalizedFloatValue(LocalizedNumericValue):
+    """All values are floats."""
+
+    default_value = None
+
+    def translate(self):
+        """Gets the value in the current language, or in the configured
+        fallback language."""
+        value = super().translate()
+        if value is None or (isinstance(value, str) and value.strip() == ""):
+            return None
+
+        return float(value)

localized_fields/widgets.py

@@ -2,8 +2,8 @@ import copy
 
 from typing import List
 
-from django.conf import settings
 from django import forms
+from django.conf import settings
 from django.contrib.admin import widgets
 
 from .value import LocalizedValue
@@ -11,27 +11,27 @@ from .value import LocalizedValue
 
 class LocalizedFieldWidget(forms.MultiWidget):
     """Widget that has an input box for every language."""
-    template_name = 'localized_fields/multiwidget.html'
+
+    template_name = "localized_fields/multiwidget.html"
     widget = forms.Textarea
 
     def __init__(self, *args, **kwargs):
         """Initializes a new instance of :see:LocalizedFieldWidget."""
 
-        initial_widgets = [
-            copy.copy(self.widget)
-            for _ in settings.LANGUAGES
-        ]
+        initial_widgets = [copy.copy(self.widget) for _ in settings.LANGUAGES]
 
         super().__init__(initial_widgets, *args, **kwargs)
 
-        for ((lang_code, lang_name), widget) in zip(settings.LANGUAGES, self.widgets):
-            widget.attrs['lang'] = lang_code
+        for ((lang_code, lang_name), widget) in zip(
+            settings.LANGUAGES, self.widgets
+        ):
+            widget.attrs["lang"] = lang_code
             widget.lang_code = lang_code
             widget.lang_name = lang_name
 
     def decompress(self, value: LocalizedValue) -> List[str]:
-        """Decompresses the specified value so
-        it can be spread over the internal widgets.
+        """Decompresses the specified value so it can be spread over the
+        internal widgets.
 
         Arguments:
             value:
@@ -61,59 +61,77 @@ class LocalizedFieldWidget(forms.MultiWidget):
         if not isinstance(value, list):
             value = self.decompress(value)
 
-        final_attrs = context['widget']['attrs']
-        input_type = final_attrs.pop('type', None)
-        id_ = final_attrs.get('id')
+        final_attrs = context["widget"]["attrs"]
+        input_type = final_attrs.pop("type", None)
+        id_ = final_attrs.get("id")
         subwidgets = []
         for i, widget in enumerate(self.widgets):
             if input_type is not None:
                 widget.input_type = input_type
-            widget_name = '%s_%s' % (name, i)
+            widget_name = "%s_%s" % (name, i)
             try:
                 widget_value = value[i]
             except IndexError:
                 widget_value = None
             if id_:
                 widget_attrs = final_attrs.copy()
-                widget_attrs['id'] = '%s_%s' % (id_, i)
+                widget_attrs["id"] = "%s_%s" % (id_, i)
             else:
                 widget_attrs = final_attrs
-            widget_attrs = self.build_widget_attrs(widget, widget_value, widget_attrs)
-            widget_context = widget.get_context(widget_name, widget_value, widget_attrs)['widget']
-            widget_context.update(dict(
-                lang_code=widget.lang_code,
-                lang_name=widget.lang_name
-            ))
+            widget_attrs = self.build_widget_attrs(
+                widget, widget_value, widget_attrs
+            )
+            widget_context = widget.get_context(
+                widget_name, widget_value, widget_attrs
+            )["widget"]
+            widget_context.update(
+                dict(lang_code=widget.lang_code, lang_name=widget.lang_name)
+            )
             subwidgets.append(widget_context)
-        context['widget']['subwidgets'] = subwidgets
+        context["widget"]["subwidgets"] = subwidgets
         return context
 
     @staticmethod
     def build_widget_attrs(widget, value, attrs):
         attrs = dict(attrs)  # Copy attrs to avoid modifying the argument.
 
-        if (not widget.use_required_attribute(value) or not widget.is_required) \
-                and 'required' in attrs:
-            del attrs['required']
+        if (
+            not widget.use_required_attribute(value) or not widget.is_required
+        ) and "required" in attrs:
+            del attrs["required"]
 
         return attrs
 
 
 class LocalizedCharFieldWidget(LocalizedFieldWidget):
     """Widget that has an input box for every language."""
+
     widget = forms.TextInput
 
 
 class LocalizedFileWidget(LocalizedFieldWidget):
     """Widget that has an file input box for every language."""
+
     widget = forms.ClearableFileInput
 
 
 class AdminLocalizedFieldWidget(LocalizedFieldWidget):
-    template_name = 'localized_fields/admin/widget.html'
+    template_name = "localized_fields/admin/widget.html"
     widget = widgets.AdminTextareaWidget
 
 
+class AdminLocalizedBooleanFieldWidget(LocalizedFieldWidget):
+    widget = forms.Select
+
+    def __init__(self, *args, **kwargs):
+        """Initializes a new instance of :see:LocalizedBooleanFieldWidget."""
+
+        super().__init__(*args, **kwargs)
+
+        for widget in self.widgets:
+            widget.choices = [("False", False), ("True", True)]
+
+
 class AdminLocalizedCharFieldWidget(AdminLocalizedFieldWidget):
     widget = widgets.AdminTextInputWidget
 

pyproject.toml

@@ -0,0 +1,2 @@
+[tool.black]
+line-length = 80

pytest.ini

@@ -0,0 +1,7 @@
+[pytest]
+DJANGO_SETTINGS_MODULE=settings
+testpaths=tests
+addopts=-m "not benchmark"
+junit_family=legacy
+filterwarnings=
+    ignore::DeprecationWarning:localized_fields.fields.autoslug_field

requirements/base.txt

@@ -1,2 +0,0 @@
-django-postgres-extra==1.22
-deprecation==2.0.3

requirements/test.txt

@@ -1,10 +0,0 @@
--r base.txt
-
-django-autoslug==1.9.3
-django-bleach==0.3.0
-psycopg2==2.7.3.2
-coverage==4.4.2
-flake8==3.6.0
-pep8==1.7.1
-dj-database-url==0.4.2
-tox==2.9.1

settings.py

@@ -1,3 +1,4 @@
+import django
 import dj_database_url
 
 DEBUG = True
@@ -8,7 +9,7 @@ SECRET_KEY = 'this is my secret key'  # NOQA
 TEST_RUNNER = 'django.test.runner.DiscoverRunner'
 
 DATABASES = {
-    'default': dj_database_url.config(default='postgres:///localized_fields')
+    'default': dj_database_url.config(default='postgres:///localized_fields'),
 }
 
 DATABASES['default']['ENGINE'] = 'psqlextra.backend'
@@ -51,6 +52,12 @@ MIDDLEWARE = [
     'django.contrib.auth.middleware.AuthenticationMiddleware',
 ]
 
+# See: https://github.com/psycopg/psycopg2/issues/1293
+if django.VERSION >= (3, 1):
+    USE_TZ = True
+    USE_I18N = True
+    TIME_ZONE = 'UTC'
+
 # set to a lower number than the default, since
 # we want the tests to be fast, default is 100
 LOCALIZED_FIELDS_MAX_RETRIES = 3

setup.cfg

@@ -1,8 +1,12 @@
 [flake8]
-max-line-length = 120
-ignore = E252, W605
+ignore = E252,E501,W503
 exclude = env,.tox,.git,config/settings,*/migrations/*,*/static/CACHE/*,docs,node_modules
 
-[pep8]
-max-line-length = 120
-exclude=env,.tox,.git,*/migrations/*,*/static/CACHE/*,docs,node_modules
+[isort]
+line_length=80
+multi_line_output=3
+lines_between_types=1
+include_trailing_comma=True
+not_skip=__init__.py
+known_standard_library=dataclasses
+known_third_party=django_bleach,bleach,pytest

setup.py

@@ -1,5 +1,5 @@
-import os
 import distutils.cmd
+import os
 import subprocess
 
 from setuptools import find_packages, setup
@@ -28,41 +28,168 @@ def create_command(text, commands):
     return CustomCommand
 
 
-with open(os.path.join(os.path.dirname(__file__), 'README.rst'), encoding='utf-8') as readme:
+with open(
+    os.path.join(os.path.dirname(__file__), "README.md"), encoding="utf-8"
+) as readme:
     README = readme.read()
 
+
 setup(
-    name='django-localized-fields',
-    version='5.4',
-    packages=find_packages(exclude=['tests']),
+    name="django-localized-fields",
+    version="6.8b5",
+    packages=find_packages(exclude=["tests"]),
     include_package_data=True,
-    license='MIT License',
-    description='Implementation of localized model fields using PostgreSQL HStore fields.',
+    license="MIT License",
+    description="Implementation of localized model fields using PostgreSQL HStore fields.",
     long_description=README,
-    url='https://github.com/SectorLabs/django-localized-fields',
-    author='Sector Labs',
-    author_email='open-source@sectorlabs.ro',
-    keywords=['django', 'localized', 'language', 'models', 'fields'],
-    install_requires=[
-        'django-postgres-extra>=1.22',
-        'Django>=1.11',
-        'deprecation==2.0.3'
+    long_description_content_type="text/markdown",
+    url="https://github.com/SectorLabs/django-localized-fields",
+    author="Sector Labs",
+    author_email="open-source@sectorlabs.ro",
+    keywords=[
+        "django",
+        "localized",
+        "language",
+        "models",
+        "fields",
+        "postgres",
+        "hstore",
+        "i18n",
     ],
     classifiers=[
-        'Environment :: Web Environment',
-        'Framework :: Django',
-        'Intended Audience :: Developers',
-        'License :: OSI Approved :: MIT License',
-        'Operating System :: OS Independent',
-        'Programming Language :: Python',
-        'Programming Language :: Python :: 3.5',
-        'Topic :: Internet :: WWW/HTTP',
-        'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
+        "Environment :: Web Environment",
+        "Framework :: Django",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 3.6",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Topic :: Internet :: WWW/HTTP",
+        "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
     ],
+    python_requires=">=3.6",
+    install_requires=[
+        "Django>=2.0",
+        "django-postgres-extra>=2.0,<3.0",
+        "deprecation>=2.0.7",
+    ],
+    extras_require={
+        ':python_version <= "3.6"': ["dataclasses"],
+        "docs": ["Sphinx==2.2.0", "sphinx-rtd-theme==0.4.3"],
+        "test": [
+            "tox==3.28.0",
+            "pytest==7.0.1",
+            "pytest-django==4.5.2",
+            "pytest-cov==2.12.1",
+            "dj-database-url==0.5.0",
+            "django-autoslug==1.9.9",
+            "django-bleach==0.9.0",
+            "psycopg2==2.9.8",
+        ],
+        "analysis": [
+            "black==22.3.0",
+            "flake8==3.7.7",
+            "autoflake==1.3",
+            "autopep8==1.4.4",
+            "isort==4.3.20",
+            "sl-docformatter==1.4",
+            "click==8.0.2",
+        ],
+    },
     cmdclass={
-        'lint': create_command(
-            'Lints the code',
-            [['flake8', 'setup.py', 'localized_fields', 'tests']],
+        "lint": create_command(
+            "Lints the code",
+            [["flake8", "setup.py", "localized_fields", "tests"]],
+        ),
+        "lint_fix": create_command(
+            "Lints the code",
+            [
+                [
+                    "autoflake",
+                    "--remove-all-unused-imports",
+                    "-i",
+                    "-r",
+                    "setup.py",
+                    "localized_fields",
+                    "tests",
+                ],
+                [
+                    "autopep8",
+                    "-i",
+                    "-r",
+                    "setup.py",
+                    "localized_fields",
+                    "tests",
+                ],
+            ],
+        ),
+        "format": create_command(
+            "Formats the code",
+            [["black", "setup.py", "localized_fields", "tests"]],
+        ),
+        "format_verify": create_command(
+            "Checks if the code is auto-formatted",
+            [["black", "--check", "setup.py", "localized_fields", "tests"]],
+        ),
+        "format_docstrings": create_command(
+            "Auto-formats doc strings", [["docformatter", "-r", "-i", "."]]
+        ),
+        "format_docstrings_verify": create_command(
+            "Verifies that doc strings are properly formatted",
+            [["docformatter", "-r", "-c", "."]],
+        ),
+        "sort_imports": create_command(
+            "Automatically sorts imports",
+            [
+                ["isort", "setup.py"],
+                ["isort", "-rc", "localized_fields"],
+                ["isort", "-rc", "tests"],
+            ],
+        ),
+        "sort_imports_verify": create_command(
+            "Verifies all imports are properly sorted.",
+            [
+                ["isort", "-c", "setup.py"],
+                ["isort", "-c", "-rc", "localized_fields"],
+                ["isort", "-c", "-rc", "tests"],
+            ],
+        ),
+        "fix": create_command(
+            "Automatically format code and fix linting errors",
+            [
+                ["python", "setup.py", "format"],
+                ["python", "setup.py", "format_docstrings"],
+                ["python", "setup.py", "sort_imports"],
+                ["python", "setup.py", "lint_fix"],
+            ],
+        ),
+        "verify": create_command(
+            "Verifies whether the code is auto-formatted and has no linting errors",
+            [
+                ["python", "setup.py", "format_verify"],
+                ["python", "setup.py", "format_docstrings_verify"],
+                ["python", "setup.py", "sort_imports_verify"],
+                ["python", "setup.py", "lint"],
+            ],
+        ),
+        "test": create_command(
+            "Runs all the tests",
+            [
+                [
+                    "pytest",
+                    "--cov=localized_fields",
+                    "--cov-report=term",
+                    "--cov-report=xml:reports/xml",
+                    "--cov-report=html:reports/html",
+                    "--junitxml=reports/junit/tests.xml",
+                    "--reuse-db",
+                ]
+            ],
         ),
     },
 )

tests/data.py

@@ -2,12 +2,11 @@ from django.conf import settings
 
 
 def get_init_values() -> dict:
-    """Gets a test dictionary containing a key
-    for every language."""
+    """Gets a test dictionary containing a key for every language."""
 
     keys = {}
 
     for lang_code, lang_name in settings.LANGUAGES:
-        keys[lang_code] = 'value in %s' % lang_name
+        keys[lang_code] = "value in %s" % lang_name
 
     return keys

tests/fake_model.py

@@ -1,20 +1,20 @@
 import uuid
 
+from django.contrib.postgres.operations import HStoreExtension
 from django.db import connection, migrations
 from django.db.migrations.executor import MigrationExecutor
-from django.contrib.postgres.operations import HStoreExtension
 
 from localized_fields.models import LocalizedModel
 
 
 def define_fake_model(fields=None, model_base=LocalizedModel, meta_options={}):
-    name = str(uuid.uuid4()).replace('-', '')[:8]
+    name = str(uuid.uuid4()).replace("-", "")[:8]
 
     attributes = {
-        'app_label': 'tests',
-        '__module__': __name__,
-        '__name__': name,
-        'Meta': type('Meta', (object,), meta_options)
+        "app_label": "tests",
+        "__module__": __name__,
+        "__name__": name,
+        "Meta": type("Meta", (object,), meta_options),
     }
 
     if fields:
@@ -30,7 +30,6 @@ def get_fake_model(fields=None, model_base=LocalizedModel, meta_options={}):
     model = define_fake_model(fields, model_base, meta_options)
 
     class TestProject:
-
         def clone(self, *_args, **_kwargs):
             return self
 
@@ -44,7 +43,8 @@ def get_fake_model(fields=None, model_base=LocalizedModel, meta_options={}):
     with connection.schema_editor() as schema_editor:
         migration_executor = MigrationExecutor(schema_editor.connection)
         migration_executor.apply_migration(
-            TestProject(), TestMigration('eh', 'postgres_extra'))
+            TestProject(), TestMigration("eh", "postgres_extra")
+        )
 
         schema_editor.create_model(model)
 

tests/test_admin.py

@@ -4,9 +4,8 @@ from django.contrib.admin.checks import check_admin_app
 from django.db import models
 from django.test import TestCase
 
-from localized_fields.fields import LocalizedField
 from localized_fields.admin import LocalizedFieldsAdminMixin
-
+from localized_fields.fields import LocalizedField
 from tests.fake_model import get_fake_model
 
 
@@ -22,16 +21,13 @@ class LocalizedFieldsAdminMixinTestCase(TestCase):
 
         super(LocalizedFieldsAdminMixinTestCase, cls).setUpClass()
 
-        cls.TestRelModel = get_fake_model(
-            {
-                'description': LocalizedField()
-            }
-        )
+        cls.TestRelModel = get_fake_model({"description": LocalizedField()})
         cls.TestModel = get_fake_model(
             {
-                'title': LocalizedField(),
-                'rel': models.ForeignKey(cls.TestRelModel,
-                                         on_delete=models.CASCADE)
+                "title": LocalizedField(),
+                "rel": models.ForeignKey(
+                    cls.TestRelModel, on_delete=models.CASCADE
+                ),
             }
         )
 
@@ -43,8 +39,8 @@ class LocalizedFieldsAdminMixinTestCase(TestCase):
 
     @classmethod
     def test_model_admin(cls):
-        """Tests whether :see:LocalizedFieldsAdminMixin
-        mixin are works with admin.ModelAdmin"""
+        """Tests whether :see:LocalizedFieldsAdminMixin mixin are works with
+        admin.ModelAdmin."""
 
         @admin.register(cls.TestModel)
         class TestModelAdmin(LocalizedFieldsAdminMixin, admin.ModelAdmin):
@@ -54,34 +50,32 @@ class LocalizedFieldsAdminMixinTestCase(TestCase):
 
     @classmethod
     def test_stackedmodel_admin(cls):
-        """Tests whether :see:LocalizedFieldsAdminMixin mixin are works
-        with admin.StackedInline"""
+        """Tests whether :see:LocalizedFieldsAdminMixin mixin are works with
+        admin.StackedInline."""
 
-        class TestModelStackedInline(LocalizedFieldsAdminMixin,
-                                     admin.StackedInline):
+        class TestModelStackedInline(
+            LocalizedFieldsAdminMixin, admin.StackedInline
+        ):
             model = cls.TestModel
 
         @admin.register(cls.TestRelModel)
         class TestRelModelAdmin(admin.ModelAdmin):
-            inlines = [
-                TestModelStackedInline,
-            ]
+            inlines = [TestModelStackedInline]
 
         assert len(check_admin_app(apps.get_app_configs())) == 0
 
     @classmethod
     def test_tabularmodel_admin(cls):
-        """Tests whether :see:LocalizedFieldsAdminMixin mixin are works
-        with admin.TabularInline"""
+        """Tests whether :see:LocalizedFieldsAdminMixin mixin are works with
+        admin.TabularInline."""
 
-        class TestModelTabularInline(LocalizedFieldsAdminMixin,
-                                     admin.TabularInline):
+        class TestModelTabularInline(
+            LocalizedFieldsAdminMixin, admin.TabularInline
+        ):
             model = cls.TestModel
 
         @admin.register(cls.TestRelModel)
         class TestRelModelAdmin(admin.ModelAdmin):
-            inlines = [
-                TestModelTabularInline,
-            ]
+            inlines = [TestModelTabularInline]
 
         assert len(check_admin_app(apps.get_app_configs())) == 0

tests/test_bleach_field.py

@@ -1,18 +1,30 @@
-import bleach
+"""isort:skip_file."""
+
+import sys
+import html
+
+import pytest
 
 from django.conf import settings
 from django.test import TestCase
-from django_bleach.utils import get_bleach_default_options
 
 from localized_fields.fields import LocalizedBleachField
 from localized_fields.value import LocalizedValue
 
+try:
+    import bleach
 
-class TestModel:
+    from django_bleach.utils import get_bleach_default_options
+except ImportError:
+    if sys.version_info >= (3, 9):
+        pytest.skip("feature not ready for python 3.9", allow_module_level=True)
+
+
+class ModelTest:
     """Used to declare a bleach-able field on."""
 
     def __init__(self, value):
-        """Initializes a new instance of :see:TestModel.
+        """Initializes a new instance of :see:ModelTest.
 
         Arguments:
             The value to initialize with.
@@ -25,8 +37,8 @@ class LocalizedBleachFieldTestCase(TestCase):
     """Tests the :see:LocalizedBleachField class."""
 
     def test_pre_save(self):
-        """Tests whether the :see:pre_save function
-        bleaches all values in a :see:LocalizedValue."""
+        """Tests whether the :see:pre_save function bleaches all values in a
+        :see:LocalizedValue."""
 
         value = self._get_test_value()
         model, field = self._get_test_model(value)
@@ -35,8 +47,8 @@ class LocalizedBleachFieldTestCase(TestCase):
         self._validate(value, bleached_value)
 
     def test_pre_save_none(self):
-        """Tests whether the :see:pre_save function
-        works properly when specifying :see:None."""
+        """Tests whether the :see:pre_save function works properly when
+        specifying :see:None."""
 
         model, field = self._get_test_model(None)
 
@@ -44,9 +56,8 @@ class LocalizedBleachFieldTestCase(TestCase):
         assert not bleached_value
 
     def test_pre_save_none_values(self):
-        """Tests whether the :see:pre_save function
-        works properly when one of the languages has
-        no text and is None."""
+        """Tests whether the :see:pre_save function works properly when one of
+        the languages has no text and is None."""
 
         value = self._get_test_value()
         value.set(settings.LANGUAGE_CODE, None)
@@ -56,16 +67,25 @@ class LocalizedBleachFieldTestCase(TestCase):
         bleached_value = field.pre_save(model, False)
         self._validate(value, bleached_value)
 
+    def test_pre_save_do_not_escape(self):
+        """Tests whether the :see:pre_save function works properly when field
+        escape argument is set to False."""
+
+        value = self._get_test_value()
+        model, field = self._get_test_model(value, escape=False)
+
+        bleached_value = field.pre_save(model, False)
+        self._validate(value, bleached_value, False)
+
     @staticmethod
-    def _get_test_model(value):
-        """Gets a test model and a artifically
-        constructed :see:LocalizedBleachField
-        instance to test with."""
+    def _get_test_model(value, escape=True):
+        """Gets a test model and an artificially constructed
+        :see:LocalizedBleachField instance to test with."""
 
-        model = TestModel(value)
+        model = ModelTest(value)
 
-        field = LocalizedBleachField()
-        field.attname = 'value'
+        field = LocalizedBleachField(escape=escape)
+        field.attname = "value"
         return model, field
 
     @staticmethod
@@ -75,14 +95,14 @@ class LocalizedBleachFieldTestCase(TestCase):
         value = LocalizedValue()
 
         for lang_code, lang_name in settings.LANGUAGES:
-            value.set(lang_code, '<script>%s</script>' % lang_name)
+            value.set(lang_code, "<script>%s</script>" % lang_name)
 
         return value
 
     @staticmethod
-    def _validate(non_bleached_value, bleached_value):
-        """Validates whether the specified non-bleached
-        value ended up being correctly bleached.
+    def _validate(non_bleached_value, bleached_value, escaped_value=True):
+        """Validates whether the specified non-bleached value ended up being
+        correctly bleached.
 
         Arguments:
             non_bleached_value:
@@ -91,15 +111,20 @@ class LocalizedBleachFieldTestCase(TestCase):
             bleached_value:
                 The value after bleaching.
         """
-
         for lang_code, _ in settings.LANGUAGES:
             if not non_bleached_value.get(lang_code):
                 assert not bleached_value.get(lang_code)
                 continue
 
-            expected_value = bleach.clean(
-                non_bleached_value.get(lang_code),
-                get_bleach_default_options()
+            cleaned_value = bleach.clean(
+                non_bleached_value.get(lang_code)
+                if escaped_value
+                else html.unescape(non_bleached_value.get(lang_code)),
+                get_bleach_default_options(),
+            )
+
+            expected_value = (
+                cleaned_value if escaped_value else html.unescape(cleaned_value)
             )
 
             assert bleached_value.get(lang_code) == expected_value

tests/test_boolean_field.py

@@ -0,0 +1,211 @@
+from django.conf import settings
+from django.db import connection
+from django.db.utils import IntegrityError
+from django.test import TestCase
+from django.utils import translation
+
+from localized_fields.fields import LocalizedBooleanField
+from localized_fields.value import LocalizedBooleanValue
+
+from .fake_model import get_fake_model
+
+
+class LocalizedBooleanFieldTestCase(TestCase):
+    """Tests whether the :see:LocalizedBooleanField and
+    :see:LocalizedIntegerValue works properly."""
+
+    TestModel = None
+
+    @classmethod
+    def setUpClass(cls):
+        super().setUpClass()
+
+        cls.TestModel = get_fake_model({"translated": LocalizedBooleanField()})
+
+    def test_basic(self):
+        """Tests the basics of storing boolean values."""
+
+        obj = self.TestModel()
+        for lang_code, _ in settings.LANGUAGES:
+            obj.translated.set(lang_code, False)
+        obj.save()
+
+        obj = self.TestModel.objects.all().first()
+        for lang_code, _ in settings.LANGUAGES:
+            assert obj.translated.get(lang_code) is False
+
+    def test_primary_language_required(self):
+        """Tests whether the primary language is required by default and all
+        other languages are optional."""
+
+        # not filling in anything should raise IntegrityError,
+        # the primary language is required
+        with self.assertRaises(IntegrityError):
+            obj = self.TestModel()
+            obj.save()
+
+        # when filling all other languages besides the primary language
+        # should still raise an error because the primary is always required
+        with self.assertRaises(IntegrityError):
+            obj = self.TestModel()
+            for lang_code, _ in settings.LANGUAGES:
+                if lang_code == settings.LANGUAGE_CODE:
+                    continue
+                obj.translated.set(lang_code, True)
+            obj.save()
+
+    def test_default_value_none(self):
+        """Tests whether the default value for optional languages is
+        NoneType."""
+
+        obj = self.TestModel()
+        obj.translated.set(settings.LANGUAGE_CODE, True)
+        obj.save()
+
+        for lang_code, _ in settings.LANGUAGES:
+            if lang_code == settings.LANGUAGE_CODE:
+                continue
+
+            assert obj.translated.get(lang_code) is None
+
+    def test_translate(self):
+        """Tests whether casting the value to a boolean results in the value
+        being returned in the currently active language as a boolean."""
+
+        obj = self.TestModel()
+        for lang_code, _ in settings.LANGUAGES:
+            obj.translated.set(lang_code, True)
+        obj.save()
+
+        obj.refresh_from_db()
+        for lang_code, _ in settings.LANGUAGES:
+            with translation.override(lang_code):
+                assert bool(obj.translated) is True
+                assert obj.translated.translate() is True
+
+    def test_translate_primary_fallback(self):
+        """Tests whether casting the value to a boolean results in the value
+        being returned in the active language and falls back to the primary
+        language if there is no value in that language."""
+
+        obj = self.TestModel()
+        obj.translated.set(settings.LANGUAGE_CODE, True)
+
+        secondary_language = settings.LANGUAGES[-1][0]
+        assert obj.translated.get(secondary_language) is None
+
+        with translation.override(secondary_language):
+            assert obj.translated.translate() is True
+            assert bool(obj.translated) is True
+
+    def test_get_default_value(self):
+        """Tests whether getting the value in a specific language properly
+        returns the specified default in case it is not available."""
+
+        obj = self.TestModel()
+        obj.translated.set(settings.LANGUAGE_CODE, True)
+
+        secondary_language = settings.LANGUAGES[-1][0]
+        assert obj.translated.get(secondary_language) is None
+        assert obj.translated.get(secondary_language, False) is False
+
+    def test_completely_optional(self):
+        """Tests whether having all languages optional works properly."""
+
+        model = get_fake_model(
+            {
+                "translated": LocalizedBooleanField(
+                    null=True, required=[], blank=True
+                )
+            }
+        )
+
+        obj = model()
+        obj.save()
+
+        for lang_code, _ in settings.LANGUAGES:
+            assert getattr(obj.translated, lang_code) is None
+
+    def test_store_string(self):
+        """Tests whether the field properly raises an error when trying to
+        store a non-boolean."""
+
+        for lang_code, _ in settings.LANGUAGES:
+            obj = self.TestModel()
+            with self.assertRaises(IntegrityError):
+                obj.translated.set(lang_code, "haha")
+                obj.save()
+
+    def test_none_if_illegal_value_stored(self):
+        """Tests whether None is returned for a language if the value stored in
+        the database is not a boolean."""
+
+        obj = self.TestModel()
+        obj.translated.set(settings.LANGUAGE_CODE, False)
+        obj.save()
+
+        with connection.cursor() as cursor:
+            table_name = self.TestModel._meta.db_table
+            cursor.execute("update %s set translated = 'en=>haha'" % table_name)
+
+        with self.assertRaises(ValueError):
+            obj.refresh_from_db()
+
+    def test_default_value(self):
+        """Tests whether a default is properly set when specified."""
+
+        model = get_fake_model(
+            {
+                "translated": LocalizedBooleanField(
+                    default={settings.LANGUAGE_CODE: True}
+                )
+            }
+        )
+
+        obj = model.objects.create()
+        assert obj.translated.get(settings.LANGUAGE_CODE) is True
+
+        obj = model()
+        for lang_code, _ in settings.LANGUAGES:
+            obj.translated.set(lang_code, None)
+        obj.save()
+
+        for lang_code, _ in settings.LANGUAGES:
+            if lang_code == settings.LANGUAGE_CODE:
+                assert obj.translated.get(lang_code) is True
+            else:
+                assert obj.translated.get(lang_code) is None
+
+    def test_default_value_update(self):
+        """Tests whether a default is properly set when specified during
+        updates."""
+
+        model = get_fake_model(
+            {
+                "translated": LocalizedBooleanField(
+                    default={settings.LANGUAGE_CODE: True}, null=True
+                )
+            }
+        )
+
+        obj = model.objects.create(
+            translated=LocalizedBooleanValue({settings.LANGUAGE_CODE: False})
+        )
+        assert obj.translated.get(settings.LANGUAGE_CODE) is False
+
+        model.objects.update(
+            translated=LocalizedBooleanValue({settings.LANGUAGE_CODE: None})
+        )
+        obj.refresh_from_db()
+        assert obj.translated.get(settings.LANGUAGE_CODE) is True
+
+    def test_callable_default_value(self):
+        output = {"en": True}
+
+        def func():
+            return output
+
+        model = get_fake_model({"test": LocalizedBooleanField(default=func)})
+        obj = model.objects.create()
+
+        assert obj.test["en"] == output["en"]

tests/test_bulk.py

@@ -7,26 +7,34 @@ from .fake_model import get_fake_model
 
 
 class LocalizedBulkTestCase(TestCase):
-    """Tests bulk operations with data structures provided
-    by the django-localized-fields library."""
+    """Tests bulk operations with data structures provided by the django-
+    localized-fields library."""
 
     @staticmethod
     def test_localized_bulk_insert():
-        """Tests whether bulk inserts work properly when using
-        a :see:LocalizedUniqueSlugField in the model."""
+        """Tests whether bulk inserts work properly when using a
+        :see:LocalizedUniqueSlugField in the model."""
 
         model = get_fake_model(
             {
-                'name': LocalizedField(),
-                'slug': LocalizedUniqueSlugField(populate_from='name', include_time=True),
-                'score': models.IntegerField()
+                "name": LocalizedField(),
+                "slug": LocalizedUniqueSlugField(
+                    populate_from="name", include_time=True
+                ),
+                "score": models.IntegerField(),
             }
         )
 
         to_create = [
-            model(name={'en': 'english name 1', 'ro': 'romanian name 1'}, score=1),
-            model(name={'en': 'english name 2', 'ro': 'romanian name 2'}, score=2),
-            model(name={'en': 'english name 3', 'ro': 'romanian name 3'}, score=3)
+            model(
+                name={"en": "english name 1", "ro": "romanian name 1"}, score=1
+            ),
+            model(
+                name={"en": "english name 2", "ro": "romanian name 2"}, score=2
+            ),
+            model(
+                name={"en": "english name 3", "ro": "romanian name 3"}, score=3
+            ),
         ]
 
         model.objects.bulk_create(to_create)
@@ -34,9 +42,7 @@ class LocalizedBulkTestCase(TestCase):
 
         for obj in to_create:
             obj_db = model.objects.filter(
-                name__en=obj.name.en,
-                name__ro=obj.name.ro,
-                score=obj.score
+                name__en=obj.name.en, name__ro=obj.name.ro, score=obj.score
             ).first()
 
             assert obj_db

tests/test_expressions.py

@@ -1,12 +1,12 @@
-from django.test import TestCase
-from django.db import models
-from django.utils import translation
 from django.conf import settings
 from django.contrib.postgres.aggregates import ArrayAgg
+from django.db import models
+from django.test import TestCase
+from django.utils import translation
 
+from localized_fields.expressions import LocalizedRef
 from localized_fields.fields import LocalizedField
 from localized_fields.value import LocalizedValue
-from localized_fields.expressions import LocalizedRef
 
 from .fake_model import get_fake_model
 
@@ -24,15 +24,17 @@ class LocalizedExpressionsTestCase(TestCase):
         super(LocalizedExpressionsTestCase, cls).setUpClass()
 
         cls.TestModel1 = get_fake_model(
-            {
-                'name': models.CharField(null=False, blank=False, max_length=255),
-            }
+            {"name": models.CharField(null=False, blank=False, max_length=255)}
         )
 
         cls.TestModel2 = get_fake_model(
             {
-                'text': LocalizedField(),
-                'other': models.ForeignKey(cls.TestModel1, related_name='features', on_delete=models.CASCADE)
+                "text": LocalizedField(),
+                "other": models.ForeignKey(
+                    cls.TestModel1,
+                    related_name="features",
+                    on_delete=models.CASCADE,
+                ),
             }
         )
 
@@ -40,24 +42,28 @@ class LocalizedExpressionsTestCase(TestCase):
     def test_localized_ref(cls):
         """Tests whether the :see:LocalizedRef expression properly works."""
 
-        obj = cls.TestModel1.objects.create(name='bla bla')
+        obj = cls.TestModel1.objects.create(name="bla bla")
         for i in range(0, 10):
             cls.TestModel2.objects.create(
-                text=LocalizedValue(dict(en='text_%d_en' % i, ro='text_%d_ro' % i, nl='text_%d_nl' % i)),
-                other=obj
+                text=LocalizedValue(
+                    dict(
+                        en="text_%d_en" % i,
+                        ro="text_%d_ro" % i,
+                        nl="text_%d_nl" % i,
+                    )
+                ),
+                other=obj,
             )
 
         def create_queryset(ref):
-            return (
-                cls.TestModel1.objects
-                .annotate(mytexts=ref)
-                .values_list('mytexts', flat=True)
+            return cls.TestModel1.objects.annotate(mytexts=ref).values_list(
+                "mytexts", flat=True
             )
 
         # assert that it properly selects the currently active language
         for lang_code, _ in settings.LANGUAGES:
             translation.activate(lang_code)
-            queryset = create_queryset(LocalizedRef('features__text'))
+            queryset = create_queryset(LocalizedRef("features__text"))
 
             for index, value in enumerate(queryset):
                 assert translation.get_language() in value
@@ -66,19 +72,21 @@ class LocalizedExpressionsTestCase(TestCase):
         # ensure that the default language is used in case no
         # language is active at all
         translation.deactivate_all()
-        queryset = create_queryset(LocalizedRef('features__text'))
+        queryset = create_queryset(LocalizedRef("features__text"))
         for index, value in enumerate(queryset):
             assert settings.LANGUAGE_CODE in value
             assert str(index) in value
 
         # ensures that overriding the language works properly
-        queryset = create_queryset(LocalizedRef('features__text', 'ro'))
+        queryset = create_queryset(LocalizedRef("features__text", "ro"))
         for index, value in enumerate(queryset):
-            assert 'ro' in value
+            assert "ro" in value
             assert str(index) in value
 
         # ensures that using this in combination with ArrayAgg works properly
-        queryset = create_queryset(ArrayAgg(LocalizedRef('features__text', 'ro'))).first()
+        queryset = create_queryset(
+            ArrayAgg(LocalizedRef("features__text", "ro"))
+        ).first()
         assert isinstance(queryset, list)
         for value in queryset:
-            assert 'ro' in value
+            assert "ro" in value

tests/test_field.py

@@ -18,8 +18,8 @@ class LocalizedFieldTestCase(TestCase):
 
     @staticmethod
     def test_init():
-        """Tests whether the :see:__init__ function
-        correctly handles parameters"""
+        """Tests whether the :see:__init__ function correctly handles
+        parameters."""
 
         field = LocalizedField(blank=True)
         assert field.required == []
@@ -28,16 +28,17 @@ class LocalizedFieldTestCase(TestCase):
         assert field.required == [settings.LANGUAGE_CODE]
 
         field = LocalizedField(required=True)
-        assert field.required == [lang_code for lang_code, _ in
-                                  settings.LANGUAGES]
+        assert field.required == [
+            lang_code for lang_code, _ in settings.LANGUAGES
+        ]
 
         field = LocalizedField(required=False)
         assert field.required == []
 
     @staticmethod
     def test_from_db_value():
-        """Tests whether the :see:from_db_value function
-        produces the expected :see:LocalizedValue."""
+        """Tests whether the :see:from_db_value function produces the expected
+        :see:LocalizedValue."""
 
         input_data = get_init_values()
         localized_value = LocalizedField().from_db_value(input_data)
@@ -47,8 +48,8 @@ class LocalizedFieldTestCase(TestCase):
 
     @staticmethod
     def test_from_db_value_none():
-        """Tests whether the :see:from_db_value function
-        correctly handles None values."""
+        """Tests whether the :see:from_db_value function correctly handles None
+        values."""
 
         localized_value = LocalizedField().from_db_value(None)
 
@@ -56,9 +57,8 @@ class LocalizedFieldTestCase(TestCase):
             assert localized_value.get(lang_code) is None
 
     def test_from_db_value_none_return_none(self):
-        """Tests whether the :see:from_db_value function
-        correctly handles None values when LOCALIZED_FIELDS_EXPERIMENTAL
-        is set to True."""
+        """Tests whether the :see:from_db_value function correctly handles None
+        values when LOCALIZED_FIELDS_EXPERIMENTAL is set to True."""
 
         with self.settings(LOCALIZED_FIELDS_EXPERIMENTAL=True):
             localized_value = LocalizedField.from_db_value(None)
@@ -67,8 +67,8 @@ class LocalizedFieldTestCase(TestCase):
 
     @staticmethod
     def test_to_python():
-        """Tests whether the :see:to_python function
-        produces the expected :see:LocalizedValue."""
+        """Tests whether the :see:to_python function produces the expected
+        :see:LocalizedValue."""
 
         input_data = get_init_values()
         localized_value = LocalizedField().to_python(input_data)
@@ -78,17 +78,16 @@ class LocalizedFieldTestCase(TestCase):
 
     @staticmethod
     def test_to_python_non_json():
-        """Tests whether the :see:to_python function
-        properly handles a string that is not JSON."""
+        """Tests whether the :see:to_python function properly handles a string
+        that is not JSON."""
 
-        localized_value = LocalizedField().to_python('my value')
-        assert localized_value.get() == 'my value'
+        localized_value = LocalizedField().to_python("my value")
+        assert localized_value.get() == "my value"
 
     @staticmethod
     def test_to_python_none():
-        """Tests whether the :see:to_python function
-        produces the expected :see:LocalizedValue
-        instance when it is passes None."""
+        """Tests whether the :see:to_python function produces the expected
+        :see:LocalizedValue instance when it is passes None."""
 
         localized_value = LocalizedField().to_python(None)
         assert localized_value
@@ -98,9 +97,8 @@ class LocalizedFieldTestCase(TestCase):
 
     @staticmethod
     def test_to_python_non_dict():
-        """Tests whether the :see:to_python function produces
-        the expected :see:LocalizedValue when it is
-        passed a non-dictionary value."""
+        """Tests whether the :see:to_python function produces the expected
+        :see:LocalizedValue when it is passed a non-dictionary value."""
 
         localized_value = LocalizedField().to_python(list())
         assert localized_value
@@ -110,9 +108,8 @@ class LocalizedFieldTestCase(TestCase):
 
     @staticmethod
     def test_to_python_str():
-        """Tests whether the :see:to_python function produces
-        the expected :see:LocalizedValue when it is
-        passed serialized string value."""
+        """Tests whether the :see:to_python function produces the expected
+        :see:LocalizedValue when it is passed serialized string value."""
 
         serialized_str = json.dumps(get_init_values())
         localized_value = LocalizedField().to_python(serialized_str)
@@ -124,8 +121,8 @@ class LocalizedFieldTestCase(TestCase):
 
     @staticmethod
     def test_get_prep_value():
-        """"Tests whether the :see:get_prep_value function
-        produces the expected dictionary."""
+        """Tests whether the :see:get_prep_value function produces the expected
+        dictionary."""
 
         input_data = get_init_values()
         localized_value = LocalizedValue(input_data)
@@ -138,25 +135,24 @@ class LocalizedFieldTestCase(TestCase):
 
     @staticmethod
     def test_get_prep_value_none():
-        """Tests whether the :see:get_prep_value function
-        produces the expected output when it is passed None."""
+        """Tests whether the :see:get_prep_value function produces the expected
+        output when it is passed None."""
 
         output_data = LocalizedField().get_prep_value(None)
         assert not output_data
 
     @staticmethod
     def test_get_prep_value_no_localized_value():
-        """Tests whether the :see:get_prep_value function
-        produces the expected output when it is passed a
-        non-LocalizedValue value."""
+        """Tests whether the :see:get_prep_value function produces the expected
+        output when it is passed a non-LocalizedValue value."""
 
-        output_data = LocalizedField().get_prep_value(['huh'])
+        output_data = LocalizedField().get_prep_value(["huh"])
         assert not output_data
 
     def test_get_prep_value_clean(self):
-        """Tests whether the :see:get_prep_value produces
-        None as the output when it is passed an empty, but
-        valid LocalizedValue value but, only when null=True."""
+        """Tests whether the :see:get_prep_value produces None as the output
+        when it is passed an empty, but valid LocalizedValue value but, only
+        when null=True."""
 
         localized_value = LocalizedValue()
 
@@ -165,17 +161,14 @@ class LocalizedFieldTestCase(TestCase):
 
         assert not LocalizedField(null=True).get_prep_value(localized_value)
         assert not LocalizedField().clean(None)
-        assert not LocalizedField().clean(['huh'])
+        assert not LocalizedField().clean(["huh"])
 
     @staticmethod
     def test_formfield():
-        """Tests whether the :see:formfield function
-        correctly returns a valid form."""
+        """Tests whether the :see:formfield function correctly returns a valid
+        form."""
 
-        assert isinstance(
-            LocalizedField().formfield(),
-            LocalizedFieldForm
-        )
+        assert isinstance(LocalizedField().formfield(), LocalizedFieldForm)
 
         # case optional filling
         field = LocalizedField(blank=True, required=[])
@@ -190,7 +183,7 @@ class LocalizedFieldTestCase(TestCase):
             assert not field.required
 
         # case required for specific languages
-        required_langs = ['ro', 'nl']
+        required_langs = ["ro", "nl"]
         field = LocalizedField(blank=False, required=required_langs)
         assert field.formfield().required
         for field in field.formfield().fields:
@@ -206,31 +199,31 @@ class LocalizedFieldTestCase(TestCase):
             assert field.required
 
     def test_descriptor_user_defined_primary_key(self):
-        """Tests that descriptor works even when primary key is user defined."""
-        model = get_fake_model(dict(
-            slug=models.SlugField(primary_key=True),
-            title=LocalizedField()
-        ))
+        """Tests that descriptor works even when primary key is user
+        defined."""
+        model = get_fake_model(
+            dict(
+                slug=models.SlugField(primary_key=True), title=LocalizedField()
+            )
+        )
 
-        obj = model.objects.create(slug='test', title='test')
-        assert obj.title == 'test'
+        obj = model.objects.create(slug="test", title="test")
+        assert obj.title == "test"
 
     def test_required_all(self):
-        """Tests whether passing required=True properly validates
-        that all languages are filled in."""
+        """Tests whether passing required=True properly validates that all
+        languages are filled in."""
 
-        model = get_fake_model(dict(
-            title=LocalizedField(required=True)
-        ))
+        model = get_fake_model(dict(title=LocalizedField(required=True)))
 
         with self.assertRaises(IntegrityError):
-            model.objects.create(title=dict(ro='romanian', nl='dutch'))
+            model.objects.create(title=dict(ro="romanian", nl="dutch"))
 
         with self.assertRaises(IntegrityError):
-            model.objects.create(title=dict(nl='dutch'))
+            model.objects.create(title=dict(nl="dutch"))
 
         with self.assertRaises(IntegrityError):
-            model.objects.create(title=dict(random='random'))
+            model.objects.create(title=dict(random="random"))
 
         with self.assertRaises(IntegrityError):
             model.objects.create(title=dict())
@@ -239,28 +232,27 @@ class LocalizedFieldTestCase(TestCase):
             model.objects.create(title=None)
 
         with self.assertRaises(IntegrityError):
-            model.objects.create(title='')
+            model.objects.create(title="")
 
         with self.assertRaises(IntegrityError):
-            model.objects.create(title='         ')
+            model.objects.create(title="         ")
 
     def test_required_some(self):
-        """Tests whether passing an array to required,
-        properly validates whether the specified languages
-        are marked as required."""
+        """Tests whether passing an array to required, properly validates
+        whether the specified languages are marked as required."""
 
-        model = get_fake_model(dict(
-            title=LocalizedField(required=['nl', 'ro'])
-        ))
+        model = get_fake_model(
+            dict(title=LocalizedField(required=["nl", "ro"]))
+        )
 
         with self.assertRaises(IntegrityError):
-            model.objects.create(title=dict(ro='romanian', nl='dutch'))
+            model.objects.create(title=dict(ro="romanian", nl="dutch"))
 
         with self.assertRaises(IntegrityError):
-            model.objects.create(title=dict(nl='dutch'))
+            model.objects.create(title=dict(nl="dutch"))
 
         with self.assertRaises(IntegrityError):
-            model.objects.create(title=dict(random='random'))
+            model.objects.create(title=dict(random="random"))
 
         with self.assertRaises(IntegrityError):
             model.objects.create(title=dict())
@@ -269,7 +261,7 @@ class LocalizedFieldTestCase(TestCase):
             model.objects.create(title=None)
 
         with self.assertRaises(IntegrityError):
-            model.objects.create(title='')
+            model.objects.create(title="")
 
         with self.assertRaises(IntegrityError):
-            model.objects.create(title='         ')
+            model.objects.create(title="         ")

tests/test_file_field.py

@@ -1,21 +1,21 @@
+import json
 import os
+import pickle
 import shutil
 import tempfile as sys_tempfile
-import pickle
-import json
 
 from django import forms
-from django.test import TestCase, override_settings
-from django.core.files.base import File, ContentFile
 from django.core.files import temp as tempfile
+from django.core.files.base import ContentFile, File
+from django.test import TestCase, override_settings
+
 from localized_fields.fields import LocalizedFileField
-from localized_fields.value import LocalizedValue
 from localized_fields.fields.file_field import LocalizedFieldFile
 from localized_fields.forms import LocalizedFileFieldForm
-from localized_fields.value import LocalizedFileValue
+from localized_fields.value import LocalizedFileValue, LocalizedValue
 from localized_fields.widgets import LocalizedFileWidget
-from .fake_model import get_fake_model
 
+from .fake_model import get_fake_model
 
 MEDIA_ROOT = sys_tempfile.mkdtemp()
 
@@ -30,11 +30,7 @@ class LocalizedFileFieldTestCase(TestCase):
 
         super().setUpClass()
 
-        cls.FileFieldModel = get_fake_model(
-            {
-                'file': LocalizedFileField(),
-            }
-        )
+        cls.FileFieldModel = get_fake_model({"file": LocalizedFileField()})
         if not os.path.isdir(MEDIA_ROOT):
             os.makedirs(MEDIA_ROOT)
 
@@ -45,48 +41,49 @@ class LocalizedFileFieldTestCase(TestCase):
 
     @classmethod
     def test_assign(cls):
-        """Tests whether the :see:LocalizedFileValueDescriptor works properly"""
+        """Tests whether the :see:LocalizedFileValueDescriptor works
+        properly."""
 
         temp_file = tempfile.NamedTemporaryFile(dir=MEDIA_ROOT)
         instance = cls.FileFieldModel()
-        instance.file = {'en': temp_file.name}
+        instance.file = {"en": temp_file.name}
         assert isinstance(instance.file.en, LocalizedFieldFile)
         assert instance.file.en.name == temp_file.name
 
         field_dump = pickle.dumps(instance.file)
         instance = cls.FileFieldModel()
         instance.file = pickle.loads(field_dump)
-        assert instance.file.en.field == instance._meta.get_field('file')
+        assert instance.file.en.field == instance._meta.get_field("file")
         assert instance.file.en.instance == instance
         assert isinstance(instance.file.en, LocalizedFieldFile)
 
         instance = cls.FileFieldModel()
-        instance.file = {'en': ContentFile("test", "testfilename")}
+        instance.file = {"en": ContentFile("test", "testfilename")}
         assert isinstance(instance.file.en, LocalizedFieldFile)
         assert instance.file.en.name == "testfilename"
 
         another_instance = cls.FileFieldModel()
-        another_instance.file = {'ro': instance.file.en}
+        another_instance.file = {"ro": instance.file.en}
         assert another_instance == another_instance.file.ro.instance
-        assert another_instance.file.ro.lang == 'ro'
+        assert another_instance.file.ro.lang == "ro"
 
     @classmethod
     def test_save_form_data(cls):
-        """Tests whether the :see:save_form_data function correctly set
-        a valid value."""
+        """Tests whether the :see:save_form_data function correctly set a valid
+        value."""
 
         instance = cls.FileFieldModel()
-        data = LocalizedFileValue({'en': False})
-        instance._meta.get_field('file').save_form_data(instance, data)
-        assert instance.file.en == ''
+        data = LocalizedFileValue({"en": False})
+        instance._meta.get_field("file").save_form_data(instance, data)
+        assert instance.file.en == ""
 
     @classmethod
     def test_pre_save(cls):
         """Tests whether the :see:pre_save function works properly."""
 
         instance = cls.FileFieldModel()
-        instance.file = {'en': ContentFile("test", "testfilename")}
-        instance._meta.get_field('file').pre_save(instance, False)
+        instance.file = {"en": ContentFile("test", "testfilename")}
+        instance._meta.get_field("file").pre_save(instance, False)
         assert instance.file.en._committed is True
 
     @classmethod
@@ -99,8 +96,8 @@ class LocalizedFileFieldTestCase(TestCase):
         # Calling delete on an unset FileField should not call the file deletion
         # process, but fail silently
         instance.file.en.delete()
-        instance.file.en.save('testfilename', temp_file)
-        assert instance.file.en.name == 'testfilename'
+        instance.file.en.save("testfilename", temp_file)
+        assert instance.file.en.name == "testfilename"
         instance.file.en.delete()
         assert instance.file.en.name is None
 
@@ -110,27 +107,29 @@ class LocalizedFileFieldTestCase(TestCase):
         works correctly."""
 
         instance = cls.FileFieldModel()
-        field = instance._meta.get_field('file')
-        field.upload_to = '{lang}/'
-        filename = field.generate_filename(instance, 'test', 'en')
-        assert filename == 'en/test'
-        field.upload_to = lambda instance, filename, lang: \
-            '%s_%s' % (lang, filename)
-        filename = field.generate_filename(instance, 'test', 'en')
-        assert filename == 'en_test'
+        field = instance._meta.get_field("file")
+        field.upload_to = "{lang}/"
+        filename = field.generate_filename(instance, "test", "en")
+        assert filename == "en/test"
+        field.upload_to = lambda instance, filename, lang: "%s_%s" % (
+            lang,
+            filename,
+        )
+        filename = field.generate_filename(instance, "test", "en")
+        assert filename == "en_test"
 
     @classmethod
-    @override_settings(LANGUAGES=(('en', 'English'),))
+    @override_settings(LANGUAGES=(("en", "English"),))
     def test_value_to_string(cls):
-        """Tests whether the :see:LocalizedFileField
-        class's :see:value_to_string function works properly."""
+        """Tests whether the :see:LocalizedFileField class's
+        :see:value_to_string function works properly."""
 
         temp_file = File(tempfile.NamedTemporaryFile())
         instance = cls.FileFieldModel()
-        field = cls.FileFieldModel._meta.get_field('file')
-        field.upload_to = ''
-        instance.file.en.save('testfilename', temp_file)
-        expected_value_to_string = json.dumps({'en': 'testfilename'})
+        field = cls.FileFieldModel._meta.get_field("file")
+        field.upload_to = ""
+        instance.file.en.save("testfilename", temp_file)
+        expected_value_to_string = json.dumps({"en": "testfilename"})
         assert field.value_to_string(instance) == expected_value_to_string
 
     @staticmethod
@@ -138,15 +137,15 @@ class LocalizedFileFieldTestCase(TestCase):
         """Tests whether the :see:get_prep_value function returns correctly
         value."""
 
-        value = LocalizedValue({'en': None})
+        value = LocalizedValue({"en": None})
         assert LocalizedFileField().get_prep_value(None) is None
         assert isinstance(LocalizedFileField().get_prep_value(value), dict)
-        assert LocalizedFileField().get_prep_value(value)['en'] == ''
+        assert LocalizedFileField().get_prep_value(value)["en"] == ""
 
     @staticmethod
     def test_formfield():
-        """Tests whether the :see:formfield function correctly returns
-        a valid form."""
+        """Tests whether the :see:formfield function correctly returns a valid
+        form."""
 
         form_field = LocalizedFileField().formfield()
         assert isinstance(form_field, LocalizedFileFieldForm)
@@ -155,11 +154,13 @@ class LocalizedFileFieldTestCase(TestCase):
 
     @staticmethod
     def test_deconstruct():
-        """Tests whether the :see:LocalizedFileField
-        class's :see:deconstruct function works properly."""
+        """Tests whether the :see:LocalizedFileField class's :see:deconstruct
+        function works properly."""
 
         name, path, args, kwargs = LocalizedFileField().deconstruct()
-        assert 'upload_to' in kwargs
-        assert 'storage' not in kwargs
-        name, path, args, kwargs = LocalizedFileField(storage='test').deconstruct()
-        assert 'storage' in kwargs
+        assert "upload_to" in kwargs
+        assert "storage" not in kwargs
+        name, path, args, kwargs = LocalizedFileField(
+            storage="test"
+        ).deconstruct()
+        assert "storage" in kwargs

tests/test_file_field_form.py

@@ -16,7 +16,7 @@ class LocalizedFileFieldFormTestCase(TestCase):
         with self.assertRaises(ValidationError):
             formfield.clean([])
         with self.assertRaises(ValidationError):
-            formfield.clean([], {'en': None})
+            formfield.clean([], {"en": None})
         with self.assertRaises(ValidationError):
             formfield.clean("badvalue")
         with self.assertRaises(ValidationError):
@@ -24,17 +24,17 @@ class LocalizedFileFieldFormTestCase(TestCase):
             formfield.clean(value)
 
         formfield = LocalizedFileFieldForm(required=False)
-        formfield.clean([''] * len(settings.LANGUAGES))
-        formfield.clean(['', ''], ['', ''])
+        formfield.clean([""] * len(settings.LANGUAGES))
+        formfield.clean(["", ""], ["", ""])
 
     def test_bound_data(self):
         """Tests whether the :see:bound_data function is returns correctly
-        value"""
+        value."""
 
         formfield = LocalizedFileFieldForm()
-        assert formfield.bound_data([''], None) == ['']
+        assert formfield.bound_data([""], None) == [""]
 
-        initial = dict([(lang, '') for lang, _ in settings.LANGUAGES])
+        initial = dict([(lang, "") for lang, _ in settings.LANGUAGES])
         value = [None] * len(settings.LANGUAGES)
-        expected_value = [''] * len(settings.LANGUAGES)
+        expected_value = [""] * len(settings.LANGUAGES)
         assert formfield.bound_data(value, initial) == expected_value

tests/test_file_widget.py

@@ -9,16 +9,18 @@ class LocalizedFileWidgetTestCase(TestCase):
 
     @staticmethod
     def test_get_context():
-        """Tests whether the :see:get_context correctly
-        handles 'required' attribute, separately for each subwidget."""
+        """Tests whether the :see:get_context correctly handles 'required'
+        attribute, separately for each subwidget."""
 
         widget = LocalizedFileWidget()
         widget.widgets[0].is_required = True
         widget.widgets[1].is_required = True
         widget.widgets[2].is_required = False
-        context = widget.get_context(name='test',
-                                     value=LocalizedFileValue(dict(en='test')),
-                                     attrs=dict(required=True))
-        assert 'required' not in context['widget']['subwidgets'][0]['attrs']
-        assert context['widget']['subwidgets'][1]['attrs']['required']
-        assert 'required' not in context['widget']['subwidgets'][2]['attrs']
+        context = widget.get_context(
+            name="test",
+            value=LocalizedFileValue(dict(en="test")),
+            attrs=dict(required=True),
+        )
+        assert "required" not in context["widget"]["subwidgets"][0]["attrs"]
+        assert context["widget"]["subwidgets"][1]["attrs"]["required"]
+        assert "required" not in context["widget"]["subwidgets"][2]["attrs"]

tests/test_float_field.py

@@ -0,0 +1,172 @@
+from django.conf import settings
+from django.db import connection
+from django.db.utils import IntegrityError
+from django.test import TestCase
+from django.utils import translation
+
+from localized_fields.fields import LocalizedFloatField
+
+from .fake_model import get_fake_model
+
+
+class LocalizedFloatFieldTestCase(TestCase):
+    """Tests whether the :see:LocalizedFloatField and :see:LocalizedFloatValue
+    works properly."""
+
+    TestModel = None
+
+    @classmethod
+    def setUpClass(cls):
+        super().setUpClass()
+
+        cls.TestModel = get_fake_model({"score": LocalizedFloatField()})
+
+    def test_basic(self):
+        """Tests the basics of storing float values."""
+
+        obj = self.TestModel()
+        for index, (lang_code, _) in enumerate(settings.LANGUAGES):
+            obj.score.set(lang_code, index + 1.0)
+        obj.save()
+
+        obj = self.TestModel.objects.all().first()
+        for index, (lang_code, _) in enumerate(settings.LANGUAGES):
+            assert obj.score.get(lang_code) == index + 1.0
+
+    def test_primary_language_required(self):
+        """Tests whether the primary language is required by default and all
+        other languages are optiona."""
+
+        # not filling in anything should raise IntegrityError,
+        # the primary language is required
+        with self.assertRaises(IntegrityError):
+            obj = self.TestModel()
+            obj.save()
+
+        # when filling all other languages besides the primary language
+        # should still raise an error because the primary is always required
+        with self.assertRaises(IntegrityError):
+            obj = self.TestModel()
+            for lang_code, _ in settings.LANGUAGES:
+                if lang_code == settings.LANGUAGE_CODE:
+                    continue
+                obj.score.set(lang_code, 23.0)
+            obj.save()
+
+    def test_default_value_none(self):
+        """Tests whether the default value for optional languages is
+        NoneType."""
+
+        obj = self.TestModel()
+        obj.score.set(settings.LANGUAGE_CODE, 1234.0)
+        obj.save()
+
+        for lang_code, _ in settings.LANGUAGES:
+            if lang_code == settings.LANGUAGE_CODE:
+                continue
+
+            assert obj.score.get(lang_code) is None
+
+    def test_translate(self):
+        """Tests whether casting the value to an float results in the value
+        being returned in the currently active language as an float."""
+
+        obj = self.TestModel()
+        for index, (lang_code, _) in enumerate(settings.LANGUAGES):
+            obj.score.set(lang_code, index + 1.0)
+        obj.save()
+
+        obj.refresh_from_db()
+        for index, (lang_code, _) in enumerate(settings.LANGUAGES):
+            with translation.override(lang_code):
+                assert float(obj.score) == index + 1.0
+                assert obj.score.translate() == index + 1.0
+
+    def test_translate_primary_fallback(self):
+        """Tests whether casting the value to an float results in the value
+        begin returned in the active language and falls back to the primary
+        language if there is no value in that language."""
+
+        obj = self.TestModel()
+        obj.score.set(settings.LANGUAGE_CODE, 25.0)
+
+        secondary_language = settings.LANGUAGES[-1][0]
+        assert obj.score.get(secondary_language) is None
+
+        with translation.override(secondary_language):
+            assert obj.score.translate() == 25.0
+            assert float(obj.score) == 25.0
+
+    def test_get_default_value(self):
+        """Tests whether getting the value in a specific language properly
+        returns the specified default in case it is not available."""
+
+        obj = self.TestModel()
+        obj.score.set(settings.LANGUAGE_CODE, 25.0)
+
+        secondary_language = settings.LANGUAGES[-1][0]
+        assert obj.score.get(secondary_language) is None
+        assert obj.score.get(secondary_language, 1337.0) == 1337.0
+
+    def test_completely_optional(self):
+        """Tests whether having all languages optional works properly."""
+
+        model = get_fake_model(
+            {"score": LocalizedFloatField(null=True, required=[], blank=True)}
+        )
+
+        obj = model()
+        obj.save()
+
+        for lang_code, _ in settings.LANGUAGES:
+            assert getattr(obj.score, lang_code) is None
+
+    def test_store_string(self):
+        """Tests whether the field properly raises an error when trying to
+        store a non-float."""
+
+        for lang_code, _ in settings.LANGUAGES:
+            obj = self.TestModel()
+            with self.assertRaises(IntegrityError):
+                obj.score.set(lang_code, "haha")
+                obj.save()
+
+    def test_none_if_illegal_value_stored(self):
+        """Tests whether None is returned for a language if the value stored in
+        the database is not an float."""
+
+        obj = self.TestModel()
+        obj.score.set(settings.LANGUAGE_CODE, 25.0)
+        obj.save()
+
+        with connection.cursor() as cursor:
+            table_name = self.TestModel._meta.db_table
+            cursor.execute("update %s set score = 'en=>haha'" % table_name)
+
+        obj.refresh_from_db()
+        assert obj.score.get(settings.LANGUAGE_CODE) is None
+
+    def test_default_value(self):
+        """Tests whether a default is properly set when specified."""
+
+        model = get_fake_model(
+            {
+                "score": LocalizedFloatField(
+                    default={settings.LANGUAGE_CODE: 75.0}
+                )
+            }
+        )
+
+        obj = model.objects.create()
+        assert obj.score.get(settings.LANGUAGE_CODE) == 75.0
+
+        obj = model()
+        for lang_code, _ in settings.LANGUAGES:
+            obj.score.set(lang_code, None)
+        obj.save()
+
+        for lang_code, _ in settings.LANGUAGES:
+            if lang_code == settings.LANGUAGE_CODE:
+                assert obj.score.get(lang_code) == 75.0
+            else:
+                assert obj.score.get(lang_code) is None

tests/test_form.py

@@ -9,8 +9,8 @@ class LocalizedFieldFormTestCase(TestCase):
 
     @staticmethod
     def test_init():
-        """Tests whether the constructor correctly
-        creates a field for every language."""
+        """Tests whether the constructor correctly creates a field for every
+        language."""
         # case required for specific language
         form = LocalizedFieldForm(required=[settings.LANGUAGE_CODE])
 
@@ -42,8 +42,7 @@ class LocalizedFieldFormTestCase(TestCase):
 
     @staticmethod
     def test_compress():
-        """Tests whether the :see:compress function
-        is working properly."""
+        """Tests whether the :see:compress function is working properly."""
 
         input_value = [lang_name for _, lang_name in settings.LANGUAGES]
         output_value = LocalizedFieldForm().compress(input_value)

tests/test_integer_field.py

@@ -1,17 +1,20 @@
-from django.test import TestCase
-from django.db.utils import IntegrityError
+import django
+
 from django.conf import settings
 from django.db import connection
+from django.db.utils import IntegrityError
+from django.test import TestCase
 from django.utils import translation
 
 from localized_fields.fields import LocalizedIntegerField
+from localized_fields.value import LocalizedIntegerValue
 
 from .fake_model import get_fake_model
 
 
 class LocalizedIntegerFieldTestCase(TestCase):
-    """Tests whether the :see:LocalizedIntegerField
-    and :see:LocalizedIntegerValue works properly."""
+    """Tests whether the :see:LocalizedIntegerField and
+    :see:LocalizedIntegerValue works properly."""
 
     TestModel = None
 
@@ -19,9 +22,7 @@ class LocalizedIntegerFieldTestCase(TestCase):
     def setUpClass(cls):
         super().setUpClass()
 
-        cls.TestModel = get_fake_model({
-            'score': LocalizedIntegerField()
-        })
+        cls.TestModel = get_fake_model({"score": LocalizedIntegerField()})
 
     def test_basic(self):
         """Tests the basics of storing integer values."""
@@ -36,8 +37,8 @@ class LocalizedIntegerFieldTestCase(TestCase):
             assert obj.score.get(lang_code) == index + 1
 
     def test_primary_language_required(self):
-        """Tests whether the primary language is required by
-        default and all other languages are optiona."""
+        """Tests whether the primary language is required by default and all
+        other languages are optiona."""
 
         # not filling in anything should raise IntegrityError,
         # the primary language is required
@@ -56,8 +57,8 @@ class LocalizedIntegerFieldTestCase(TestCase):
             obj.save()
 
     def test_default_value_none(self):
-        """Tests whether the default value for optional languages
-        is NoneType."""
+        """Tests whether the default value for optional languages is
+        NoneType."""
 
         obj = self.TestModel()
         obj.score.set(settings.LANGUAGE_CODE, 1234)
@@ -70,9 +71,8 @@ class LocalizedIntegerFieldTestCase(TestCase):
             assert obj.score.get(lang_code) is None
 
     def test_translate(self):
-        """Tests whether casting the value to an integer
-        results in the value being returned in the currently
-        active language as an integer."""
+        """Tests whether casting the value to an integer results in the value
+        being returned in the currently active language as an integer."""
 
         obj = self.TestModel()
         for index, (lang_code, _) in enumerate(settings.LANGUAGES):
@@ -86,10 +86,9 @@ class LocalizedIntegerFieldTestCase(TestCase):
                 assert obj.score.translate() == index + 1
 
     def test_translate_primary_fallback(self):
-        """Tests whether casting the value to an integer
-        results in the value begin returned in the active
-        language and falls back to the primary language
-        if there is no value in that language."""
+        """Tests whether casting the value to an integer results in the value
+        begin returned in the active language and falls back to the primary
+        language if there is no value in that language."""
 
         obj = self.TestModel()
         obj.score.set(settings.LANGUAGE_CODE, 25)
@@ -102,9 +101,8 @@ class LocalizedIntegerFieldTestCase(TestCase):
             assert int(obj.score) == 25
 
     def test_get_default_value(self):
-        """Tests whether getting the value in a specific
-        language properly returns the specified default
-        in case it is not available."""
+        """Tests whether getting the value in a specific language properly
+        returns the specified default in case it is not available."""
 
         obj = self.TestModel()
         obj.score.set(settings.LANGUAGE_CODE, 25)
@@ -114,12 +112,11 @@ class LocalizedIntegerFieldTestCase(TestCase):
         assert obj.score.get(secondary_language, 1337) == 1337
 
     def test_completely_optional(self):
-        """Tests whether having all languages optional
-        works properly."""
+        """Tests whether having all languages optional works properly."""
 
-        model = get_fake_model({
-            'score': LocalizedIntegerField(null=True, required=[], blank=True)
-        })
+        model = get_fake_model(
+            {"score": LocalizedIntegerField(null=True, required=[], blank=True)}
+        )
 
         obj = model()
         obj.save()
@@ -128,19 +125,18 @@ class LocalizedIntegerFieldTestCase(TestCase):
             assert getattr(obj.score, lang_code) is None
 
     def test_store_string(self):
-        """Tests whether the field properly raises
-        an error when trying to store a non-integer."""
+        """Tests whether the field properly raises an error when trying to
+        store a non-integer."""
 
         for lang_code, _ in settings.LANGUAGES:
             obj = self.TestModel()
             with self.assertRaises(IntegrityError):
-                obj.score.set(lang_code, 'haha')
+                obj.score.set(lang_code, "haha")
                 obj.save()
 
     def test_none_if_illegal_value_stored(self):
-        """Tests whether None is returned for a language
-        if the value stored in the database is not an
-        integer."""
+        """Tests whether None is returned for a language if the value stored in
+        the database is not an integer."""
 
         obj = self.TestModel()
         obj.score.set(settings.LANGUAGE_CODE, 25)
@@ -154,12 +150,15 @@ class LocalizedIntegerFieldTestCase(TestCase):
         assert obj.score.get(settings.LANGUAGE_CODE) is None
 
     def test_default_value(self):
-        """Tests whether a default is properly set
-        when specified."""
+        """Tests whether a default is properly set when specified."""
 
-        model = get_fake_model({
-            'score': LocalizedIntegerField(default={settings.LANGUAGE_CODE: 75})
-        })
+        model = get_fake_model(
+            {
+                "score": LocalizedIntegerField(
+                    default={settings.LANGUAGE_CODE: 75}
+                )
+            }
+        )
 
         obj = model.objects.create()
         assert obj.score.get(settings.LANGUAGE_CODE) == 75
@@ -174,3 +173,67 @@ class LocalizedIntegerFieldTestCase(TestCase):
                 assert obj.score.get(lang_code) == 75
             else:
                 assert obj.score.get(lang_code) is None
+
+    def test_default_value_update(self):
+        """Tests whether a default is properly set when specified during
+        updates."""
+
+        model = get_fake_model(
+            {
+                "score": LocalizedIntegerField(
+                    default={settings.LANGUAGE_CODE: 75}, null=True
+                )
+            }
+        )
+
+        obj = model.objects.create(
+            score=LocalizedIntegerValue({settings.LANGUAGE_CODE: 35})
+        )
+        assert obj.score.get(settings.LANGUAGE_CODE) == 35
+
+        model.objects.update(
+            score=LocalizedIntegerValue({settings.LANGUAGE_CODE: None})
+        )
+        obj.refresh_from_db()
+        assert obj.score.get(settings.LANGUAGE_CODE) == 75
+
+    def test_callable_default_value(self):
+        output = {"en": 5}
+
+        def func():
+            return output
+
+        model = get_fake_model({"test": LocalizedIntegerField(default=func)})
+        obj = model.objects.create()
+
+        assert obj.test["en"] == output["en"]
+
+    def test_order_by(self):
+        """Tests whether ordering by a :see:LocalizedIntegerField key works
+        expected."""
+
+        # using key transforms (score__en) in order_by(..) is only
+        # supported since Django 2.1
+        # https://github.com/django/django/commit/2162f0983de0dfe2178531638ce7ea56f54dd4e7#diff-0edd853580d56db07e4020728d59e193
+
+        if django.VERSION < (2, 1):
+            return
+
+        model = get_fake_model(
+            {
+                "score": LocalizedIntegerField(
+                    default={settings.LANGUAGE_CODE: 1337}, null=True
+                )
+            }
+        )
+
+        model.objects.create(score=dict(en=982))
+        model.objects.create(score=dict(en=382))
+        model.objects.create(score=dict(en=1331))
+
+        res = list(
+            model.objects.values_list("score__en", flat=True).order_by(
+                "-score__en"
+            )
+        )
+        assert res == [1331, 982, 382]

tests/test_isnull.py

@@ -0,0 +1,51 @@
+import django
+import pytest
+
+from django.test import TestCase
+
+from localized_fields.fields import LocalizedField
+from localized_fields.value import LocalizedValue
+
+from .fake_model import get_fake_model
+
+
+class LocalizedIsNullLookupsTestCase(TestCase):
+    """Tests whether ref lookups properly work with."""
+
+    TestModel1 = None
+
+    @classmethod
+    def setUpClass(cls):
+        """Creates the test model in the database."""
+        super(LocalizedIsNullLookupsTestCase, cls).setUpClass()
+        cls.TestModel = get_fake_model(
+            {"text": LocalizedField(null=True, required=[])}
+        )
+        cls.TestModel.objects.create(
+            text=LocalizedValue(dict(en="text_en", ro="text_ro", nl="text_nl"))
+        )
+        cls.TestModel.objects.create(
+            text=None,
+        )
+
+    def test_isnull_lookup_valid_values(self):
+        """Test whether isnull properly works with valid values."""
+        assert self.TestModel.objects.filter(text__isnull=True).exists()
+        assert self.TestModel.objects.filter(text__isnull=False).exists()
+
+    def test_isnull_lookup_null(self):
+        """Test whether isnull crashes with None as value."""
+
+        with pytest.raises(ValueError):
+            assert self.TestModel.objects.filter(text__isnull=None).exists()
+
+    def test_isnull_lookup_string(self):
+        """Test whether isnull properly works with string values on the
+        corresponding Django version."""
+        if django.VERSION < (4, 0):
+            assert self.TestModel.objects.filter(text__isnull="True").exists()
+        else:
+            with pytest.raises(ValueError):
+                assert self.TestModel.objects.filter(
+                    text__isnull="True"
+                ).exists()

tests/test_lookups.py

@@ -3,6 +3,7 @@ from django.conf import settings
 from django.test import TestCase, override_settings
 from django.utils import translation
 
+from localized_fields.expressions import LocalizedRef
 from localized_fields.fields import LocalizedField
 from localized_fields.value import LocalizedValue
 
@@ -12,6 +13,7 @@ from .fake_model import get_fake_model
 @override_settings(LOCALIZED_FIELDS_EXPERIMENTAL=True)
 class LocalizedLookupsTestCase(TestCase):
     """Tests whether localized lookups properly work with."""
+
     TestModel1 = None
 
     @classmethod
@@ -21,31 +23,109 @@ class LocalizedLookupsTestCase(TestCase):
         super(LocalizedLookupsTestCase, cls).setUpClass()
 
         # reload app as setting has changed
-        config = apps.get_app_config('localized_fields')
+        config = apps.get_app_config("localized_fields")
         config.ready()
 
-        cls.TestModel = get_fake_model(
-            {
-                'text': LocalizedField(),
-            }
-        )
+        cls.TestModel = get_fake_model({"text": LocalizedField()})
 
     def test_localized_lookup(self):
         """Tests whether localized lookup properly works."""
 
         self.TestModel.objects.create(
-            text=LocalizedValue(dict(en='text_en', ro='text_ro', nl='text_nl')),
+            text=LocalizedValue(dict(en="text_en", ro="text_ro", nl="text_nl"))
         )
 
         # assert that it properly lookups the currently active language
         for lang_code, _ in settings.LANGUAGES:
             translation.activate(lang_code)
-            assert self.TestModel.objects.filter(text='text_' + lang_code).exists()
+            assert self.TestModel.objects.filter(
+                text="text_" + lang_code
+            ).exists()
 
         # ensure that the default language is used in case no
         # language is active at all
         translation.deactivate_all()
-        assert self.TestModel.objects.filter(text='text_en').exists()
+        assert self.TestModel.objects.filter(text="text_en").exists()
 
         # ensure that hstore lookups still work
-        assert self.TestModel.objects.filter(text__ro='text_ro').exists()
+        assert self.TestModel.objects.filter(text__ro="text_ro").exists()
+
+    def test_localized_lookup_specific_isnull(self):
+        self.TestModel.objects.create(
+            text=LocalizedValue(dict(en="text_en", ro="text_ro", nl=None))
+        )
+
+        translation.activate("nl")
+        assert (
+            self.TestModel.objects.annotate(text_localized=LocalizedRef("text"))
+            .filter(text_localized__isnull=True)
+            .exists()
+        )
+
+
+class LocalizedRefLookupsTestCase(TestCase):
+    """Tests whether ref lookups properly work with."""
+
+    TestModel1 = None
+
+    @classmethod
+    def setUpClass(cls):
+        """Creates the test model in the database."""
+        super(LocalizedRefLookupsTestCase, cls).setUpClass()
+        cls.TestModel = get_fake_model({"text": LocalizedField()})
+        cls.TestModel.objects.create(
+            text=LocalizedValue(dict(en="text_en", ro="text_ro", nl="text_nl"))
+        )
+
+    def test_active_ref_lookup(self):
+        """Tests whether active_ref lookup properly works."""
+
+        # assert that it properly lookups the currently active language
+        for lang_code, _ in settings.LANGUAGES:
+            translation.activate(lang_code)
+            assert self.TestModel.objects.filter(
+                text__active_ref=f"text_{lang_code}"
+            ).exists()
+
+        # ensure that the default language is used in case no
+        # language is active at all
+        translation.deactivate_all()
+        assert self.TestModel.objects.filter(
+            text__active_ref="text_en"
+        ).exists()
+
+    def test_translated_ref_lookup(self):
+        """Tests whether translated_ref lookup properly works."""
+
+        # assert that it properly lookups the currently active language
+        for lang_code, _ in settings.LANGUAGES:
+            translation.activate(lang_code)
+            assert self.TestModel.objects.filter(
+                text__translated_ref=f"text_{lang_code}"
+            ).exists()
+
+        # ensure that the default language is used in case no
+        # language is active at all
+        translation.deactivate_all()
+        assert self.TestModel.objects.filter(
+            text__translated_ref="text_en"
+        ).exists()
+
+        fallbacks = {"cs": ["ru", "ro"], "pl": ["nl", "ro"]}
+
+        with override_settings(LOCALIZED_FIELDS_FALLBACKS=fallbacks):
+            with translation.override("cs"):
+                assert self.TestModel.objects.filter(
+                    text__translated_ref="text_ro"
+                ).exists()
+
+            with translation.override("pl"):
+                assert self.TestModel.objects.filter(
+                    text__translated_ref="text_nl"
+                ).exists()
+
+            # ensure that the default language is used in case no fallback is set
+            with translation.override("ru"):
+                assert self.TestModel.objects.filter(
+                    text__translated_ref="text_en"
+                ).exists()

tests/test_model.py

@@ -17,17 +17,12 @@ class LocalizedModelTestCase(TestCase):
 
         super(LocalizedModelTestCase, cls).setUpClass()
 
-        cls.TestModel = get_fake_model(
-            {
-                'title': LocalizedField()
-            }
-        )
+        cls.TestModel = get_fake_model({"title": LocalizedField()})
 
     @classmethod
     def test_defaults(cls):
-        """Tests whether all :see:LocalizedField
-        fields are assigned an empty :see:LocalizedValue
-        instance when the model is instanitiated."""
+        """Tests whether all :see:LocalizedField fields are assigned an empty
+        :see:LocalizedValue instance when the model is instanitiated."""
 
         obj = cls.TestModel()
 
@@ -35,19 +30,18 @@ class LocalizedModelTestCase(TestCase):
 
     @classmethod
     def test_model_init_kwargs(cls):
-        """Tests whether all :see:LocalizedField
-        fields are assigned an empty :see:LocalizedValue
-        instance when the model is instanitiated."""
+        """Tests whether all :see:LocalizedField fields are assigned an empty
+        :see:LocalizedValue instance when the model is instanitiated."""
         data = {
-            'title': {
-                'en': 'english_title',
-                'ro': 'romanian_title',
-                'nl': 'dutch_title'
+            "title": {
+                "en": "english_title",
+                "ro": "romanian_title",
+                "nl": "dutch_title",
             }
         }
         obj = cls.TestModel(**data)
 
         assert isinstance(obj.title, LocalizedValue)
-        assert obj.title.en == 'english_title'
-        assert obj.title.ro == 'romanian_title'
-        assert obj.title.nl == 'dutch_title'
+        assert obj.title.en == "english_title"
+        assert obj.title.ro == "romanian_title"
+        assert obj.title.nl == "dutch_title"

tests/test_query_set.py

@@ -16,30 +16,24 @@ class LocalizedQuerySetTestCase(TestCase):
 
         super(LocalizedQuerySetTestCase, cls).setUpClass()
 
-        cls.Model = get_fake_model(
-            {
-                'title': LocalizedField(),
-            }
-        )
+        cls.Model = get_fake_model({"title": LocalizedField()})
 
     @classmethod
     def test_assign_raw_dict(cls):
         inst = cls.Model()
-        inst.title = dict(en='Bread', ro='Paine')
+        inst.title = dict(en="Bread", ro="Paine")
         inst.save()
 
         inst = cls.Model.objects.get(pk=inst.pk)
-        assert inst.title.en == 'Bread'
-        assert inst.title.ro == 'Paine'
+        assert inst.title.en == "Bread"
+        assert inst.title.ro == "Paine"
 
     @classmethod
     def test_assign_raw_dict_update(cls):
-        inst = cls.Model.objects.create(
-            title=dict(en='Bread', ro='Paine'))
+        inst = cls.Model.objects.create(title=dict(en="Bread", ro="Paine"))
 
-        cls.Model.objects.update(
-            title=dict(en='Beer', ro='Bere'))
+        cls.Model.objects.update(title=dict(en="Beer", ro="Bere"))
 
         inst = cls.Model.objects.get(pk=inst.pk)
-        assert inst.title.en == 'Beer'
-        assert inst.title.ro == 'Bere'
+        assert inst.title.en == "Beer"
+        assert inst.title.ro == "Bere"

tests/test_slug_fields.py

@@ -1,16 +1,15 @@
 import copy
 
+import pytest
+
 from django import forms
-from django.db import models
 from django.conf import settings
-from django.test import TestCase
+from django.db import models
 from django.db.utils import IntegrityError
+from django.test import TestCase
 from django.utils.text import slugify
 
-from localized_fields.fields import (
-    LocalizedField,
-    LocalizedUniqueSlugField
-)
+from localized_fields.fields import LocalizedField, LocalizedUniqueSlugField
 
 from .fake_model import get_fake_model
 
@@ -29,23 +28,25 @@ class LocalizedSlugFieldTestCase(TestCase):
 
         cls.Model = get_fake_model(
             {
-                'title': LocalizedField(),
-                'name': models.CharField(max_length=255),
-                'slug': LocalizedUniqueSlugField(populate_from='title')
+                "title": LocalizedField(),
+                "name": models.CharField(max_length=255),
+                "slug": LocalizedUniqueSlugField(populate_from="title"),
             }
         )
 
     @staticmethod
     def test_unique_slug_with_time():
-        """Tests whether the primary key is included in
-        the slug when the 'use_pk' option is enabled."""
+        """Tests whether the primary key is included in the slug when the
+        'use_pk' option is enabled."""
 
-        title = 'myuniquetitle'
+        title = "myuniquetitle"
 
         PkModel = get_fake_model(
             {
-                'title': LocalizedField(),
-                'slug': LocalizedUniqueSlugField(populate_from='title', include_time=True)
+                "title": LocalizedField(),
+                "slug": LocalizedUniqueSlugField(
+                    populate_from="title", include_time=True
+                ),
             }
         )
 
@@ -53,7 +54,7 @@ class LocalizedSlugFieldTestCase(TestCase):
         obj.title.en = title
         obj.save()
 
-        assert obj.slug.en.startswith('%s-' % title)
+        assert obj.slug.en.startswith("%s-" % title)
 
     @classmethod
     def test_uniue_slug_no_change(cls):
@@ -61,12 +62,14 @@ class LocalizedSlugFieldTestCase(TestCase):
 
         NoChangeSlugModel = get_fake_model(
             {
-                'title': LocalizedField(),
-                'slug': LocalizedUniqueSlugField(populate_from='title', include_time=True)
+                "title": LocalizedField(),
+                "slug": LocalizedUniqueSlugField(
+                    populate_from="title", include_time=True
+                ),
             }
         )
 
-        title = 'myuniquetitle'
+        title = "myuniquetitle"
 
         obj = NoChangeSlugModel()
         obj.title.en = title
@@ -75,7 +78,7 @@ class LocalizedSlugFieldTestCase(TestCase):
 
         old_slug_en = copy.deepcopy(obj.slug.en)
         old_slug_nl = copy.deepcopy(obj.slug.nl)
-        obj.title.nl += 'beer'
+        obj.title.nl += "beer"
         obj.save()
 
         assert old_slug_en == obj.slug.en
@@ -83,18 +86,20 @@ class LocalizedSlugFieldTestCase(TestCase):
 
     @classmethod
     def test_unique_slug_update(cls):
-        obj = cls.Model.objects.create(title={settings.LANGUAGE_CODE: 'mytitle'})
-        assert obj.slug.get() == 'mytitle'
-        obj.title.set(settings.LANGUAGE_CODE, 'othertitle')
+        obj = cls.Model.objects.create(
+            title={settings.LANGUAGE_CODE: "mytitle"}
+        )
+        assert obj.slug.get() == "mytitle"
+        obj.title.set(settings.LANGUAGE_CODE, "othertitle")
         obj.save()
-        assert obj.slug.get() == 'othertitle'
+        assert obj.slug.get() == "othertitle"
 
     @classmethod
     def test_unique_slug_unique_max_retries(cls):
-        """Tests whether the unique slug implementation doesn't
-        try to find a slug forever and gives up after a while."""
+        """Tests whether the unique slug implementation doesn't try to find a
+        slug forever and gives up after a while."""
 
-        title = 'myuniquetitle'
+        title = "myuniquetitle"
 
         obj = cls.Model()
         obj.title.en = title
@@ -111,106 +116,159 @@ class LocalizedSlugFieldTestCase(TestCase):
         """Tests whether the populating feature works correctly."""
 
         obj = cls.Model()
-        obj.title.en = 'this is my title'
+        obj.title.en = "this is my title"
         obj.save()
 
-        assert obj.slug.get('en') == slugify(obj.title)
+        assert obj.slug.get("en") == slugify(obj.title)
 
     @classmethod
     def test_populate_callable(cls):
-        """Tests whether the populating feature works correctly
-        when you specify a callable."""
+        """Tests whether the populating feature works correctly when you
+        specify a callable."""
 
         def generate_slug(instance):
             return instance.title
 
-        get_fake_model({
-            'title': LocalizedField(),
-            'slug': LocalizedUniqueSlugField(populate_from=generate_slug)
-        })
+        get_fake_model(
+            {
+                "title": LocalizedField(),
+                "slug": LocalizedUniqueSlugField(populate_from=generate_slug),
+            }
+        )
 
         obj = cls.Model()
         for lang_code, lang_name in settings.LANGUAGES:
-            obj.title.set(lang_code, 'title %s' % lang_name)
+            obj.title.set(lang_code, "title %s" % lang_name)
 
         obj.save()
 
         for lang_code, lang_name in settings.LANGUAGES:
-            assert obj.slug.get(lang_code) == 'title-%s' % lang_name.lower()
+            assert obj.slug.get(lang_code) == "title-%s" % lang_name.lower()
 
     @staticmethod
     def test_populate_multiple_from_fields():
-        """Tests whether populating the slug from multiple
-        fields works correctly."""
+        """Tests whether populating the slug from multiple fields works
+        correctly."""
 
         model = get_fake_model(
             {
-                'title': LocalizedField(),
-                'name': models.CharField(max_length=255),
-                'slug': LocalizedUniqueSlugField(populate_from=('title', 'name'))
+                "title": LocalizedField(),
+                "name": models.CharField(max_length=255),
+                "slug": LocalizedUniqueSlugField(
+                    populate_from=("title", "name")
+                ),
             }
         )
 
         obj = model()
         for lang_code, lang_name in settings.LANGUAGES:
-            obj.name = 'swen'
-            obj.title.set(lang_code, 'title %s' % lang_name)
+            obj.name = "swen"
+            obj.title.set(lang_code, "title %s" % lang_name)
 
         obj.save()
 
         for lang_code, lang_name in settings.LANGUAGES:
-            assert obj.slug.get(lang_code) == 'title-%s-swen' % lang_name.lower()
+            assert (
+                obj.slug.get(lang_code) == "title-%s-swen" % lang_name.lower()
+            )
 
     @staticmethod
     def test_populate_multiple_from_fields_fk():
-        """Tests whether populating the slug from multiple
-        fields works correctly."""
+        """Tests whether populating the slug from multiple fields works
+        correctly."""
 
-        model_fk = get_fake_model(
-            {
-                'name': LocalizedField(),
-            }
-        )
+        model_fk = get_fake_model({"name": LocalizedField()})
 
         model = get_fake_model(
             {
-                'title': LocalizedField(),
-                'other': models.ForeignKey(model_fk, on_delete=models.CASCADE),
-                'slug': LocalizedUniqueSlugField(populate_from=('title', 'other.name'))
+                "title": LocalizedField(),
+                "other": models.ForeignKey(model_fk, on_delete=models.CASCADE),
+                "slug": LocalizedUniqueSlugField(
+                    populate_from=("title", "other.name")
+                ),
             }
         )
 
-        other = model_fk.objects.create(name={settings.LANGUAGE_CODE: 'swen'})
+        other = model_fk.objects.create(name={settings.LANGUAGE_CODE: "swen"})
 
         obj = model()
         for lang_code, lang_name in settings.LANGUAGES:
             obj.other_id = other.id
-            obj.title.set(lang_code, 'title %s' % lang_name)
+            obj.title.set(lang_code, "title %s" % lang_name)
 
         obj.save()
 
         for lang_code, lang_name in settings.LANGUAGES:
-            assert obj.slug.get(lang_code) == 'title-%s-swen' % lang_name.lower()
+            assert (
+                obj.slug.get(lang_code) == "title-%s-swen" % lang_name.lower()
+            )
 
     @classmethod
     def test_populate_multiple_languages(cls):
-        """Tests whether the populating feature correctly
-        works for all languages."""
+        """Tests whether the populating feature correctly works for all
+        languages."""
 
         obj = cls.Model()
         for lang_code, lang_name in settings.LANGUAGES:
-            obj.title.set(lang_code, 'title %s' % lang_name)
+            obj.title.set(lang_code, "title %s" % lang_name)
 
         obj.save()
 
         for lang_code, lang_name in settings.LANGUAGES:
-            assert obj.slug.get(lang_code) == 'title-%s' % lang_name.lower()
+            assert obj.slug.get(lang_code) == "title-%s" % lang_name.lower()
+
+    @classmethod
+    def test_disable(cls):
+        """Tests whether disabling auto-slugging works."""
+
+        Model = get_fake_model(
+            {
+                "title": LocalizedField(),
+                "slug": LocalizedUniqueSlugField(
+                    populate_from="title", enabled=False
+                ),
+            }
+        )
+
+        obj = Model()
+        obj.title = "test"
+
+        # should raise IntegrityError because auto-slugging
+        # is disabled and the slug field is NULL
+        with pytest.raises(IntegrityError):
+            obj.save()
+
+    @classmethod
+    def test_allows_override_when_immutable(cls):
+        """Tests whether setting a value manually works and does not get
+        overriden."""
+
+        Model = get_fake_model(
+            {
+                "title": LocalizedField(),
+                "name": models.CharField(max_length=255),
+                "slug": LocalizedUniqueSlugField(
+                    populate_from="title", immutable=True
+                ),
+            }
+        )
+
+        obj = Model()
+
+        for lang_code, lang_name in settings.LANGUAGES:
+            obj.slug.set(lang_code, "my value %s" % lang_code)
+            obj.title.set(lang_code, "my title %s" % lang_code)
+
+        obj.save()
+
+        for lang_code, lang_name in settings.LANGUAGES:
+            assert obj.slug.get(lang_code) == "my value %s" % lang_code
 
     @classmethod
     def test_unique_slug(cls):
         """Tests whether unique slugs are properly generated."""
 
-        title = 'myuniquetitle'
+        title = "myuniquetitle"
 
         obj = cls.Model()
         obj.title.en = title
@@ -221,38 +279,39 @@ class LocalizedSlugFieldTestCase(TestCase):
             another_obj.title.en = title
             another_obj.save()
 
-            assert another_obj.slug.en == '%s-%d' % (title, i)
+            assert another_obj.slug.en == "%s-%d" % (title, i)
 
     @classmethod
     def test_unique_slug_utf(cls):
-        """Tests whether generating a slug works
-        when the value consists completely out
-        of non-ASCII characters."""
+        """Tests whether generating a slug works when the value consists
+        completely out of non-ASCII characters."""
 
         obj = cls.Model()
-        obj.title.en = 'مكاتب للايجار بشارع بورسعيد'
+        obj.title.en = "مكاتب للايجار بشارع بورسعيد"
         obj.save()
 
-        assert obj.slug.en == 'مكاتب-للايجار-بشارع-بورسعيد'
+        assert obj.slug.en == "مكاتب-للايجار-بشارع-بورسعيد"
 
     @staticmethod
     def test_deconstruct():
-        """Tests whether the :see:deconstruct
-        function properly retains options
+        """Tests whether the :see:deconstruct function properly retains options
         specified in the constructor."""
 
-        field = LocalizedUniqueSlugField(populate_from='title')
+        field = LocalizedUniqueSlugField(
+            enabled=False, immutable=True, populate_from="title"
+        )
         _, _, _, kwargs = field.deconstruct()
 
-        assert 'populate_from' in kwargs
-        assert kwargs['populate_from'] == field.populate_from
+        assert not kwargs["enabled"]
+        assert kwargs["immutable"]
+        assert kwargs["populate_from"] == field.populate_from
 
     @staticmethod
     def test_formfield():
-        """Tests whether the :see:formfield method
-        returns a valid form field that is hidden."""
+        """Tests whether the :see:formfield method returns a valid form field
+        that is hidden."""
 
-        form_field = LocalizedUniqueSlugField(populate_from='title').formfield()
+        form_field = LocalizedUniqueSlugField(populate_from="title").formfield()
 
         assert isinstance(form_field, forms.CharField)
         assert isinstance(form_field.widget, forms.HiddenInput)

tests/test_value.py

@@ -1,7 +1,7 @@
-from django.db.models import F
 from django.conf import settings
-from django.utils import translation
+from django.db.models import F
 from django.test import TestCase, override_settings
+from django.utils import translation
 
 from localized_fields.value import LocalizedValue
 
@@ -13,16 +13,14 @@ class LocalizedValueTestCase(TestCase):
 
     @staticmethod
     def tearDown():
-        """Assures that the current language
-        is set back to the default."""
+        """Assures that the current language is set back to the default."""
 
         translation.activate(settings.LANGUAGE_CODE)
 
     @staticmethod
     def test_init():
-        """Tests whether the __init__ function
-        of the :see:LocalizedValue class works
-        as expected."""
+        """Tests whether the __init__ function of the :see:LocalizedValue class
+        works as expected."""
 
         keys = get_init_values()
         value = LocalizedValue(keys)
@@ -32,32 +30,41 @@ class LocalizedValueTestCase(TestCase):
 
     @staticmethod
     def test_init_default_values():
-        """Tests whether the __init__ function
-        of the :see:LocalizedValue accepts the
-        default value or an empty dict properly."""
+        """Tests whether the __init__ function of the :see:LocalizedValue
+        accepts the default value or an empty dict properly."""
 
         value = LocalizedValue()
 
         for lang_code, _ in settings.LANGUAGES:
             assert getattr(value, lang_code) is None
 
+    @staticmethod
+    def test_is_empty():
+        """Tests whether a newly constructed :see:LocalizedValue without any
+        content is considered "empty"."""
+
+        value = LocalizedValue()
+        assert value.is_empty()
+
+        value.set(settings.LANGUAGE_CODE, "my value")
+        assert not value.is_empty()
+
     @staticmethod
     def test_init_array():
-        """Tests whether the __init__ function
-        of :see:LocalizedValue properly handles an
-        array.
+        """Tests whether the __init__ function of :see:LocalizedValue properly
+        handles an array.
 
-        Arrays can be passed to LocalizedValue as
-        a result of a ArrayAgg operation."""
+        Arrays can be passed to LocalizedValue as a result of a ArrayAgg
+        operation.
+        """
 
-        value = LocalizedValue(['my value'])
-        assert value.get(settings.LANGUAGE_CODE) == 'my value'
+        value = LocalizedValue(["my value"])
+        assert value.get(settings.LANGUAGE_CODE) == "my value"
 
     @staticmethod
     def test_get_explicit():
-        """Tests whether the the :see:LocalizedValue
-        class's :see:get function works properly
-        when specifying an explicit value."""
+        """Tests whether the the :see:LocalizedValue class's :see:get function
+        works properly when specifying an explicit value."""
 
         keys = get_init_values()
         localized_value = LocalizedValue(keys)
@@ -67,9 +74,8 @@ class LocalizedValueTestCase(TestCase):
 
     @staticmethod
     def test_get_default_language():
-        """Tests whether the :see:LocalizedValue
-        class's see:get function properly
-        gets the value in the default language."""
+        """Tests whether the :see:LocalizedValue class's see:get function
+        properly gets the value in the default language."""
 
         keys = get_init_values()
         localized_value = LocalizedValue(keys)
@@ -80,8 +86,8 @@ class LocalizedValueTestCase(TestCase):
 
     @staticmethod
     def test_set():
-        """Tests whether the :see:LocalizedValue
-        class's see:set function works properly."""
+        """Tests whether the :see:LocalizedValue class's see:set function works
+        properly."""
 
         localized_value = LocalizedValue()
 
@@ -92,21 +98,21 @@ class LocalizedValueTestCase(TestCase):
 
     @staticmethod
     def test_eq():
-        """Tests whether the __eq__ operator
-        of :see:LocalizedValue works properly."""
+        """Tests whether the __eq__ operator of :see:LocalizedValue works
+        properly."""
 
-        a = LocalizedValue({'en': 'a', 'ar': 'b'})
-        b = LocalizedValue({'en': 'a', 'ar': 'b'})
+        a = LocalizedValue({"en": "a", "ar": "b"})
+        b = LocalizedValue({"en": "a", "ar": "b"})
 
         assert a == b
 
-        b.en = 'b'
+        b.en = "b"
         assert a != b
 
     @staticmethod
     def test_translate():
-        """Tests whether the :see:LocalizedValue
-        class's __str__ works properly."""
+        """Tests whether the :see:LocalizedValue class's __str__ works
+        properly."""
 
         keys = get_init_values()
         localized_value = LocalizedValue(keys)
@@ -117,15 +123,12 @@ class LocalizedValueTestCase(TestCase):
 
     @staticmethod
     def test_translate_fallback():
-        """Tests whether the :see:LocalizedValue
-        class's translate()'s fallback functionality
-        works properly."""
+        """Tests whether the :see:LocalizedValue class's translate()'s fallback
+        functionality works properly."""
 
-        test_value = 'myvalue'
+        test_value = "myvalue"
 
-        localized_value = LocalizedValue({
-            settings.LANGUAGE_CODE: test_value
-        })
+        localized_value = LocalizedValue({settings.LANGUAGE_CODE: test_value})
 
         other_language = settings.LANGUAGES[-1][0]
 
@@ -146,50 +149,56 @@ class LocalizedValueTestCase(TestCase):
 
     @staticmethod
     def test_translate_none():
-        """Tests whether the :see:LocalizedValue
-        class's translate() method properly returns
-        None when there is no value."""
+        """Tests whether the :see:LocalizedValue class's translate() method
+        properly returns None when there is no value."""
 
         # with no value, we always expect it to return None
         localized_value = LocalizedValue()
         assert localized_value.translate() is None
-        assert str(localized_value) == ''
+        assert str(localized_value) == ""
 
         # with no value for the default language, the default
         # behavior is to return None, unless a custom fallback
         # chain is configured, which there is not for this test
         other_language = settings.LANGUAGES[-1][0]
-        localized_value = LocalizedValue({
-            other_language: 'hey'
-        })
+        localized_value = LocalizedValue({other_language: "hey"})
 
         translation.activate(settings.LANGUAGE_CODE)
         assert localized_value.translate() is None
-        assert str(localized_value) == ''
+        assert str(localized_value) == ""
 
     @staticmethod
     def test_translate_fallback_custom_fallback():
-        """Tests whether the :see:LocalizedValue class's
-        translate()'s fallback functionality properly respects
-        the LOCALIZED_FIELDS_FALLBACKS setting."""
+        """Tests whether the :see:LocalizedValue class's translate()'s fallback
+        functionality properly respects the LOCALIZED_FIELDS_FALLBACKS
+        setting."""
 
-        fallbacks = {
-            'nl': ['ro']
-        }
+        fallbacks = {"nl": ["ro"]}
 
-        localized_value = LocalizedValue({
-            settings.LANGUAGE_CODE: settings.LANGUAGE_CODE,
-            'ro': 'ro'
-        })
+        localized_value = LocalizedValue(
+            {settings.LANGUAGE_CODE: settings.LANGUAGE_CODE, "ro": "ro"}
+        )
 
         with override_settings(LOCALIZED_FIELDS_FALLBACKS=fallbacks):
-            with translation.override('nl'):
-                assert localized_value.translate() == 'ro'
+            with translation.override("nl"):
+                assert localized_value.translate() == "ro"
+
+    @staticmethod
+    def test_translate_custom_language():
+        """Tests whether the :see:LocalizedValue class's translate() ignores
+        the active language when one is specified explicitely."""
+
+        localized_value = LocalizedValue(
+            {settings.LANGUAGE_CODE: settings.LANGUAGE_CODE, "ro": "ro"}
+        )
+
+        with translation.override("en"):
+            assert localized_value.translate("ro") == "ro"
 
     @staticmethod
     def test_deconstruct():
-        """Tests whether the :see:LocalizedValue
-        class's :see:deconstruct function works properly."""
+        """Tests whether the :see:LocalizedValue class's :see:deconstruct
+        function works properly."""
 
         keys = get_init_values()
         value = LocalizedValue(keys)
@@ -200,16 +209,16 @@ class LocalizedValueTestCase(TestCase):
 
     @staticmethod
     def test_construct_string():
-        """Tests whether the :see:LocalizedValue's constructor
-        assumes the primary language when passing a single string."""
+        """Tests whether the :see:LocalizedValue's constructor assumes the
+        primary language when passing a single string."""
 
-        value = LocalizedValue('beer')
-        assert value.get(settings.LANGUAGE_CODE) == 'beer'
+        value = LocalizedValue("beer")
+        assert value.get(settings.LANGUAGE_CODE) == "beer"
 
     @staticmethod
     def test_construct_expression():
-        """Tests whether passing expressions as values
-        works properly and are not converted to string."""
+        """Tests whether passing expressions as values works properly and are
+        not converted to string."""
 
-        value = LocalizedValue(dict(en=F('other')))
+        value = LocalizedValue(dict(en=F("other")))
         assert isinstance(value.en, F)

tests/test_widget.py

@@ -1,4 +1,5 @@
 import re
+
 from django.conf import settings
 from django.test import TestCase
 
@@ -11,8 +12,7 @@ class LocalizedFieldWidgetTestCase(TestCase):
 
     @staticmethod
     def test_widget_creation():
-        """Tests whether a widget is created for every
-        language correctly."""
+        """Tests whether a widget is created for every language correctly."""
 
         widget = LocalizedFieldWidget()
         assert len(widget.widgets) == len(settings.LANGUAGES)
@@ -20,9 +20,8 @@ class LocalizedFieldWidgetTestCase(TestCase):
 
     @staticmethod
     def test_decompress():
-        """Tests whether a :see:LocalizedValue instance
-        can correctly be "decompressed" over the available
-        widgets."""
+        """Tests whether a :see:LocalizedValue instance can correctly be
+        "decompressed" over the available widgets."""
 
         localized_value = LocalizedValue()
         for lang_code, lang_name in settings.LANGUAGES:
@@ -31,13 +30,15 @@ class LocalizedFieldWidgetTestCase(TestCase):
         widget = LocalizedFieldWidget()
         decompressed_values = widget.decompress(localized_value)
 
-        for (lang_code, _), value in zip(settings.LANGUAGES, decompressed_values):
+        for (lang_code, _), value in zip(
+            settings.LANGUAGES, decompressed_values
+        ):
             assert localized_value.get(lang_code) == value
 
     @staticmethod
     def test_decompress_none():
-        """Tests whether the :see:LocalizedFieldWidget correctly
-        handles :see:None."""
+        """Tests whether the :see:LocalizedFieldWidget correctly handles
+        :see:None."""
 
         widget = LocalizedFieldWidget()
         decompressed_values = widget.decompress(None)
@@ -47,16 +48,17 @@ class LocalizedFieldWidgetTestCase(TestCase):
 
     @staticmethod
     def test_get_context_required():
-        """Tests whether the :see:get_context correctly
-        handles 'required' attribute, separately for each subwidget."""
+        """Tests whether the :see:get_context correctly handles 'required'
+        attribute, separately for each subwidget."""
 
         widget = LocalizedFieldWidget()
         widget.widgets[0].is_required = True
         widget.widgets[1].is_required = False
-        context = widget.get_context(name='test', value=LocalizedValue(),
-                                     attrs=dict(required=True))
-        assert context['widget']['subwidgets'][0]['attrs']['required']
-        assert 'required' not in context['widget']['subwidgets'][1]['attrs']
+        context = widget.get_context(
+            name="test", value=LocalizedValue(), attrs=dict(required=True)
+        )
+        assert context["widget"]["subwidgets"][0]["attrs"]["required"]
+        assert "required" not in context["widget"]["subwidgets"][1]["attrs"]
 
     @staticmethod
     def test_get_context_langs():
@@ -64,20 +66,20 @@ class LocalizedFieldWidgetTestCase(TestCase):
         'lang_name' attribute for each subwidget."""
 
         widget = LocalizedFieldWidget()
-        context = widget.get_context(name='test', value=LocalizedValue(),
-                                     attrs=dict())
-        subwidgets_context = context['widget']['subwidgets']
+        context = widget.get_context(
+            name="test", value=LocalizedValue(), attrs=dict()
+        )
+        subwidgets_context = context["widget"]["subwidgets"]
         for widget, context in zip(widget.widgets, subwidgets_context):
-            assert 'lang_code' in context
-            assert 'lang_name' in context
-            assert widget.lang_code == context['lang_code']
-            assert widget.lang_name == context['lang_name']
+            assert "lang_code" in context
+            assert "lang_name" in context
+            assert widget.lang_code == context["lang_code"]
+            assert widget.lang_name == context["lang_name"]
 
     @staticmethod
     def test_render():
-        """Tests whether the :see:LocalizedFieldWidget correctly
-        render."""
+        """Tests whether the :see:LocalizedFieldWidget correctly render."""
 
         widget = LocalizedFieldWidget()
-        output = widget.render(name='title', value=None)
-        assert bool(re.search('<label (.|\n|\t)*>\w+<\/label>', output))
+        output = widget.render(name="title", value=None)
+        assert bool(re.search(r"<label (.|\n|\t)*>\w+<\/label>", output))

tox.ini

@@ -1,14 +1,20 @@
 [tox]
-envlist = py35-dj{111,20,21,22}, py36-dj{111,20,21,22}, py37-dj{111,20,21,22}
+envlist = py36-dj{20,21,22,30,31,32}, py37-dj{20,21,22,30,31,32}, py38-dj{20,21,22,30,31,32,40,41,42}, py39-dj{30,31,32,40,41,42}, py310-dj{32,40,41,42,50}, py311-dj{42,50}
 
 [testenv]
 deps =
-    dj111: Django>=1.11,<1.12
     dj20: Django>=2.0,<2.1
     dj21: Django>=2.1,<2.2
     dj22: Django>=2.2,<2.3
-    -rrequirements/test.txt
+    dj30: Django>=3.0,<3.0.2
+    dj31: Django>=3.1,<3.2
+    dj32: Django>=3.2,<4.0
+    dj40: Django>=4.0,<4.1
+    dj41: Django>=4.1,<4.2
+    dj42: Django>=4.2,<5.0
+    dj50: Django>=5.0,<5.1
+    .[test]
 setenv =
     DJANGO_SETTINGS_MODULE=settings
 passenv = DATABASE_URL
-commands = coverage run manage.py test
+commands = python setup.py test