Auto-organize Python Imports Using isort

Organizing Python Imports

Organizing imports is a small but essential aspect of writing clean and maintainable Python code. As your codebase grows, import statements can become disorganized, leading to confusion and decreased readability. This is where isort comes to the rescue.

What is isort?

isort is a Python utility that sorts and organizes imports automatically according to PEP 8 (Python Enhancement Proposal-8). It ensures that import statements are arranged in a consistent and logical order. By categorizing and alphabetizing imports, isort eliminates clutter and makes your code more readable.

How to Use isort?

1. Activate your virtual environment

Before installing isort, you have to activate your virtual environment. A virtual environment helps isolate your project's dependencies from your global Python installation.

2. Install isort via pip

Once your virtual environment is active, download and install isort using pip by entering the following command in your terminal:

1

pip install isort

3. Flag codes to be ignored

You may want to flag the imports that isort should not reformat.

To ignore a single line of import, use # isort: skip:

1
2

import a # isort: skip
import b

To ignore a block of imports, start with # isort: off and end with # isort: on:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

import a
import b

# isort: off
import c
import d
# isort: on

import e
import f

To ignore imports in the entire file, use # isort: skip_file:

1
2
3
4

# isort: skip_file

import a
import b

4. (Optional) Customize isort's configuration

To customize isort's behavior, you can use configuration files, such as .isort.cfg (preferred), pyproject.toml (preferred), setup.cfg, tox.ini, .editorconfig, and custom files. For more information, you may want to visit isort's official documentation on its supported config files.

I prefer to use the .isort.cfg file as it is easy to understand that this configuration file is related to isort.

Using the Gen EMR project as an example, below is a sample production .isort.cfg file from our Django project.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

[settings]
profile = black
default_section = THIRDPARTY
known_first_party = pages  
known_django = django 
sections = FUTURE,STDLIB,DJANGO,THIRDPARTY,FIRSTPARTY,LOCALFOLDER
import_heading_future = Standard Python future Libraries
import_heading_stdlib = Standard Python libraries
import_heading_django = Django module imports
import_heading_thirdparty = Third-party libraries
import_heading_firstparty = Gen EMR module imports
import_heading_localfolder = Gen EMR local folder imports

You may want to view the isort's available config options.

• The profile is required to integrate Black with isort.
• The default_section is the default section where uncategorized imports will be placed.
• The known_first_party contains your project's local packages (e.g., A Django app called pages).
• The known_[package_name] creates a new custom section name for known imports (e.g., Django).
• The sections shows how imports will be organized in a chronological manner.
• The import_heading_[section_name] adds a comment for each section to help quickly categorize the imports.

Lesson learned: You can use isort --show-config to check whether isort is using the settings you specified in your configuration file.

In the last section of this tutorial, check out the sample output using this configuration.

5. Format Files

Make sure to navigate to your source code directory before running the following code in your terminal.

To format a single file:

1

isort [file_name].py

To format the files in the entire directory:

1

isort [directory_name]/

Sample isort's Formatting

Before formatting:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

from my_lib import Object
import os
from my_lib import Object3
from my_lib import Object2
from django.contrib.auth import get_user_model
from gen_emr.models import Answer
from pages import url
from .forms import QuestionForm
import sys
from third_party import lib15, lib1, lib2, lib3, lib4, lib5, lib6, lib7, lib8, lib9, lib10, lib11, lib12, lib13, lib14
import sys
from __future__ import absolute_import
from third_party import lib3
print("sample code")

After formatting:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

# Standard Python future Libraries
from __future__ import absolute_import

# Standard Python libraries
import os
import sys

# Django module imports
from django.contrib.auth import get_user_model

# Third-party libraries
from my_lib import Object, Object2, Object3
from third_party import (
    lib1,
    lib2,
    lib3,
    lib4,
    lib5,
    lib6,
    lib7,
    lib8,
    lib9,
    lib10,
    lib11,
    lib12,
    lib13,
    lib14,
    lib15,
)

# Gen EMR module imports
from gen_emr.models import Answer
from pages import url

# Gen EMR local folder imports
from .forms import QuestionForm

print("sample code")