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, mode: black.Mode) → 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_split_after_delimiter(leaf: blib2to3.pytree.Leaf, previous: Union[blib2to3.pytree.Leaf, NoneType] = 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: Union[blib2to3.pytree.Leaf, NoneType] = 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, *, fast: bool, mode: black.Mode) → 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. mode is passed to format_str().

black.format_file_in_place(src: pathlib.Path, fast: bool, mode: black.Mode, write_back: black.WriteBack = <WriteBack.NO: 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. mode and fast options are passed to format_file_contents().

black.format_stdin_to_stdout(fast: bool, *, write_back: black.WriteBack = <WriteBack.NO: 0>, mode: black.Mode) → 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. The mode argument is passed to format_file_contents().

black.format_str(src_contents: str, *, mode: black.Mode) → str¶

Reformat a string and return new contents.

mode determines formatting options, such as how many characters per line are allowed. Example:

>>> import black
>>> print(black.format_str("def f(arg:str='')->None:...", mode=Mode()))
def f(arg: str = "") -> None:
    ...

A more complex example: >>> print( … black.format_str( … “def f(arg:str=’‘)->None: hey”, … mode=black.Mode( … target_versions={black.TargetVersion.PY36}, … line_length=10, … string_normalization=False, … is_pyi=False, … ), … ), … ) def f(

arg: str = ‘’,

) -> None:: hey

black.reformat_one(src: pathlib.Path, fast: bool, write_back: black.WriteBack, mode: black.Mode, report: black.Report) → None¶

Reformat a single file under src without spawning child processes.

fast, write_back, and mode options are passed to format_file_in_place() or format_stdin_to_stdout().

black.schedule_formatting(sources: Set[pathlib.Path], fast: bool, write_back: black.WriteBack, mode: black.Mode, report: black.Report, loop: asyncio.events.AbstractEventLoop, executor: concurrent.futures._base.Executor) → None¶

Run formatting of sources in parallel using the provided executor.

(Use ProcessPoolExecutors for actual parallelism.)

write_back, fast, and mode 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(paths: Iterable[pathlib.Path], root: pathlib.Path, include: Union[Pattern[str], NoneType], exclude_regexes: Iterable[Pattern[str]], report: black.Report, gitignore: pathspec.pathspec.PathSpec) → 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, NoneType]) → Union[str, NoneType]¶

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, target_versions: Iterable[black.TargetVersion] = ()) → 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, features: Collection[black.Feature] = ()) → Iterator[black.Line]¶

Split according to delimiters of the highest priority.

If the appropriate Features are given, the split will add trailing commas also in function signatures and calls that contain * and **.

black.left_hand_split(line: black.Line, _features: Collection[black.Feature] = ()) → 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, features: Collection[black.Feature] = (), 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, features: Collection[black.Feature] = ()) → Iterator[black.Line]¶: Split standalone comments from the rest of the line.

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(mode: black.Mode) → 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(mode: black.Mode) → 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], mode: black.Mode) → 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()¶: 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, NoneType]¶: 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()¶

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) → str¶: Formats a float string like “1.0”.

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

Make sure parentheses are visible.

They could be invisible as part of some statements (see normalize_invisible_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.is_fmt_on(container: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) → bool¶: Determine whether formatting is switched on within a container. Determined by whether the last # fmt: comment is on or off.

black.contains_fmt_on_at_column(container: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node], column: int) → bool¶: Determine if children at a given column have formatting switched on.

black.first_leaf_column(node: blib2to3.pytree.Node) → Union[int, NoneType]¶: Returns the column of the first leaf child of a node.

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], parent: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node]) → bool¶

If it’s safe, make the parens in the atom node invisible, recursively. Additionally, remove repeated, adjacent invisible parens from the atom node as they are redundant.

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) → None¶

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

All letters used in the representation are normalized to lowercase (except in Python 2 long literals).

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 immediately 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, NoneType]) → Union[blib2to3.pytree.Leaf, NoneType]¶: 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.events.AbstractEventLoop) → 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.

Navigation

Related Topics

This Page