How pycqa/isort works
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