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 configuredexcludes
patterns in the associatedpyproject.toml
.
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.
- 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.
- 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.
- default_category: Category = 'third_party'¶
- 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, orFalse
otherwise.