# pycqa/isort architecture

> Architecture diagram of the GitHub repository pycqa/isort, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pycqa/isort
- Repository: https://github.com/pycqa/isort

## Overview

##### Project type and purpose
- This is isort: an open-source Python utility and library whose sole purpose is to sort Python import statements according to configurable rules.
- It provides:
- A command-line interface (CLI) entrypoint
- A Python API for use in scripts
- Plugins/hooks for editors and git/pre-commit
- Configuration loaders (pyproject.toml, .isort.cfg, etc.)
- A core engine that parses, classifies, sorts, and rewrites imports

##### File structure
- Top-level files: Dockerfile, pyproject.toml, mkdocs.yml, script folder for docs generation, tests, examples, example plugins, CI workflows.
- Key source directory:
isort/
- __main__.py (CLI entrypoint)
- api.py (public Python API)
- parse.py (parsing imports)
- sorting.py (sorting logic)
- core.py, settings.py, profiles.py (configuration & profiles)
- output.py, io.py (file I/O and diffs)
- hooks.py, setuptools_commands.py (integration points)
- _vendored/tomli (third-party dependency for TOML parsing)
- Tests and example_*_plugin folders validate core behaviors and demonstrate extensibility.

##### README for additional insights
- Describes CLI usage, Python API, configuration options, multi-line modes, integration (pre-commit, setuptools).

a. Main components
1. CLI / Entry points
- isort/__main__.py
- pip – console_scripts → isort
2. Python API
- isort.api functions: file(), code(), etc.
3. Configuration Loader
- settings.py reads/merges config from files or CLI flags
- _vendored/tomli parses TOML configs
4. Parser
- parse.py tokenizes code, identifies import statements
5. Classification & Sections
- .py, profiles.py—classify imports into stdlib, third-party, local, custom sections
6. Sorting Engine
- sorting.py & core.py apply order, grouping, multi-line formatting strategies
7. Output Generator
- output.py builds diffs or overwritten files
- io.py handles file reads/writes
8. Integration Hooks & Plugins
- hooks.py (git pre-commit)
- setuptools_commands.py (setup.py integration)
- Editor plugins (external – examples under example_*_plugin)
9. Build & Docs
- scripts/ for autogenerating docs
- mkdocs.yml, docs/
10. Tests
- tests/unit and tests/integration validate each component

b. Relationships & data flow
- User invokes “isort” CLI → __main__.py
- CLI parses flags → settings.py
- API or CLI calls isort.api which orchestrates:
→ io.py reads source file
→ parse.py extracts import AST/tokens
→ identify.py/profiles.py classify imports into sections
→ sorting.py reorder import groups
→ output.py generates final text or diff
→ io.py writes back or prints to stdout
- Hooks/plugins wrap CLI/API calls to embed isort in git or setuptools workflows

c. Architectural patterns & design principles
- Modular separation: parsing, classification, sorting, I/O, configuration
- Plugin-style extensibility: example plugins show how to register new formatters/ordering rules
- Single Responsibility: each module focuses on one phase
- Configuration-driven behavior: profiles and settings decouple code from ordering rules

d. Key technologies, frameworks, libraries
- Python 3.9+
- Vendored tomli for TOML parsing
- setuptools entry points for CLI and commands
- mkdocs for documentation
- pytest for testing
- GitHub Actions for CI/CD

##### Detail
- Subcomponents (e.g., tomli parser under Config Loader, identify.py under Classifier)
- External dependencies (Python stdlib, vendored modules, third-party TOML)
- Don’t merely group everything as “core”; show each module’s role in the pipeline

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Pipeline
    subgraph "Core Pipeline"
        CLI["CLI Entry Point"]:::core
        API["Python API"]:::core
        Config["Configuration Loader"]:::config
        Parser["Parser"]:::core
        Classifier["Classifier & Sections"]:::core
        Sorter["Sorting Engine"]:::core
        Output["Output Generator"]:::io
        IO["I/O Module"]:::io

        CLI -->|invokes| Config
        API -->|calls| Config
        Config -->|provides settings| Parser
        Parser -->|extracts imports| Classifier
        Classifier -->|classifies| Sorter
        Sorter -->|reorders imports| Output
        Output -->|generates text| IO
        IO -->|reads/writes files| CLI
    end

    %% Integrations & Plugins
    subgraph "Integrations & Plugins"
        Hooks["Integration Hooks"]:::integration
        Plugins["Editor & Example Plugins"]:::integration

        Hooks -->|wraps| CLI
        Hooks -->|wraps| API
        Plugins -->|extend| CLI
        Plugins -->|extend| API
    end

    %% Tooling
    subgraph "Tooling & Testing"
        Docs["Build & Documentation"]:::tool
        Tests["Tests"]:::tool

        Docs -->|generate docs| CLI
        Tests -->|validate pipeline| Sorter
    end

    %% Click Events
    click CLI "https://github.com/pycqa/isort/blob/main/isort/__main__.py"
    click CLI "https://github.com/pycqa/isort/blob/main/isort/main.py"
    click API "https://github.com/pycqa/isort/blob/main/isort/api.py"
    click Config "https://github.com/pycqa/isort/blob/main/isort/settings.py"
    click Config "https://github.com/pycqa/isort/blob/main/isort/profiles.py"
    click Config "https://github.com/pycqa/isort/blob/main/isort/_vendored/tomli/__init__.py"
    click Parser "https://github.com/pycqa/isort/blob/main/isort/parse.py"
    click Parser "https://github.com/pycqa/isort/blob/main/isort/comments.py"
    click Parser "https://github.com/pycqa/isort/blob/main/isort/literal.py"
    click Classifier "https://github.com/pycqa/isort/blob/main/isort/identify.py"
    click Classifier "https://github.com/pycqa/isort/blob/main/isort/sections.py"
    click Classifier "https://github.com/pycqa/isort/blob/main/isort/place.py"
    click Classifier "https://github.com/pycqa/isort/tree/main/isort/stdlibs/"
    click Sorter "https://github.com/pycqa/isort/blob/main/isort/sorting.py"
    click Sorter "https://github.com/pycqa/isort/blob/main/isort/core.py"
    click Output "https://github.com/pycqa/isort/blob/main/isort/output.py"
    click IO "https://github.com/pycqa/isort/blob/main/isort/io.py"
    click Hooks "https://github.com/pycqa/isort/blob/main/isort/hooks.py"
    click Hooks "https://github.com/pycqa/isort/blob/main/isort/setuptools_commands.py"
    click Plugins "https://github.com/pycqa/isort/blob/main/example_isort_formatting_plugin/example_isort_formatting_plugin.py"
    click Plugins "https://github.com/pycqa/isort/blob/main/example_isort_sorting_plugin/example_isort_sorting_plugin.py"
    click Plugins "https://github.com/pycqa/isort/blob/main/example_shared_isort_profile/example_shared_isort_profile.py"
    click Docs "https://github.com/pycqa/isort/tree/main/scripts/"
    click Docs "https://github.com/pycqa/isort/blob/main/mkdocs.yml"
    click Docs "https://github.com/pycqa/isort/tree/main/docs/"
    click Tests "https://github.com/pycqa/isort/tree/main/tests/unit/"
    click Tests "https://github.com/pycqa/isort/tree/main/tests/integration/"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366d6,stroke-width:2px
    classDef config fill:#E6F9E6,stroke:#28a745,stroke-width:2px
    classDef io fill:#FFF5E5,stroke:#d58512,stroke-width:2px
    classDef integration fill:#F0E6FF,stroke:#6f42c1,stroke-width:2px
    classDef tool fill:#F5F5F5,stroke:#6c757d,stroke-width:2px
```
