Add docs on making Wagtail compatible with multiple Django versions

pull/2403/head
Tim Heap 2016-03-27 07:15:56 +02:00
rodzic 8ac23d0554
commit 4b46ff341d
1 zmienionych plików z 53 dodań i 0 usunięć

Wyświetl plik

@ -12,6 +12,59 @@ Python 2 and 3 compatibility
All contributions should support Python 2 and 3 and we recommend using the `six <https://pythonhosted.org/six/>`_ compatibility library (use the pip version installed as a dependency, not the version bundled with Django).
Django compatibility
~~~~~~~~~~~~~~~~~~~~
Wagtail is written to be compatible with multiple versions of Django. Sometimes, this requires running one piece of code for recent version of Django, and another piece of code for older versions of Django. In these cases, always check which version of Django is being used by inspecting ``django.VERSION``:
.. code-block:: python
import django
if django.VERSION >= (1, 9):
# Use new attribute
related_field = field.rel
else:
# Use old, deprecated attribute
related_field = field.related
Always compare against the version using greater-or-equals (``>=``), so that code for newer versions of Django is first.
Do not use a ``try ... except`` when seeing if an object has an attribute or method introduced in a newer versions of Django, as it does not clearly express why the ``try ... except`` is used. An explicit check against the Django version makes the intention of the code very clear.
.. code-block:: python
# Do not do this
try:
related_field = field.rel
except AttributeError:
related_field = field.related
If the code needs to use something that changed in a version of Django many times, consider making a function that encapsulates the check:
.. code-block:: python
import django
def related_field(field):
if django.VERSION >= (1, 9):
return field.rel
else:
return field.related
If a new function has been introduced by Django that you think would be very useful for Wagtail, but is not available in older versions of Django that Wagtail supports, that function can be copied over in to Wagtail. If the user is running a new version of Django that has the function, the function should be imported from Django. Otherwise, the version bundled with Wagtail should be used. A link to the Django source code where this function was taken from should be included:
.. code-block:: python
import django
if django.VERSION >= (1, 9):
from django.core.validators import validate_unicode_slug
else:
# Taken from https://github.com/django/django/blob/1.9/django/core/validators.py#L230
def validate_unicode_slug(value):
# Code left as an exercise to the reader
pass
Tests
~~~~~