Plugins for other text editors

I use Kate, and Kate provides a very nice Python plugin API so I wrote a
Kate plugin. That said I will enthusiastically accept pull requests that
include plugins for other text editors and add documentation for them as
I am notified.

How does isort work?

isort parses specified files for global level import lines (imports
outside of try / excepts blocks, functions, etc..) and puts them all at
the top of the file grouped together by the type of import:

Inside of each section the imports are sorted alphabetically. isort
automatically removes duplicate python imports, and wraps long from
imports to the specified line length (defaults to 80).

When will isort not work?

If you ever have the situation where you need to have a try / except
block in the middle of top-level imports or if your import order is
directly linked to precedence.

For example: a common practice in Django settings files is importing *
from various settings files to form a new settings file. In this case if
any of the imports change order you are changing the settings definition
itself.

However, you can configure isort to skip over just these files - or even
to force certain imports to the top.

Configuring isort

If you find the default isort settings do not work well for your
project, isort provides several ways to adjust the behavior.

Additionally, you can specify project level configuration simply by
placing a .isort.cfg file at the root of your project. isort will look
up to 25 directories up, from the one it is ran, to find a project
specific configuration.

Or, if you prefer, you can add an isort section to your project’s
setup.cfg with any desired settings.

You can then override any of these settings by using command line
arguments, or by passing in override values to the SortImports class.

Finally, as of version 3.0 isort supports editorconfig files using the
standard syntax defined here: http://editorconfig.org/

Meaning you place any standard isort configuration parameters within a
.editorconfig file under the *.py section and they will be honored.

Multi line output modes

You will notice above the “multi_line_output” setting. This setting
defines how from imports wrap when they extend past the line_length
limit and has 4 possible settings:

0 - Grid

from third_party import (lib1, lib2, lib3,
lib4, lib5, ...)

1 - Vertical

from third_party import (lib1,
lib2,
lib3
lib4,
lib5,
...)

2 - Hanging Indent

from third_party import \
lib1, lib2, lib3, \
lib4, lib5, lib6

3 - Vertical Hanging Indent

from third_party import (
lib1,
lib2,
lib3,
lib4,
)

4 - Hanging Grid

from third_party import (
lib1, lib2, lib3, lib4,
lib5, ...)

5 - Hanging Grid Grouped

from third_party import (
lib1, lib2, lib3, lib4,
lib5, ...
)

Alternatively, you can set force_single_line to True (-sl on the
command line) and every import will appear on its own line

Note: to change the how constant indents appear - simply change the
indent property with the following accepted formats: * Number of spaces
you would like. For example: 4 would cause standard 4 space indentation.
* Tab * A verbatim string with quotes around it. For example: ” ” is
equivalent to 4

Intelligently Balanced Multi-line Imports

As of isort 3.1.0 support for balanced multi-line imports has been
added. With this enabled isort will dynamically change the import length
to the one that produces the most balanced grid, while staying below the
maximum import length defined.

To enable this set ‘balanced_wrapping’ to True in your config or pass
the -e option into the command line utility.

Auto-comment import sections

Some projects prefer to have import sections uniquely titled to aid in
identifying the sections quickly when visually scanning. isort can
automate this as well. To do this simply set the
import_heading_{section_name} setting for each section you wish to
have auto commented - to the desired comment.

Which can help to ensure a certain level of code quality throughout a
project.

Why isort?

isort simply stands for import sort. It was originally called
“sortImports” however I got tired of typing the extra characters and
came to the realization camelCase is not pythonic.

I wrote isort because in an organization I used to work in the manager
came in one day and decided all code must have alphabetically sorted
imports. The code base was huge - and he meant for us to do it by hand.
However, being a programmer - I’m too lazy to spend 8 hours mindlessly
performing a function, but not too lazy to spend 16 hours automating it.
I was given permission to open source sortImports and here we are :)