Black classes¶
Contents are subject to change.
BracketTracker
¶
-
class
black.
BracketTracker
(depth: int = 0, bracket_match: Dict[Tuple[int, int], blib2to3.pytree.Leaf] = <factory>, delimiters: Dict[int, int] = <factory>, previous: Union[blib2to3.pytree.Leaf, NoneType] = None, _for_loop_depths: List[int] = <factory>, _lambda_argument_depths: List[int] = <factory>) → None¶ 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.
-
any_open_brackets
() → bool¶ 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.
-
get_open_lsqb
() → Union[blib2to3.pytree.Leaf, NoneType]¶ Return the most recent opening square bracket (if any).
-
EmptyLineTracker
¶
-
class
black.
EmptyLineTracker
(is_pyi: bool = False, previous_line: Union[black.Line, NoneType] = None, previous_after: int = 0, previous_defs: List[int] = <factory>) → None¶ 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.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).
-
Line
¶
-
class
black.
Line
(depth: int = 0, leaves: List[blib2to3.pytree.Leaf] = <factory>, comments: Dict[int, List[blib2to3.pytree.Leaf]] = <factory>, bracket_tracker: black.BracketTracker = <factory>, inside_brackets: bool = False, should_explode: bool = False) → 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.
-
is_comment
¶ Is this line a standalone comment?
-
is_decorator
¶ Is this line a decorator?
-
is_import
¶ Is this an import line?
-
is_class
¶ Is this line a class definition?
-
is_stub_class
¶ Is this line a class definition with a body consisting only of “…”?
-
is_collection_with_optional_trailing_comma
¶ Is this line a collection literal with a trailing comma that’s optional?
Note that the trailing comma in a 1-tuple is not optional.
-
is_def
¶ Is this a function definition? (Also returns True for async defs.)
-
is_class_paren_empty
¶ Is this a class with no base classes but using parentheses?
Those are unnecessary and should be removed.
-
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.
-
maybe_remove_trailing_comma
(closing: blib2to3.pytree.Leaf) → bool¶ Remove trailing comma if there is one and it’s safe.
-
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_trailing_comma
() → None¶ 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.
-
__str__
() → str¶ Render the line.
-
__bool__
() → bool¶ Return True if the line has leaves or comments.
-
LineGenerator
¶
-
class
black.
LineGenerator
(is_pyi: bool = False, normalize_strings: bool = True, current_line: black.Line = <factory>, remove_u_prefix: bool = False) → None¶ Bases:
black.Visitor
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.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.Line]¶ Default visit_*() implementation. Recurses to children of node.
-
visit_INDENT
(node: blib2to3.pytree.Leaf) → Iterator[black.Line]¶ Increase indentation level, maybe yield a line.
-
visit_DEDENT
(node: blib2to3.pytree.Leaf) → Iterator[black.Line]¶ Decrease indentation level, maybe yield a line.
-
visit_stmt
(node: blib2to3.pytree.Node, keywords: Set[str], parens: Set[str]) → Iterator[black.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.Line]¶ Visit a suite.
-
visit_simple_stmt
(node: blib2to3.pytree.Node) → Iterator[black.Line]¶ Visit a statement without nested statements.
-
visit_async_stmt
(node: blib2to3.pytree.Node) → Iterator[black.Line]¶ Visit async def, async for, async with.
-
visit_decorators
(node: blib2to3.pytree.Node) → Iterator[black.Line]¶ Visit decorators.
-
visit_SEMI
(leaf: blib2to3.pytree.Leaf) → Iterator[black.Line]¶ Remove a semicolon and put the other statement on a separate line.
-
visit_ENDMARKER
(leaf: blib2to3.pytree.Leaf) → Iterator[black.Line]¶ End of file. Process outstanding comments and end with a newline.
-
visit_factor
(node: blib2to3.pytree.Node) → Iterator[black.Line]¶ Force parentheses between a unary op and a binary power:
-2 ** 8 -> -(2 ** 8)
-
ProtoComment
¶
-
class
black.
ProtoComment
(type: int, value: str, newlines: int, consumed: int) → None¶ 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
.
Report
¶
-
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) → None¶ Provides a reformatting counter. Can be rendered with str(report).
-
done
(src: pathlib.Path, changed: black.Changed) → None¶ 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.
-
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.
-
__str__
() → str¶ Render a color report of the current state.
Use click.unstyle to remove colors.
-
Visitor
¶
-
class
black.
Visitor
¶ Bases:
typing.Generic
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.
-