API Reference

Simple API

usort.usort_path(paths: Path | Iterable[Path], write: bool = False) → Iterable[Result]

For a given path, format it, or any python files in it, and yield Result s.

If given a directory, it will be searched, recursively, for any Python source files, excluding any files or directories that match the project root’s .gitignore or any configured excludes patterns in the associated pyproject.toml.

class usort.Result(path: Path, content: bytes = b'', output: bytes = b'', encoding: str | None = None, error: Exception | None = None, trace: str = '', timings: Sequence[Tuple[str, float]] = (), warnings: Sequence[SortWarning] = ())

content: bytes

encoding: str | None

error: Exception | None

output: bytes

path: Path

timings: Sequence[Tuple[str, float]]

trace: str

warnings: Sequence[SortWarning]

class usort.SortWarning(line: int, message: str)

line: int

message: str

Advanced API

usort.usort(data: bytes, config: Config, path: Path | None = None) → Result

Given bytes for a module, this parses and sorts imports, and returns a Result.

usort.usort_file(path: Path, *, write: bool = False) → Result

Format a single file and return a Result object.

Ignores any configured excludes patterns.

usort.usort_stdin() → bool

Read file contents from stdin, format it, and write the resulting file to stdout

In case of error during sorting, no output will be written to stdout, and the exception will be written to stderr instead.

Returns True if formatting succeeded, otherwise False

class usort.Config(known: Dict[str, usort.config.Category] = <factory>, categories: Sequence[usort.config.Category] = ('future', 'standard_library', 'third_party', 'first_party'), default_category: usort.config.Category = 'third_party', side_effect_modules: List[str] = <factory>, side_effect_re: Pattern[str] = re.compile(''), first_party_detection: bool = True, merge_imports: bool = True, excludes: List[str] = <factory>, line_length: int = 88)

category(dotted_import: str) → Category

Given a piece of an import string, return its category for this config.

You can pass in “.foo” or “pkg.foo.bar” or just “os” and it should categorize.

classmethod find(filename: Path | None = None, with_first_party: bool = True) → Config

is_side_effect_import(base: str, names: List[str]) → bool

Determine if any of the given imports are in the list with known side effects.

Takes a “base” (possibly empty) and a list of imported names, and checks if any of the base+name combinations (or a prefix of that combination) is in the list of know modules with side effects.

update_from_config(toml_path: Path) → None

with_first_party(filename: Path) → Config

Infer first-party top-level names; this only works for the common case of a single package, but not multiple, or modules (pure-python or extensions). In those cases, you should explicitly set known_first_party in the config.

This code as-is should work for something like running against a site-packages dir, but if we broaden to support multiple top-level names, it would find too much.

To disable this code entirely, set first_party_detection=false in the config.

categories: Sequence[Category] = ('future', 'standard_library', 'third_party', 'first_party')

default_category: Category = 'third_party'

excludes: List[str]

first_party_detection: bool = True

known: Dict[str, Category]

line_length: int = 88

merge_imports: bool = True

side_effect_modules: List[str]

side_effect_re: Pattern[str] = re.compile('')