Black functions

Contents are subject to change.

Assertions and checks

black.assert_equivalent(src: str, dst: str) → None

Raise AssertionError if src and dst aren’t equivalent.

black.assert_stable(src: str, dst: str, line_length: int, mode: black.FileMode = <FileMode.AUTO_DETECT: 0>) → None

Raise AssertionError if dst reformats differently the second time.

black.can_be_split(line: black.Line) → bool

Return False if the line cannot be split for sure.

This is not an exhaustive search but a cheap heuristic that we can use to avoid some unfortunate formattings (mostly around wrapping unsplittable code in unnecessary parentheses).

black.can_omit_invisible_parens(line: black.Line, line_length: int) → bool

Does line have a shape safe to reformat without optional parens around it?

Returns True for only a subset of potentially nice looking formattings but the point is to not return false positives that end up producing lines that are too long.

black.is_empty_tuple(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) → bool

Return True if node holds an empty tuple.

black.is_import(leaf: blib2to3.pytree.Leaf) → bool

Return True if the given leaf starts an import statement.

black.is_line_short_enough(line: black.Line, *, line_length: int, line_str: str = '') → bool

Return True if line is no longer than line_length.

Uses the provided line_str rendering, if any, otherwise computes a new one.

black.is_multiline_string(leaf: blib2to3.pytree.Leaf) → bool

Return True if leaf is a multiline string that actually spans many lines.

black.is_one_tuple(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) → bool

Return True if node holds a tuple with one element, with or without parens.

black.is_python36(node: blib2to3.pytree.Node) → bool

Return True if the current file is using Python 3.6+ features.

Currently looking for: - f-strings; - underscores in numeric literals; and - trailing commas after * or ** in function signatures and calls.

black.is_split_after_delimiter(leaf: blib2to3.pytree.Leaf, previous: blib2to3.pytree.Leaf = None) → int

Return the priority of the leaf delimiter, given a line break after it.

The delimiter priorities returned here are from those delimiters that would cause a line break after themselves.

Higher numbers are higher priority.

black.is_split_before_delimiter(leaf: blib2to3.pytree.Leaf, previous: blib2to3.pytree.Leaf = None) → int

Return the priority of the leaf delimiter, given a line break before it.

The delimiter priorities returned here are from those delimiters that would cause a line break before themselves.

Higher numbers are higher priority.

black.is_stub_body(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) → bool

Return True if node is a simple statement containing an ellipsis.

black.is_stub_suite(node: blib2to3.pytree.Node) → bool

Return True if node is a suite with a stub body.

black.is_vararg(leaf: blib2to3.pytree.Leaf, within: Set[int]) → bool

Return True if leaf is a star or double star in a vararg or kwarg.

If within includes VARARGS_PARENTS, this applies to function signatures. If within includes UNPACKING_PARENTS, it applies to right hand-side extended iterable unpacking (PEP 3132) and additional unpacking generalizations (PEP 448).

black.is_yield(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) → bool

Return True if node holds a yield or yield from expression.

Formatting

black.format_file_contents(src_contents: str, *, line_length: int, fast: bool, mode: black.FileMode = <FileMode.AUTO_DETECT: 0>) → str

Reformat contents a file and return new contents.

If fast is False, additionally confirm that the reformatted code is valid by calling assert_equivalent() and assert_stable() on it. line_length is passed to format_str().

black.format_file_in_place(src: pathlib.Path, line_length: int, fast: bool, write_back: black.WriteBack = <WriteBack.NO: 0>, mode: black.FileMode = <FileMode.AUTO_DETECT: 0>, lock: Any = None) → bool

Format file under src path. Return True if changed.

If write_back is DIFF, write a diff to stdout. If it is YES, write reformatted code to the file. line_length and fast options are passed to format_file_contents().

black.format_stdin_to_stdout(line_length: int, fast: bool, write_back: black.WriteBack = <WriteBack.NO: 0>, mode: black.FileMode = <FileMode.AUTO_DETECT: 0>) → bool

Format file on stdin. Return True if changed.

If write_back is YES, write reformatted code back to stdout. If it is DIFF, write a diff to stdout. line_length, fast, is_pyi, and force_py36 arguments are passed to format_file_contents().

black.format_str(src_contents: str, line_length: int, *, mode: black.FileMode = <FileMode.AUTO_DETECT: 0>) → str

Reformat a string and return new contents.

line_length determines how many characters per line are allowed.

black.reformat_one(src: pathlib.Path, line_length: int, fast: bool, write_back: black.WriteBack, mode: black.FileMode, report: black.Report) → None

Reformat a single file under src without spawning child processes.

If quiet is True, non-error messages are not output. line_length, write_back, fast and pyi options are passed to format_file_in_place() or format_stdin_to_stdout().

black.schedule_formatting(sources: Set[pathlib.Path], line_length: int, fast: bool, write_back: black.WriteBack, mode: black.FileMode, report: black.Report, loop: asyncio.base_events.BaseEventLoop, executor: concurrent.futures._base.Executor) → None

Run formatting of sources in parallel using the provided executor.

(Use ProcessPoolExecutors for actual parallelism.)

line_length, write_back, fast, and pyi options are passed to format_file_in_place().

File operations

black.dump_to_file(*output) → str

Dump output to a temporary file. Return path to the file.

black.find_project_root()

Return a directory containing .git, .hg, or pyproject.toml.

That directory can be one of the directories passed in srcs or their common parent.

If no directory in the tree contains a marker that would specify it’s the project root, the root of the file system is returned.

black.gen_python_files_in_dir(path: pathlib.Path, root: pathlib.Path, include: Pattern[str], exclude: Pattern[str], report: black.Report) → Iterator[pathlib.Path]

Generate all files under path whose paths are not excluded by the exclude regex, but are included by the include regex.

Symbolic links pointing outside of the root directory are ignored.

report is where output about exclusions goes.

black.read_pyproject_toml(ctx: click.core.Context, param: click.core.Parameter, value: Union[str, int, None]) → Optional[str]

Inject Black configuration from “pyproject.toml” into defaults in ctx.

Returns the path to a successfully found and read configuration file, None otherwise.

Parsing

black.decode_bytes(src: bytes) → Tuple[str, str, str]

Return a tuple of (decoded_contents, encoding, newline).

newline is either CRLF or LF but decoded_contents is decoded with universal newlines (i.e. only contains LF).

black.lib2to3_parse(src_txt: str) → blib2to3.pytree.Node

Given a string with source, return the lib2to3 Node.

black.lib2to3_unparse(node: blib2to3.pytree.Node) → str

Given a lib2to3 node, return its string representation.

Split functions

black.bracket_split_build_line(leaves: List[blib2to3.pytree.Leaf], original: black.Line, opening_bracket: blib2to3.pytree.Leaf, *, is_body: bool = False) → black.Line

Return a new line with given leaves and respective comments from original.

If is_body is True, the result line is one-indented inside brackets and as such has its first leaf’s prefix normalized and a trailing comma added when expected.

black.bracket_split_succeeded_or_raise(head: black.Line, body: black.Line, tail: black.Line) → None

Raise CannotSplit if the last left- or right-hand split failed.

Do nothing otherwise.

A left- or right-hand split is based on a pair of brackets. Content before (and including) the opening bracket is left on one line, content inside the brackets is put on a separate line, and finally content starting with and following the closing bracket is put on a separate line.

Those are called head, body, and tail, respectively. If the split produced the same line (all content in head) or ended up with an empty body and the tail is just the closing bracket, then it’s considered failed.

black.delimiter_split(line: black.Line, py36: bool = False) → Iterator[black.Line]

Split according to delimiters of the highest priority.

If py36 is True, the split will add trailing commas also in function signatures that contain * and **.

black.left_hand_split(line: black.Line, py36: bool = False) → Iterator[black.Line]

Split line into many lines, starting with the first matching bracket pair.

Note: this usually looks weird, only use this for function definitions. Prefer RHS otherwise. This is why this function is not symmetrical with right_hand_split() which also handles optional parentheses.

black.right_hand_split(line: black.Line, line_length: int, py36: bool = False, omit: Collection[int] = ()) → Iterator[black.Line]

Split line into many lines, starting with the last matching bracket pair.

If the split was by optional parentheses, attempt splitting without them, too. omit is a collection of closing bracket IDs that shouldn’t be considered for this split.

Note: running this function modifies bracket_depth on the leaves of line.

black.standalone_comment_split(line: black.Line, py36: bool = False) → Iterator[black.Line]

Split standalone comments from the rest of the line.

black.split_line(line: black.Line, line_length: int, inner: bool = False, py36: bool = False) → Iterator[black.Line]

Split a line into potentially many lines.

They should fit in the allotted line_length but might not be able to. inner signifies that there were a pair of brackets somewhere around the current line, possibly transitively. This means we can fallback to splitting by delimiters if the LHS/RHS don’t yield any results.

If py36 is True, splitting may generate syntax that is only compatible with Python 3.6 and later.

Caching

black.filter_cached(cache: Dict[pathlib.Path, Tuple[float, int]], sources: Iterable[pathlib.Path]) → Tuple[Set[pathlib.Path], Set[pathlib.Path]]

Split an iterable of paths in sources into two sets.

The first contains paths of files that modified on disk or are not in the cache. The other contains paths to non-modified files.

black.get_cache_file(line_length: int, mode: black.FileMode) → pathlib.Path
black.get_cache_info(path: pathlib.Path) → Tuple[float, int]

Return the information used to check if a file is already formatted or not.

black.read_cache(line_length: int, mode: black.FileMode) → Dict[pathlib.Path, Tuple[float, int]]

Read the cache if it exists and is well formed.

If it is not well formed, the call to write_cache later should resolve the issue.

black.write_cache(cache: Dict[pathlib.Path, Tuple[float, int]], sources: Iterable[pathlib.Path], line_length: int, mode: black.FileMode) → None

Update the cache file.

Utilities

black.DebugVisitor.show(code: str) → None

Pretty-print the lib2to3 AST of a given string of code.

black.cancel(tasks: Iterable[_asyncio.Task]) → None

asyncio signal handler that cancels all tasks and reports to stderr.

black.child_towards(ancestor: blib2to3.pytree.Node, descendant: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) → Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node, None]

Return the child of ancestor that contains descendant.

black.container_of(leaf: blib2to3.pytree.Leaf) → Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]

Return leaf or one of its ancestors that is the topmost container of it.

By “container” we mean a node where leaf is the very first child.

black.convert_one_fmt_off_pair(node: blib2to3.pytree.Node) → bool

Convert content of a single # fmt: off/# fmt: on into a standalone comment.

Returns True if a pair was converted.

black.diff(a: str, b: str, a_name: str, b_name: str) → str

Return a unified diff string between strings a and b.

black.dont_increase_indentation(split_func: Callable[[Line, bool], Iterator[Line]]) → Callable[[black.Line, bool], Iterator[black.Line]]

Normalize prefix of the first leaf in every line returned by split_func.

This is a decorator over relevant split functions.

black.format_float_or_int_string(text: str, allow_underscores: bool) → str

Formats a float string like “1.0”.

black.format_int_string(text: str, allow_underscores: bool, count_from_end: bool = True) → str

Normalizes underscores in a string to e.g. 1_000_000.

Input must be a string of digits and optional underscores. If count_from_end is False, we add underscores after groups of three digits counting from the beginning instead of the end of the strings. This is used for the fractional part of float literals.

black.ensure_visible(leaf: blib2to3.pytree.Leaf) → None

Make sure parentheses are visible.

They could be invisible as part of some statements (see normalize_invible_parens() and visit_import_from()).

black.enumerate_reversed(sequence: Sequence[T]) → Iterator[Tuple[int, T]]

Like reversed(enumerate(sequence)) if that were possible.

black.enumerate_with_length(line: black.Line, reversed: bool = False) → Iterator[Tuple[int, blib2to3.pytree.Leaf, int]]

Return an enumeration of leaves with their length.

Stops prematurely on multiline strings and standalone comments.

black.generate_comments(leaf: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) → Iterator[blib2to3.pytree.Leaf]

Clean the prefix of the leaf and generate comments from it, if any.

Comments in lib2to3 are shoved into the whitespace prefix. This happens in pgen2/driver.py:Driver.parse_tokens(). This was a brilliant implementation move because it does away with modifying the grammar to include all the possible places in which comments can be placed.

The sad consequence for us though is that comments don’t “belong” anywhere. This is why this function generates simple parentless Leaf objects for comments. We simply don’t know what the correct parent should be.

No matter though, we can live without this. We really only need to differentiate between inline and standalone comments. The latter don’t share the line with any code.

Inline comments are emitted as regular token.COMMENT leaves. Standalone are emitted with a fake STANDALONE_COMMENT token identifier.

black.generate_ignored_nodes(leaf: blib2to3.pytree.Leaf) → Iterator[Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]]

Starting from the container of leaf, generate all leaves until # fmt: on.

Stops at the end of the block.

black.generate_trailers_to_omit(line: black.Line, line_length: int) → Iterator[Set[int]]

Generate sets of closing bracket IDs that should be omitted in a RHS.

Brackets can be omitted if the entire trailer up to and including a preceding closing bracket fits in one line.

Yielded sets are cumulative (contain results of previous yields, too). First set is empty.

black.get_future_imports(node: blib2to3.pytree.Node) → Set[str]

Return a set of __future__ imports in the file.

black.list_comments()

Return a list of ProtoComment objects parsed from the given prefix.

black.make_comment(content: str) → str

Return a consistently formatted comment from the given content string.

All comments (except for “##”, “#!”, “#:”, ‘#’”, “#%%”) should have a single space between the hash sign and the content.

If content didn’t start with a hash sign, one is provided.

black.maybe_make_parens_invisible_in_atom(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) → bool

If it’s safe, make the parens in the atom node invisible, recursively.

Returns whether the node should itself be wrapped in invisible parentheses.

black.max_delimiter_priority_in_atom(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) → int

Return maximum delimiter priority inside node.

This is specific to atoms with contents contained in a pair of parentheses. If node isn’t an atom or there are no enclosing parentheses, returns 0.

black.normalize_fmt_off(node: blib2to3.pytree.Node) → None

Convert content between # fmt: off/# fmt: on into standalone comments.

black.normalize_numeric_literal(leaf: blib2to3.pytree.Leaf, allow_underscores: bool) → None

Normalizes numeric (float, int, and complex) literals.

All letters used in the representation are normalized to lowercase (except in Python 2 long literals), and long number literals are split using underscores.

black.normalize_prefix(leaf: blib2to3.pytree.Leaf, *, inside_brackets: bool) → None

Leave existing extra newlines if not inside_brackets. Remove everything else.

Note: don’t use backslashes for formatting or you’ll lose your voting rights.

black.normalize_string_prefix(leaf: blib2to3.pytree.Leaf, remove_u_prefix: bool = False) → None

Make all string prefixes lowercase.

If remove_u_prefix is given, also removes any u prefix from the string.

Note: Mutates its argument.

black.normalize_string_quotes(leaf: blib2to3.pytree.Leaf) → None

Prefer double quotes but only if it doesn’t cause more escaping.

Adds or removes backslashes as appropriate. Doesn’t parse and fix strings nested in f-strings (yet).

Note: Mutates its argument.

black.normalize_invisible_parens(node: blib2to3.pytree.Node, parens_after: Set[str]) → None

Make existing optional parentheses invisible or create new ones.

parens_after is a set of string leaf values immeditely after which parens should be put.

Standardizes on visible parentheses for single-element tuples, and keeps existing visible parentheses for other tuples and generator expressions.

black.patch_click() → None

Make Click not crash.

On certain misconfigured environments, Python 3 selects the ASCII encoding as the default which restricts paths that it can access during the lifetime of the application. Click refuses to work in this scenario by raising a RuntimeError.

In case of Black the likelihood that non-ASCII characters are going to be used in file paths is minimal since it’s Python source code. Moreover, this crash was spurious on Python 3.7 thanks to PEP 538 and PEP 540.

black.preceding_leaf(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node, None]) → Optional[blib2to3.pytree.Leaf]

Return the first leaf that precedes node, if any.

black.re_compile_maybe_verbose(regex: str) → Pattern[str]

Compile a regular expression string in regex.

If it contains newlines, use verbose mode.

black.should_explode(line: black.Line, opening_bracket: blib2to3.pytree.Leaf) → bool

Should line immediately be split with delimiter_split() after RHS?

black.shutdown(loop: asyncio.base_events.BaseEventLoop) → None

Cancel all pending tasks on loop, wait for them, and close the loop.

black.sub_twice(regex: Pattern[str], replacement: str, original: str) → str

Replace regex with replacement twice on original.

This is used by string normalization to perform replaces on overlapping matches.

black.whitespace(leaf: blib2to3.pytree.Leaf, *, complex_subscript: bool) → str

Return whitespace prefix if needed for the given leaf.

complex_subscript signals whether the given leaf is part of a subscription which has non-trivial arguments, like arithmetic expressions or function calls.