Restructured book, added Django chapter

Author: programmdesign

README.md

@@ -5,7 +5,7 @@ This is an open-source book of **Python anti-patterns and worst practices**. Che
 **Notice**: This is still (and will always be) a work-in-progress, feel free to contribute by suggesting improvements, adding new articles, improving existing ones, or translating this into other languages.
 
 # New articles
-If you add new articles, please use the provided [template](docs/template.rst).
+If you add new articles, please use the provided templates. Depending on the pattern you are creating, use either the [anti-pattern](templates/anti_pattern.rst) or the [migration-pattern](templates/migration_pattern.rst) template.
 
 #License
 

docs/_themes/quantifiedcode/layout.html

@@ -90,7 +90,7 @@
 
 
       <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
-        {% set toctree = toctree(maxdepth=2, collapse=False, includehidden=True) %}
+        {% set toctree = toctree(maxdepth=4, titles_only=True, collapse=True, includehidden=True) %}
         {% if toctree %}
             {{ toctree }}
         {% else %}
@@ -183,12 +183,12 @@
       (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
       m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
       })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
-    
+
       ga('create', 'UA-51790189-2', 'auto');
       ga('set', 'anonymizeIp', true);
       ga('send', 'pageview', {
        'page': location.pathname + location.search  + location.hash
-      });      
+      });
     </script>
 
   {%- block footer %} {% endblock %}

docs/django/1.8/index.rst

@@ -0,0 +1,10 @@
+Django 1.8
+==========
+
+In this section, you'll find anti-patterns that apply specifically to Django 1.8.
+
+.. toctree::
+    :maxdepth: 2
+
+    migration/index
+

docs/django/1.8/migration/index.rst

@@ -0,0 +1,16 @@
+:fa:`magic` Migration
+======================
+
+Migrating to a new Django version can be time consuming. To make this process easier, this chapter lists deprecated features and shows potential migration patterns/pathes.
+
+.. toctree::
+    :maxdepth: 1
+
+    template_dirs_deprecated
+    template_debug_deprecated
+    template_loaders_deprecated
+    template_string_if_invalid_deprecated
+
+
+
+

docs/django/1.8/migration/template_debug_deprecated.rst

@@ -0,0 +1,48 @@
+``TEMPLATE_DEBUG`` deprecated
+=============================
+
+This setting sets the output that the template system should use for invalid (e.g. misspelled) variables. The default value is an empty string ``''``. This setting is deprecated since Django version 1.8. Set the `TEMPLATE_DEBUG` option in the ``OPTIONS`` of a ``DjangoTemplates`` backend instead.
+
+Deprecated feature
+------------------
+
+Deprecated ``TEMPLATE_DEBUG`` setting used.
+
+.. code:: python
+
+    """ settings.py """
+
+    TEMPLATE_DEBUG = True
+
+
+Migration path
+--------------
+
+As of Django 1.8 you should set ``debug`` option in the ``OPTIONS`` of a ``DjangoTemplates`` backend instead.
+
+.. code:: python
+
+    """ settings.py """
+
+    TEMPLATES = [
+        {
+            'BACKEND': 'django.template.backends.django.DjangoTemplates',
+            'APP_DIRS': True,
+            'DIRS': '/path/to/my/templates',
+            'OPTIONS': {
+                 'debug': True,
+             }
+        },
+    ]
+
+References
+----------
+
+- [Django documentation - Settings: TEMPLATE_DEBUG](https://docs.djangoproject.com/en/1.8/ref/settings/#template-debug)
+- [Django documentation - Settings: TEMPLATES](https://docs.djangoproject.com/en/1.8/ref/settings/#templates)
+- [Django documentation - Templates: Built-in backends](https://docs.djangoproject.com/en/1.8/topics/templates/#module-django.template.backends.django)
+
+Status
+------
+
+- `Automated code check available <https://www.quantifiedcode.com/app/pattern/705f569e1a174f39946454933994e4b3>`_

docs/django/1.8/migration/template_dirs_deprecated.rst

@@ -0,0 +1,49 @@
+``TEMPLATE_DIRS`` deprecated
+============================
+
+This setting is deprecated since Django version 1.8. Set the ``DIRS`` option of a [`DjangoTemplates` backend](https://docs.djangoproject.com/en/1.8/topics/templates/#module-django.template.backends.django) instead.
+
+Deprecated feature
+------------------
+
+Deprecated ``TEMPLATE_DIRS`` setting used.
+
+.. code:: python
+
+    """ settings.py """
+
+    TEMPLATE_DIRS = [
+        "path/to/my/templates",
+    ]
+
+Migration path
+--------------
+
+As of Django 1.8 you should set ``DIRS`` option within ``TEMPLATES`` setting. It defines where the engine should look for template source files, in search order.
+
+.. code:: python
+
+    """ settings.py """
+
+    TEMPLATES = [
+        {
+            'BACKEND': 'django.template.backends.django.DjangoTemplates',
+            'APP_DIRS': True,
+            'DIRS': '/path/to/my/templates',
+        },
+    ]
+
+
+References
+----------
+
+- [Django documentation - Settings: TEMPLATES](https://docs.djangoproject.com/en/1.8/ref/settings/#templates)
+- [Django documentation - Settings: TEMPLATE_DIRS](https://docs.djangoproject.com/en/1.8/ref/settings/#template-dirs)
+- [Django documentation - Templates: Built-in backends](https://docs.djangoproject.com/en/1.8/topics/templates/#module-django.template.backends.django)
+
+
+Status
+------
+
+- `Automated code check available <https://www.quantifiedcode.com/app/pattern/4af01dfd013241f58d0469e014209e3a>`_
+

docs/django/1.8/migration/template_loaders_deprecated.rst

@@ -0,0 +1,56 @@
+``TEMPLATE_LOADERS`` deprecated
+===============================
+
+This setting is deprecated since Django version 1.8. Set the `LOADERS` option of a [`DjangoTemplates` backend](https://docs.djangoproject.com/en/1.8/topics/templates/#module-django.template.backends.django) instead.
+
+Deprecated feature
+------------------
+
+Deprecated ``TEMPLATE_LOADERS`` setting used.
+
+.. code:: python
+
+    """ settings.py """
+
+    TEMPLATE_LOADERS = (
+            'django.template.loaders.filesystem.Loader',
+            'django.template.loaders.app_directories.Loader',
+    )
+    ```
+
+Migration path
+--------------
+
+As of Django 1.8 you should set ``loaders`` option in the ``TEMPLATES`` setting. It defines where the engine should look for template source files, in search order.
+
+.. code:: python
+
+    """ settings.py """
+
+    TEMPLATES = [
+        {
+            'BACKEND': 'django.template.backends.django.DjangoTemplates',
+            'APP_DIRS': True,
+            'DIRS': '/path/to/my/templates',
+            'OPTIONS': {
+                 'loaders': (
+                     'django.template.loaders.filesystem.Loader',
+                     'django.template.loaders.app_directories.Loader',
+                  ),
+             }
+        },
+    ]
+
+
+References
+----------
+
+- [Django documentation - Settings: TEMPLATES](https://docs.djangoproject.com/en/1.8/ref/settings/#templates)
+- [Django documentation - Settings: TEMPLATE_DIRS](https://docs.djangoproject.com/en/1.8/ref/settings/#template-loaders)
+- [Django documentation - Templates: Built-in backends](https://docs.djangoproject.com/en/1.8/topics/templates/#module-django.template.backends.django)
+
+Status
+------
+
+- `Automated code check available <https://www.quantifiedcode.com/app/pattern/1f408fdeddad425192c87dc2b101fc51>`_
+

docs/django/1.8/migration/template_string_if_invalid_deprecated.rst

@@ -0,0 +1,48 @@
+``TEMPLATE_STRING_IF_INVALID`` deprecated
+=========================================
+
+This setting sets the output that the template system should use for invalid (e.g. misspelled) variables. The default value is an empty string ``''``. This setting is deprecated since Django version 1.8. Set the `string_if_invalid` option in the `OPTIONS` of a `DjangoTemplates` backend instead.
+
+Deprecated feature
+------------------
+
+Deprecated ``TEMPLATE_STRING_IF_INVALID`` setting used.
+
+.. code:: python
+
+    """ settings.py """
+
+    TEMPLATE_STRING_IF_INVALID = 'Invalid variable'
+
+Migration path
+--------------
+
+As of Django 1.8 you should set ``string_if_invalid`` option in the ``OPTIONS`` of a ``DjangoTemplates`` backend instead.
+
+.. code:: python
+
+    """ settings.py """
+
+    TEMPLATES = [
+        {
+            'BACKEND': 'django.template.backends.django.DjangoTemplates',
+            'APP_DIRS': True,
+            'DIRS': '/path/to/my/templates',
+            'OPTIONS': {
+                 'string_if_invalid': 'Invalid varialbe!',
+             }
+        },
+    ]
+
+References
+----------
+
+- [Django documentation - Settings: TEMPLATES](https://docs.djangoproject.com/en/1.8/ref/settings/#templates)
+- [Django documentation - Settings: TEMPLATE_STRING_IF_INVALID](https://docs.djangoproject.com/en/1.8/ref/settings/#template-string-if-invalid)
+- [Django documentation - Templates: Built-in backends](https://docs.djangoproject.com/en/1.8/topics/templates/#module-django.template.backends.django)
+- [Django documentation - Templates: How invalid variables are handled](https://docs.djangoproject.com/en/1.8/ref/templates/api/#how-invalid-variables-are-handled)
+
+Status
+------
+
+- `Automated code check available <https://www.quantifiedcode.com/app/pattern/6f1b0d6580e04149983617cefa39d08c>`_

docs/django/all/correctness/index.rst

@@ -0,0 +1,8 @@
+:fa:`check` Correctness
+=======================
+
+.. toctree::
+    :maxdepth: 1
+
+    not_using_forward_slashes
+    not_using_null_boolean_field

docs/django/all/correctness/not_using_forward_slashes.rst

@@ -0,0 +1,48 @@
+Not using forward slashes
+=========================
+
+Django requires you to use forward slashes ``/`` whenever you indicate a path, even on Windows. In your settings, this is true for the following variables.
+
+- ``STATICFILES_DIRS``
+- ``TEMPLATE_DIRS``
+- ``DATABASES['<your database>'][NAME]``
+- ``FIXTURE_DIRS``
+
+Anti-pattern
+------------
+
+This pattern is exemplary for any of the above mentioned settings. It uses backslashes, instead of forward slashes.
+
+.. code:: python
+
+    """ settings.py """
+
+    STATICFILES_DIRS = [
+        "\path\to\my\static\files",
+    ]
+
+Best practice
+-------------
+
+Django requires you to use forward slashes ``/``, even on Windows.
+
+.. code:: python
+
+    """ settings.py """
+
+    STATICFILES_DIRS = [
+        "\path\to\my\static\files",
+    ]
+
+References
+----------
+
+- [Django documentation - Settings: TEMPLATE_DIRS](https://docs.djangoproject.com/en/1.8/ref/settings/#template-dirs)
+- [Django documentation - Settings: FIXTURE_DIRS](https://docs.djangoproject.com/en/1.8/ref/settings/#fixture-dirs)
+- [Django documentation - Settings: STATIC_FILES_DIRS](https://docs.djangoproject.com/en/1.8/ref/settings/#https://docs.djangoproject.com/en/1.8/ref/settings/#staticfiles-dirs)
+- [Django documentation - Settings: HOST](https://docs.djangoproject.com/en/1.8/ref/settings/#host)
+
+Status
+------
+
+- `Automated code check available <https://www.quantifiedcode.com/app/pattern/ff48f625efa5424088acfc1ea788db3e>`_

docs/django/all/correctness/not_using_null_boolean_field.rst

@@ -0,0 +1,45 @@
+Not using ``NullBooleanField``
+==============================
+
+A ``BooleanField`` in Django accepts only the two values: ``true`` and ``false``. If you need to accept ``NULL`` values, you have to use a ``NullBooleanField``.
+
+Anti-pattern
+------------
+
+The following model uses a ``BooleanField`` with the option ``null=True``, instead of using a ``NullBooleanField``.
+
+.. code:: python
+
+    from django.db import models
+
+    class Person(models.Model):
+        first_name = models.CharField(max_length=30)
+        last_name = models.CharField(max_length=30)
+        activated = models.BooleanField(null=True)
+
+
+Best practice
+-------------
+
+Use a ``NullBooleanField`` instead:
+
+.. code:: python
+
+    from django.db import models
+
+    class Person(models.Model):
+        first_name = models.CharField(max_length=30)
+        last_name = models.CharField(max_length=30)
+        # Using NullBooleanField instead
+        activated = models.NullBooleanField()
+
+Reference
+---------
+
+- [Django documentation - Model field reference: BooleanField (https://docs.djangoproject.com/en/1.8/ref/models/fields/#booleanfield)
+- [Django documentation - Model field reference: NullBooleanField (https://docs.djangoproject.com/en/1.8/ref/models/fields/#nullbooleanfield)
+
+Status
+------
+
+- `Automated code check available <https://www.quantifiedcode.com/app/pattern/f9a71a2aeef846ceafce68f5652b9dad>`_

docs/django/all/index.rst

@@ -0,0 +1,12 @@
+Django (all versions)
+=====================
+
+This chapter contains anti- and migration patterns that apply to all (recent) Django version.
+
+.. toctree::
+    :maxdepth: 2
+
+    maintainability/index
+    security/index
+    correctness/index
+