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 `_ 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 --------------