.isort.cfg

# =============================================================================
# isort Configuration
# =============================================================================
#
# isort: Python import sorter and organizer
# Documentation: https://pycqa.github.io/isort/
#
# -----------------------------------------------------------------------------
# Usage
# -----------------------------------------------------------------------------
#
#   Check imports:
#     poetry run isort --check-only src/
#
#   Fix imports:
#     poetry run isort src/
#
#   Preview changes:
#     poetry run isort --diff src/
#
#   Single file:
#     poetry run isort src/swing/package/module.py
#
# -----------------------------------------------------------------------------
# Multi-line Output Modes (multi_line_output)
# -----------------------------------------------------------------------------
#
#   0 = Vertical Hanging Indent (single line if fits, otherwise vertical)
#   1 = Vertical (one import per line, all indented)
#   2 = Hanging Indent (continuation lines indented)
#   3 = Vertical Hanging Indent + Trailing Comma [BLACK COMPATIBLE]
#   4 = Vertical (hanging indent from parenthesis)
#   5 = Vertical Grid Grouped (grouped from statement, hanging after)
#
# =============================================================================


[settings]


# =============================================================================
# Black Compatibility
# =============================================================================
#
# Using `profile = black` enables Black-compatible formatting.
# This sets: multi_line_output=3, include_trailing_comma=True,
# force_grid_wrap=0, use_parentheses=True, line_length=88.
# We override line_length to match our PEP 8 preference (79 chars).
#
# -----------------------------------------------------------------------------

profile                         = black
line_length                     = 79


# =============================================================================
# Multi-line Formatting
# =============================================================================
#
# multi_line_output = 3:
#   from package import (
#       first,
#       second,
#       third,
#   )
#
# include_trailing_comma:   Always add trailing comma for cleaner diffs
# force_grid_wrap = 0:      Only wrap when exceeds line_length
# use_parentheses:          Use parentheses for line continuation
# split_on_trailing_comma:  Honor trailing commas as wrap hints
#
# -----------------------------------------------------------------------------

multi_line_output               = 3
include_trailing_comma          = true
force_grid_wrap                 = 0
use_parentheses                 = true
split_on_trailing_comma         = true


# =============================================================================
# Comments & Whitespace
# =============================================================================
#
# ensure_newline_before_comments: Blank line before inline comments
#
# -----------------------------------------------------------------------------

ensure_newline_before_comments  = true


# =============================================================================
# Skip Patterns
# =============================================================================
#
# skip_gitignore:   Respect .gitignore patterns
# skip:             Directories to always skip (build artifacts, caches, etc.)
# extend_skip:      Additional files to skip beyond defaults
# extend_skip_glob: Glob patterns for additional skipping
#
# -----------------------------------------------------------------------------

skip_gitignore                  = true

skip = .eggs,.git,.hg,.mypy_cache,.nox,.tox,.venv,venv,_build,buck-out,build,dist,public,htmlcov,site,node_modules,bup,wip,tmp,migrations,vendor

extend_skip                     = conftest.py
extend_skip_glob                = **/fixtures/*


# =============================================================================
# Import Classification & Sections
# =============================================================================
#
# isort groups imports into sections. The default order is:
#   FUTURE → STDLIB → THIRDPARTY → FIRSTPARTY → LOCALFOLDER
#
# We add DJANGO as a custom section between STDLIB and THIRDPARTY.
#
# known_first_party:  Packages that belong to this project
# known_third_party:  Override detection for specific packages
#
# Note: `swing` covers all swing.* namespace packages (portable).
#
# -----------------------------------------------------------------------------

known_first_party               = swing
known_third_party               = celery,rest_framework

# Define Django section (required when DJANGO is in sections)
known_django                    = django

sections                        = FUTURE,STDLIB,DJANGO,THIRDPARTY,FIRSTPARTY,LOCALFOLDER


# =============================================================================
# Section Headers (Optional)
# =============================================================================
#
# Add comment headers above each import section for visual organization.
# Uncomment import_heading_firstparty to label your package imports.
#
# Example output:
#
#   # Import | Future
#   from __future__ import annotations
#
#   # Import | Standard Library
#   import os
#   from pathlib import Path
#
#   # Import | Libraries
#   import requests
#
# -----------------------------------------------------------------------------

import_heading_future           = Import | Future
import_heading_stdlib           = Import | Standard Library
import_heading_thirdparty       = Import | Libraries
import_heading_localfolder      = Import | Local

; Uncomment for section headers on Django and first-party imports:
; import_heading_django         = Import | Django
; import_heading_firstparty     = Import | Package


# =============================================================================
# Sorting Behavior
# =============================================================================
#
# force_alphabetical_sort_within_sections:
#   Sort imports alphabetically within each section
#
# force_sort_within_sections:
#   Sort by module regardless of import type (import vs from)
#
# honor_noqa:
#   Respect `# noqa` and `# isort:skip` comments
#
# atomic:
#   Only write files if no syntax errors are introduced
#
# remove_redundant_aliases:
#   Remove `import foo as foo` redundancies
#
# group_by_package:
#   Group imports from the same package together
#
# float_to_top:
#   Move imports to the top of the file (after module docstring)
#
# -----------------------------------------------------------------------------

force_alphabetical_sort_within_sections = true
force_sort_within_sections      = true
honor_noqa                      = true
atomic                          = true
remove_redundant_aliases        = true
group_by_package                = true
float_to_top                    = true


# =============================================================================
# Source Discovery
# =============================================================================
#
# src_paths: Where to look for first-party modules
#
# -----------------------------------------------------------------------------

src_paths                       = src


# =============================================================================
# Output & Debugging
# =============================================================================
#
# color_output: Colorize terminal output for readability
#
# Note: show_diff is deprecated in isort 5.x, use --diff CLI flag instead
#
# -----------------------------------------------------------------------------

color_output                    = true