Implementation:Huggingface Diffusers Custom Init Isort

Knowledge Sources	Huggingface_Diffusers
Domains	Code_Quality, Build_System, Tooling
Last Updated	2026-02-13 21:00 GMT

Overview

Concrete tool for sorting import entries within the lazy `_import_structure` dictionaries in diffusers `__init__.py` files provided by the diffusers code quality toolchain.

Description

The custom_init_isort.py utility handles a specialized sorting problem: the diffusers library uses lazy-loading init files where a dictionary `_import_structure` maps module names to lists of exported objects. Standard tools like `isort` or `ruff` handle the `TYPE_CHECKING` import block but cannot sort the `_import_structure` dictionary entries. This script parses the init files, identifies the `_import_structure` blocks, splits them into indentation-based blocks, sorts both the module keys and the objects within each module alphabetically, and rewrites the file. It supports both direct dictionary syntax (`"key": [...]`) and indirect assignment syntax (`_import_structure["key"]`).

Usage

Run this script from the repository root as part of `make style` for auto-fixing or `make quality` for check-only mode. Use it whenever modifying `__init__.py` files that contain `_import_structure` dictionaries to maintain consistent import ordering.

Code Reference

Source Location

• Repository: Huggingface_Diffusers
• File: utils/custom_init_isort.py
• Lines: 1-330

Signature

def get_indent(line: str) -> str:
    """Returns the indent in given line (as string)."""
    ...

def split_code_in_indented_blocks(
    code: str,
    indent_level: str = "",
    start_prompt: str | None = None,
    end_prompt: str | None = None,
) -> List[str]:
    """Split code into indented blocks at a given level."""
    ...

def sort_objects(objects: List[Any], key: Callable | None = None) -> List[Any]:
    """Sort a list of objects, handling case-insensitive string sorting."""
    ...

def sort_objects_in_import(import_block: str) -> str:
    """Sort the objects inside an import block (the values in _import_structure)."""
    ...

def sort_imports(file: str, check_only: bool = True) -> bool | None:
    """Sort the imports in a single __init__.py file."""
    ...

def sort_imports_in_all_inits(check_only: bool = True):
    """Sort imports in all __init__.py files under src/diffusers."""
    ...

Import

# CLI script — not imported as a module:
# python utils/custom_init_isort.py
# python utils/custom_init_isort.py --check_only

I/O Contract

Inputs

Name	Type	Required	Description
PATH_TO_TRANSFORMERS	str	Yes	Root path to scan for `__init__.py` files (default: `src/diffusers`)
check_only	bool	No	If True, report unsorted files without modifying them (default: True)

Outputs

Name	Type	Description
Modified files	Files	`__init__.py` files rewritten with sorted `_import_structure` entries
ValueError	Exception	Raised in check_only mode if any files would need sorting

Usage Examples

Check Only (CI Quality Gate)

# Check if all init files have sorted imports (exits non-zero if not)
python utils/custom_init_isort.py --check_only

Auto-fix Sorting

# Sort all init imports in place
python utils/custom_init_isort.py

# Or via Makefile
make style

Related Pages

• Environment:Huggingface_Diffusers_PyTorch_CUDA_Runtime