Fixed #23860 -- Documented imports order convention.

[wrwrwr]

Please see #23860.

[charettes]

Use :pep:XXX

[wrwrwr]

Thanks, any way to link to the imports section of the document?

[carljm]

This LGTM, modulo adding a blank line after __future__ imports.

[carljm]

@timgraham You do most of the code-formatting-enforcement these days (or so it seems to me, anyway) -- does this look OK to you?

[berkerpeksag]

Nitpick: The examples are a mix of Python 2 and Python 3 stdlib. nested_scopes is too old. I'd replace it with something like print_function. Also, concurrent.futures is only available on Python 3 stdlib. I'd replace it with email.message.

[wrwrwr]

OK, both replaced. nested_scope was the first one introduced and I believe all are guaranteed to be available forever, but the one that Django mostly uses nowadays is unicode_literals.

[berkerpeksag]

from django.db import (
    models, transaction, DataError, DatabaseError, Error, IntegrityError,
    InterfaceError, InternalError, NotSupportedError, OperationalError,
)

[wrwrwr]

I'd leave the closing brace on the 3rd line.

Ending the first line after the opening parenthesis is currently more or less as common as starting to list objects right away (173 cases compared to 152, but 88 files versus 124. Making a line break before the closing parenthesis isn't that popular however, with 60 files versus 148.

I can't guarantee the full accuracy of these stats (if any at all ;-), some of the commands used to get the numbers:

• grep -RPzl 'from\s+[\w.]+\s+import\s+\(' --include=*.py . | wc -l (205 files in total)
• grep -RPzl 'from\s+[\w.]+\s+import\s+\(\s*(\n|#)' --include=*.py . | wc -l (88)
• grep -RPzl 'from\s+[\w.]+\s+import\s+\(\w' --include=*.py . | wc -l (124)
• grep -RPzl 'from\s+[\w.]+\s+import\s+\([^\)]*\n\)' --include=*.py . | wc -l (60)
• grep -RPzl 'from\s+[\w.]+\s+import\s+\([^\)]*\w\)' --include=*.py . | wc -l (148)

What do you think?

[berkerpeksag]

"Fixed #23860 -- Document [...]" -> "Fixed #23860 -- Documented [...]"

[MarkusH]

Do we really place import ... after from .. import ...? I think we mix them right now and just sort them by module.

[wrwrwr]

I've written this fragment choosing a style at random (just looking at a few files), actually changing it from "before" to "after" in an early update. Having them sorted out seemed slightly more elegant, but no real arguments on this one.

An imperfect look at the sources:

• a single block with from ... lines followed by some import ... lines and then from ... again: 20 files;
• one or more import lines followed by two or more from lines: 48 (some of these are import django at the beginning of Django imports or are alphabetical by a different coincidence, some others are due to a missing blank line after the standard library block);
• at least two from lines before an import line: 17 (again some of these are alphabetical).

Here are the commands I've used, maybe you'll figure out something more accurate:

• grep -RPzl '\nfrom[^\n]+\n(import[^\n]+\n)+from' --include=*.py . | wc -l (20)
• grep -RPzl '\n(import[^\n]+\n)+(from[^\n]+\n){2,}' --include=*.py . | wc -l (48)
• grep -RPzl '\n(from[^\n]+\n){2,}import' --include=*.py . | wc -l (17)

(note that you may drop the wc -l and replace l with o to see the matches in all of these).

I'm not sure if isort has a setting for this one -- it seems it puts import lines before from lines.

[timgraham]

I've resumed work on this with isort in #4008 and #4009. Thanks for starting the conversation.