Fixed #23860 -- Documented import order convention.

1 files changed, 79 insertions, 8 deletions

diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt
index dd0d334072..7275393888 100644
--- a/docs/internals/contributing/writing-code/coding-style.txt
+++ b/docs/internals/contributing/writing-code/coding-style.txt
@@ -32,14 +32,6 @@ Python style
 * Use ``InitialCaps`` for class names (or for factory functions that
   return classes).
 
-* Use convenience imports whenever available. For example, do this::
-
-      from django.views.generic import View
-
-  Don't do this::
-
-      from django.views.generic.base import View
-
 * In docstrings, follow :pep:`257`. For example::
 
       def foo():
@@ -48,6 +40,85 @@ Python style
           """
           ...
 
+Imports
+-------
+
+* Use `isort <https://github.com/timothycrosley/isort#readme>`_ to automate
+  import sorting using the guidelines below.
+
+  Quick start:
+
+  .. code-block:: bash
+
+      $ pip install isort
+      $ isort -rc .
+
+  This runs ``isort`` recursively from your current directory, modifying any
+  files that don't conform to the guidelines. If you need to have imports out
+  of order (to avoid a circular import, for example) use a comment like this::
+
+      import module  # isort:skip
+
+* Put imports in these groups: future, standard library, third-party libraries,
+  other Django components, local Django component, try/excepts. Sort lines in
+  each group alphabetically by the full module name. Place all ``import module``
+  statements before ``from module import objects`` in each section.
+
+* On each line, alphabetize the items with the upper case items grouped before
+  the lower case items.
+
+* Break long lines using parentheses and indent continuation lines by 4 spaces.
+  Include a trailing comma after the last import and put the closing
+  parenthesis on its own line.
+
+  Use a single blank line between the last import and any module level code,
+  and use two blank lines above the first function or class.
+
+  For example (comments are for explanatory purposes only):
+
+  .. snippet::
+      :filename: django/contrib/admin/example.py
+
+      # future
+      from __future__ import unicode_literals
+
+      # standard library
+      import json
+      from itertools import chain
+
+      # third-party
+      import bcrypt
+
+      # Django
+      from django.http import Http404
+      from django.http.response import (
+          Http404, HttpResponse, HttpResponseNotAllowed, StreamingHttpResponse,
+          cookie,
+      )
+
+      # local Django
+      from .models import LogEntry
+
+      # try/except
+      try:
+          import pytz
+      except ImportError:
+          pytz = None
+
+      CONSTANT = 'foo'
+
+
+      class Example(object):
+          # ...
+
+* Use convenience imports whenever available. For example, do this::
+
+      from django.views.generic import View
+
+  instead of::
+
+      from django.views.generic.base import View
+
 Template style
 --------------