Python: Using isort with Black to improve your code base

isort is a Python package that sorts the order of your imports, and groups them into sections by type. So while a code formatter like Black will ensure the spacing and line length of your imports is correct, it will not modify their order.

So why bother ordering your imports?¹

To reduce cognitive load.

If each file has imports listed in a different order, this is more taxing to read through, and requires active concentration. Having a consistent grouping and order to your imports helps your brain to spot patterns, often without you being consciously aware.

To help with refactoring.

When you are refactoring code, third party code is effectively out-of-bounds; it is a black box that you can move around, or plug into different places, but you cannot change its inner workings. If it’s unclear whether imports belong to your code base or to some third party, this makes it more difficult to spot ways you can reorganise or simplify your code.

To discourage use of import side-effects.

In general, import side-effects are a Bad Idea™. They make it harder to reason about what the code does, and can lead to surprising effects. While relinquishing control of your import order to isort does not prevent use of import side-effects, it does draw a line in the sand, making developers think twice before trying to manipulate the import order.²

isort configuration §

isort comes with sensible defaults, but at a minimum I prefer to add the following configuration for it to my pyproject.toml:

pyproject.toml §

[tool.isort]
profile = "black"
import_heading_stdlib = "Standard library imports"
import_heading_thirdparty = "Third party imports"
import_heading_firstparty = "Project imports"
known_first_party = [
	"my_package_app",
	"my_package_lib",
	"my_package_util",
]

The reason for each line is as follows:

profile = "black"

I’m a strong advocate for using Black to automatically format Python code. Enabling this setting is critical to ensure that isort does not conflict with Black, since by default isort has a different opinion on the particulars of how imports should be arranged.

import_heading_* = "<blah>"

This adds a comment heading for each import section. By default the sections have no headings. Note that there are other sections, such as import_heading_local for if you do a from .local_file style import, which I prefer to avoid. You can also define your own sections, but I have not explored that. I prefer sticking to the main three: standard library, third party, and project imports (i.e. those which are part of your project’s package(s)).

known_first_party = [...]

This is necessary for the import_heading_firstparty setting to work correctly when you have multiple Python packages, some of which are defined in other pyproject.toml files. In order for isort to be able to identify which packages are first party imports (aka “Project imports”), list each one explicitly. Without setting this, isort is smart enough to identify packages defined in the local pyproject.toml file as being first party, but understandably it cannot determine that packages defined elsewhere are first party: they will be considered third party. If your Python project consists of just one package, then this is not necessary.

Here is an example of what using this configuration looks like:

# Standard library imports
import os
import queue
import shutil
import time

# Third party imports
import structlog

# Project imports
from my_package_app.widget import Thing
from my_package_lib.extras import SomethingElse
from my_package_util.helpers import do_something_useful

While you’re at it, it’s also worth configuring isort to run on pre-commit.