isort

Warnings

• breaking Major versions of `isort` regularly drop support for older Python versions. Version 7.0.0 dropped support for Python 3.9, and version 6.0.0 dropped Python 3.8. Current versions (8.x) require Python >= 3.10.0.
  Fix: Ensure your project's Python interpreter meets the minimum requirement for your `isort` version or pin `isort` to an older version compatible with your environment.
• breaking isort v8.0.0 removed the `setuptools` plugin and deprecated old finders flags and legacy finder logic. Version 6.1.0 also dropped the use of the non-standard `pkg_resources` API. Integrations relying on these components will break.
  Fix: Review your `isort` configuration and any custom scripts for usage of `setuptools` plugin or legacy finder flags. Update integrations to use `isort`'s official programmatic API or standard configuration methods. Refactor any code depending on `pkg_resources` for dependency discovery.
• gotcha `isort` can conflict with other code formatters, notably `Black`, if not configured correctly. Both tools format imports but with different default styles.
  Fix: Always configure `isort` with the `black` profile when using it alongside `Black`. This can be done via `isort --profile black` on the command line, or by adding `profile = "black"` under `[tool.isort]` in your `pyproject.toml` or `[isort]` in `.isort.cfg`.
• gotcha `isort` supports multiple configuration file formats (`pyproject.toml`, `.isort.cfg`, `setup.cfg`, `tox.ini`, `.editorconfig`), which can lead to confusion regarding precedence and correct syntax. For `pyproject.toml`, settings must be under `[tool.isort]`.
  Fix: Consolidate your configuration into a single, preferred file format like `pyproject.toml` (using `[tool.isort]`) or `.isort.cfg` (using `[settings]` or `[isort]`). Use `isort --verbose` to confirm which configuration file is being used for a given path.
• gotcha The `--atomic` flag, which prevents `isort` from applying changes that introduce syntax errors, is disabled by default. Using it can prevent `isort` from running against code written using a different Python version than the one `isort` is run with.
  Fix: Be mindful when using `--atomic` in CI/CD environments, especially in projects with diverse Python version targets. It's often safer to rely on your test suite or linter to catch syntax errors after `isort` runs without `--atomic`.
• gotcha Prior to version 8.0.0, `isort` had an edge case where it could incorrectly handle `__future__` imports. While fixed in 8.0.0, older versions might exhibit subtle issues.
  Fix: Upgrade to `isort` 8.0.0 or newer if your project relies heavily on `__future__` imports and you encounter unexpected formatting behavior. Otherwise, carefully review `isort`'s output on such files.

Install

• pip install isort Install latest version

Imports

• isort

  import isort

  The `isort` module is imported directly for programmatic access to functions like `isort.code()` or `isort.file()`.

Quickstart

Demonstrates programmatic use of `isort` to sort a string of Python code and check if it's correctly sorted. The `isort.code()` function takes a string of code and returns the sorted version, while `isort.check_code()` verifies compliance.

import isort

unsorted_code = '''import os
import sys
from third_party import lib
from . import local_module'''

sorted_code = isort.code(unsorted_code)
print(sorted_code)

# Example of checking if code is sorted correctly
is_sorted = isort.check_code(sorted_code)
print(f"Is the code sorted correctly? {is_sorted}")