Black classes

Contents are subject to change.


class black.brackets.BracketTracker(depth: int = 0, bracket_match: Dict[Tuple[int, int], blib2to3.pytree.Leaf] = <factory>, delimiters: Dict[int, int] = <factory>, previous: Optional[blib2to3.pytree.Leaf] = None, _for_loop_depths: List[int] = <factory>, _lambda_argument_depths: List[int] = <factory>, invisible: List[blib2to3.pytree.Leaf] = <factory>)

Keeps track of brackets on a line.

mark(leaf: blib2to3.pytree.Leaf)None

Mark leaf with bracket-related metadata. Keep track of delimiters.

All leaves receive an int bracket_depth field that stores how deep within brackets a given leaf is. 0 means there are no enclosing brackets that started on this line.

If a leaf is itself a closing bracket, it receives an opening_bracket field that it forms a pair with. This is a one-directional link to avoid reference cycles.

If a leaf is a delimiter (a token on which Black can split the line if needed) and it’s on depth 0, its id() is stored in the tracker’s delimiters field.


Return True if there is an yet unmatched open bracket on the line.

max_delimiter_priority(exclude: Iterable[int] = ())int

Return the highest priority of a delimiter found on the line.

Values are consistent with what is_split_*_delimiter() return. Raises ValueError on no delimiters.

delimiter_count_with_priority(priority: int = 0)int

Return the number of delimiters with the given priority.

If no priority is passed, defaults to max priority on the line.

maybe_increment_for_loop_variable(leaf: blib2to3.pytree.Leaf)bool

In a for loop, or comprehension, the variables are often unpacks.

To avoid splitting on the comma in this situation, increase the depth of tokens between for and in.

maybe_decrement_after_for_loop_variable(leaf: blib2to3.pytree.Leaf)bool

See maybe_increment_for_loop_variable above for explanation.

maybe_increment_lambda_arguments(leaf: blib2to3.pytree.Leaf)bool

In a lambda expression, there might be more than one argument.

To avoid splitting on the comma in this situation, increase the depth of tokens between lambda and :.

maybe_decrement_after_lambda_arguments(leaf: blib2to3.pytree.Leaf)bool

See maybe_increment_lambda_arguments above for explanation.


Return the most recent opening square bracket (if any).


class black.EmptyLineTracker(is_pyi: bool = False, previous_line: Optional[black.lines.Line] = None, previous_after: int = 0, previous_defs: List[int] = <factory>)

Provides a stateful method that returns the number of potential extra empty lines needed before and after the currently processed line.

Note: this tracker works on lines that haven’t been split yet. It assumes the prefix of the first leaf consists of optional newlines. Those newlines are consumed by maybe_empty_lines() and included in the computation.

maybe_empty_lines(current_line: black.lines.Line)Tuple[int, int]

Return the number of extra empty lines before and after the current_line.

This is for separating def, async def and class with extra empty lines (two on module-level).


class black.Line(mode: black.mode.Mode, depth: int = 0, leaves: List[blib2to3.pytree.Leaf] = <factory>, comments: Dict[int, List[blib2to3.pytree.Leaf]] = <factory>, bracket_tracker: black.brackets.BracketTracker = <factory>, inside_brackets: bool = False, should_split_rhs: bool = False, magic_trailing_comma: Optional[blib2to3.pytree.Leaf] = None)

Holds leaves and comments. Can be printed with str(line).

append(leaf: blib2to3.pytree.Leaf, preformatted: bool = False)None

Add a new leaf to the end of the line.

Unless preformatted is True, the leaf will receive a new consistent whitespace prefix and metadata applied by BracketTracker. Trailing commas are maybe removed, unpacked for loop variables are demoted from being delimiters.

Inline comments are put aside.

append_safe(leaf: blib2to3.pytree.Leaf, preformatted: bool = False)None

Like append() but disallow invalid standalone comment structure.

Raises ValueError when any leaf is appended after a standalone comment or when a standalone comment is not the first leaf on the line.

property is_comment

Is this line a standalone comment?

property is_decorator

Is this line a decorator?

property is_import

Is this an import line?

property is_class

Is this line a class definition?

property is_stub_class

Is this line a class definition with a body consisting only of “…”?

property is_def

Is this a function definition? (Also returns True for async defs.)

property is_class_paren_empty

Is this a class with no base classes but using parentheses?

Those are unnecessary and should be removed.

property is_triple_quoted_string

Is the line a triple quoted string?

contains_standalone_comments(depth_limit: int = 9223372036854775807)bool

If so, needs to be split before emitting.

has_magic_trailing_comma(closing: blib2to3.pytree.Leaf, ensure_removable: bool = False)bool

Return True if we have a magic trailing comma, that is when: - there’s a trailing comma here - it’s not a one-tuple Additionally, if ensure_removable: - it’s not from square bracket indexing

append_comment(comment: blib2to3.pytree.Leaf)bool

Add an inline or standalone comment to the line.

comments_after(leaf: blib2to3.pytree.Leaf)List[blib2to3.pytree.Leaf]

Generate comments that should appear directly after leaf.


Remove the trailing comma and moves the comments attached to it.

is_complex_subscript(leaf: blib2to3.pytree.Leaf)bool

Return True iff leaf is part of a slice with non-trivial exprs.

enumerate_with_length(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.


Render the line.


Return True if the line has leaves or comments.


class black.LineGenerator(mode: black.mode.Mode, remove_u_prefix: bool = False)

Bases: black.nodes.Visitor[black.lines.Line]

Generates reformatted Line objects. Empty lines are not emitted.

Note: destroys the tree it’s visiting by mutating prefixes of its leaves in ways that will no longer stringify to valid Python code on the tree.

line(indent: int = 0)Iterator[black.lines.Line]

Generate a line.

If the line is empty, only emit if it makes sense. If the line is too long, split it first and then generate.

If any lines were generated, set up a new current_line.

visit_default(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node])Iterator[black.lines.Line]

Default visit_*() implementation. Recurses to children of node.

visit_INDENT(node: blib2to3.pytree.Leaf)Iterator[black.lines.Line]

Increase indentation level, maybe yield a line.

visit_DEDENT(node: blib2to3.pytree.Leaf)Iterator[black.lines.Line]

Decrease indentation level, maybe yield a line.

visit_stmt(node: blib2to3.pytree.Node, keywords: Set[str], parens: Set[str])Iterator[black.lines.Line]

Visit a statement.

This implementation is shared for if, while, for, try, except, def, with, class, assert and assignments.

The relevant Python language keywords for a given statement will be NAME leaves within it. This methods puts those on a separate line.

parens holds a set of string leaf values immediately after which invisible parens should be put.

visit_suite(node: blib2to3.pytree.Node)Iterator[black.lines.Line]

Visit a suite.

visit_simple_stmt(node: blib2to3.pytree.Node)Iterator[black.lines.Line]

Visit a statement without nested statements.

visit_async_stmt(node: blib2to3.pytree.Node)Iterator[black.lines.Line]

Visit async def, async for, async with.

visit_decorators(node: blib2to3.pytree.Node)Iterator[black.lines.Line]

Visit decorators.

visit_SEMI(leaf: blib2to3.pytree.Leaf)Iterator[black.lines.Line]

Remove a semicolon and put the other statement on a separate line.

visit_ENDMARKER(leaf: blib2to3.pytree.Leaf)Iterator[black.lines.Line]

End of file. Process outstanding comments and end with a newline.

visit_factor(node: blib2to3.pytree.Node)Iterator[black.lines.Line]

Force parentheses between a unary op and a binary power:

-2 ** 8 -> -(2 ** 8)


class black.comments.ProtoComment(type: int, value: str, newlines: int, consumed: int)

Describes a piece of syntax that is a comment.

It’s not a blib2to3.pytree.Leaf so that:

  • it can be cached (Leaf objects should not be reused more than once as they store their lineno, column, prefix, and parent information);

  • newlines and consumed fields are kept separate from the value. This simplifies handling of special marker comments like # fmt: off/on.


class black.Report(check: bool = False, diff: bool = False, quiet: bool = False, verbose: bool = False, change_count: int = 0, same_count: int = 0, failure_count: int = 0)

Provides a reformatting counter. Can be rendered with str(report).

done(src: pathlib.Path, changed:

Increment the counter for successful reformatting. Write out a message.

failed(src: pathlib.Path, message: str)None

Increment the counter for failed reformatting. Write out a message.

property return_code

Return the exit code that the app should use.

This considers the current state of changed files and failures: - if there were any failures, return 123; - if any files were changed and –check is being used, return 1; - otherwise return 0.


Render a color report of the current state.

Use click.unstyle to remove colors.


class black.nodes.Visitor(*args, **kwds)

Bases: Generic[black.nodes.T]

Basic lib2to3 visitor that yields things of type T on visit().

visit(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node])Iterator[T]

Main method to visit node and its children.

It tries to find a visit_*() method for the given node.type, like visit_simple_stmt for Node objects or visit_INDENT for Leaf objects. If no dedicated visit_*() method is found, chooses visit_default() instead.

Then yields objects of type T from the selected visitor.

visit_default(node: Union[blib2to3.pytree.Leaf, blib2to3.pytree.Node])Iterator[T]

Default visit_*() implementation. Recurses to children of node.



class black.Changed(value)

Bases: enum.Enum

An enumeration.


class black.Mode(target_versions: Set[black.mode.TargetVersion] = <factory>, line_length: int = 88, string_normalization: bool = True, is_pyi: bool = False, magic_trailing_comma: bool = True, experimental_string_processing: bool = False)

Bases: object


class black.WriteBack(value)

Bases: enum.Enum

An enumeration.