Document the preferred imports order

[Wojtek Ruszczewski]

I think it would be nice to have the (soft?) convention on imports order documented. It's said that Django has one, but I've recently spent some time trying to figure out what it is and couldn't find any precise info or get a consistent view based on the source.

​PEP 8 only asks to put imports on separate lines at the top of the file, guides to make "standard library", "related" and "local" groups, recommends absolute imports (unless dealing with complex package layouts), and discourages the use of "*" in most cases.

A short example on the ​coding style page would be enough. Things to mention:

• alphabetical order for modules, classes and objects (within groups);
• modules before classes, other objects after classes?
• "import" before "from ... import"?
• line breaking of lengthy imports.

Some conventions from other projects: ​Google, ​reddit, ​OpenStack, ​Plone.

[Aymeric Augustin]

Yes, whatever convention is chosen, it would be good to have on for new or refactored code.

[Wojtek Ruszczewski]

Here's a ​preliminary docs addition with an example chosen to demonstrate what there is to consider. Some highlights: -- blank line after __future__? -- not grouping imported objects? -- ignore case within words?

[Carl Meyer]

Replying to wrwrwr:

Here's a ​preliminary docs addition with an example chosen to demonstrate what there is to consider. Some highlights: -- blank line after __future__? -- not grouping imported objects? -- ignore case within words?

If you create a pull-request, that would allow in-line comments.

[Wojtek Ruszczewski]

Here's a ​pull request for more convenient discussion.

[Tim Graham]

As I mentioned on the mailing list, I'd like to take a look at ​isort and see if it'll work for us so we can automate this and not have to think about it very much.

[Wojtek Ruszczewski]

Good idea. I've been playing with isort a bit and prepared some flake8 / isort ​pre-commit hooks for those on the other side of the looking-glass. Maybe you'll find the ​isort config useful. The convention would need some amending to make it work: -- putting "import" before "from" statements, -- choosing a slightly different line breaking style, -- sorting objects into constants, classes, modules & other objects (case based).

[Tim Graham <timograham@…>]

In 0ed7d155635da9f79d4dd67e4889087d3673c6da:

Sorted imports with isort; refs #23860.

[Tim Graham <timograham@…>]

In cd155c7c7160f5178833593713727f013d3ed36d:

Fixed #23860 -- Documented import order convention.

[Tim Graham <timograham@…>]

In a8b70d251d238b4e6cfc7bb4296da15494f8dff3:

[1.8.x] Sorted imports with isort; refs #23860.

Backport of 0ed7d155635da9f79d4dd67e4889087d3673c6da from master