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, Category] = <factory>, categories: Sequence[Category] = ('future', 'standard_library', 'third_party', 'first_party'), default_category: <function NewType.<locals>.new_type at 0x7fceae72bc10> = 'third_party', side_effect_modules: List[str] = <factory>, side_effect_re: Pattern[str] = re.compile(''), first_party_detection: bool = True, magic_commas: bool = False, 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
magic_commas: bool = False
merge_imports: bool = True
side_effect_modules: List[str]
side_effect_re: Pattern[str] = re.compile('')
usort.util.enable_libcst_native() → bool

Attempt to enable LibCST’s faster, native PEG parser if available.

This enables parsing files with 3.10 match statements, or other new syntax features dependent on having a PEG style parser. This is currently not the default parser in LibCST, so this function must be called before parsing files with 3.10+ syntax, or otherwise set the environment variable LIBCST_PARSER_TYPE="native".

Returns True if the native parser was found and enabled, or False otherwise.