Black classes#
Contents are subject to change.
Black Classes#
BracketTracker#
- class black.brackets.BracketTracker(depth: int = 0, bracket_match: ~typing.Dict[~typing.Tuple[int, int], ~blib2to3.pytree.Leaf] = <factory>, delimiters: ~typing.Dict[int, int] = <factory>, previous: ~blib2to3.pytree.Leaf | None = None, _for_loop_depths: ~typing.List[int] = <factory>, _lambda_argument_depths: ~typing.List[int] = <factory>, invisible: ~typing.List[~blib2to3.pytree.Leaf] = <factory>)#
Keeps track of brackets on a line.
- mark(leaf: 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 and there is a matching opening bracket earlier, it receives an opening_bracket field with which it forms a pair. This is a one-directional link to avoid reference cycles. Closing bracket without opening happens on lines continued from previous breaks, e.g. ) -> “ReturnType”: as part of a funcdef where we place the return type annotation on its own line of the previous closing RPAR.
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.
- 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: 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: Leaf) bool#
See maybe_increment_for_loop_variable above for explanation.
- maybe_increment_lambda_arguments(leaf: 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 :.
Line#
- class black.lines.Line(mode: ~black.mode.Mode, depth: int = 0, leaves: ~typing.List[~blib2to3.pytree.Leaf] = <factory>, comments: ~typing.Dict[int, ~typing.List[~blib2to3.pytree.Leaf]] = <factory>, bracket_tracker: ~black.brackets.BracketTracker = <factory>, inside_brackets: bool = False, should_split_rhs: bool = False, magic_trailing_comma: ~blib2to3.pytree.Leaf | None = None)#
Holds leaves and comments. Can be printed with str(line).
- append(leaf: Leaf, preformatted: bool = False, track_bracket: 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: 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_class_paren_empty: bool#
Is this a class with no base classes but using parentheses?
Those are unnecessary and should be removed.
- is_fmt_pass_converted(*, first_leaf_matches: Callable[[Leaf], bool] | None = None) bool#
Is this line converted from fmt off/skip code?
If first_leaf_matches is not None, it only returns True if the first leaf of converted code matches.
- contains_standalone_comments(depth_limit: int = 9223372036854775807) bool#
If so, needs to be split before emitting.
- has_magic_trailing_comma(closing: 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 - it’s not a single-element subscript Additionally, if ensure_removable: - it’s not from square bracket indexing (specifically, single-element square bracket indexing)
- is_complex_subscript(leaf: Leaf) bool#
Return True iff leaf is part of a slice with non-trivial exprs.
RHSResult#
LinesBlock#
- class black.lines.LinesBlock(mode: ~black.mode.Mode, previous_block: ~black.lines.LinesBlock | None, original_line: ~black.lines.Line, before: int = 0, content_lines: ~typing.List[str] = <factory>, after: int = 0)#
Class that holds information about a block of formatted lines.
This is introduced so that the EmptyLineTracker can look behind the standalone comments and adjust their empty lines for class or def lines.
EmptyLineTracker#
- class black.lines.EmptyLineTracker(mode: ~black.mode.Mode, previous_line: ~black.lines.Line | None = None, previous_block: ~black.lines.LinesBlock | None = None, previous_defs: ~typing.List[~black.lines.Line] = <factory>, semantic_leading_comment: ~black.lines.LinesBlock | None = 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: Line) LinesBlock#
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).
LineGenerator#
- class black.linegen.LineGenerator(mode: Mode, features: Collection[Feature])#
-
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[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: Leaf | Node) Iterator[Line]#
Default visit_*() implementation. Recurses to children of node.
- visit_stmt(node: Node, keywords: Set[str], parens: Set[str]) Iterator[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_SEMI(leaf: Leaf) Iterator[Line]#
Remove a semicolon and put the other statement on a separate line.
ProtoComment#
- 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.Leafso 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.
Mode#
- class black.mode.Mode(target_versions: Set[black.mode.TargetVersion] = <factory>, line_length: int = 88, string_normalization: bool = True, is_pyi: bool = False, is_ipynb: bool = False, skip_source_first_line: bool = False, magic_trailing_comma: bool = True, experimental_string_processing: bool = False, python_cell_magics: Set[str] = <factory>, preview: bool = False)#
Report#
- class black.report.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: Path, changed: Changed) None#
Increment the counter for successful reformatting. Write out a message.
- failed(src: Path, message: str) None#
Increment the counter for failed reformatting. Write out a message.
Ok#
Err#
Visitor#
- class black.nodes.Visitor#
Bases:
Generic[T]Basic lib2to3 visitor that yields things of type T on visit().
- visit(node: Leaf | 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.
StringTransformer#
- class black.trans.StringTransformer(line_length: int, normalize_strings: bool)#
Bases:
ABCAn implementation of the Transformer protocol that relies on its subclasses overriding the template methods do_match(…) and do_transform(…).
This Transformer works exclusively on strings (for example, by merging or splitting them).
The following sections can be found among the docstrings of each concrete StringTransformer subclass.
- Requirements:
Which requirements must be met of the given Line for this StringTransformer to be applied?
- Transformations:
If the given Line meets all of the above requirements, which string transformations can you expect to be applied to it by this StringTransformer?
- Collaborations:
What contractual agreements does this StringTransformer have with other StringTransfomers? Such collaborations should be eliminated/minimized as much as possible.
- abstract do_match(line: Line) Ok[List[int]] | Err[CannotTransform]#
- Returns:
Ok(string_indices) such that for each index, line.leaves[index] is our target string if a match was able to be made. For transformers that don’t result in more lines (e.g. StringMerger, StringParenStripper), multiple matches and transforms are done at once to reduce the complexity. OR
Err(CannotTransform), if no match could be made.
- abstract do_transform(line: Line, string_indices: List[int]) Iterator[Ok[Line] | Err[CannotTransform]]#
- Yields:
Ok(new_line) where new_line is the new transformed line. OR
Err(CannotTransform) if the transformation failed for some reason. The do_match(…) template method should usually be used to reject the form of the given Line, but in some cases it is difficult to know whether or not a Line meets the StringTransformer’s requirements until the transformation is already midway.
- Side Effects:
This method should NOT mutate @line directly, but it MAY mutate the Line’s underlying Node structure. (WARNING: If the underlying Node structure IS altered, then this method should NOT be allowed to yield an CannotTransform after that point.)
CustomSplit#
- class black.trans.CustomSplit(has_prefix: bool, break_idx: int)#
A custom (i.e. manual) string split.
A single CustomSplit instance represents a single substring.
Examples
Consider the following string:
` "Hi there friend." " This is a custom" f" string {split}." `This string will correspond to the following three CustomSplit instances:
` CustomSplit(False, 16) CustomSplit(False, 17) CustomSplit(True, 16) `
CustomSplitMapMixin#
- class black.trans.CustomSplitMapMixin#
Bases:
objectThis mixin class is used to map merged strings to a sequence of CustomSplits, which will then be used to re-split the strings iff none of the resultant substrings go over the configured max line length.
- add_custom_splits(string: str, custom_splits: Iterable[CustomSplit]) None#
Custom Split Map Setter Method
- Side Effects:
Adds a mapping from @string to the custom splits @custom_splits.
- pop_custom_splits(string: str) List[CustomSplit]#
Custom Split Map Getter Method
- Returns:
A list of the custom splits that are mapped to @string, if any exist. OR
[], otherwise.
- Side Effects:
Deletes the mapping between @string and its associated custom splits (which are returned to the caller).
StringMerger#
- class black.trans.StringMerger(line_length: int, normalize_strings: bool)#
Bases:
StringTransformer,CustomSplitMapMixinStringTransformer that merges strings together.
- Requirements:
(A) The line contains adjacent strings such that ALL of the validation checks listed in StringMerger._validate_msg(…)’s docstring pass. OR (B) The line contains a string which uses line continuation backslashes.
- Transformations:
Depending on which of the two requirements above where met, either:
(A) The string group associated with the target string is merged. OR (B) All line-continuation backslashes are removed from the target string.
- Collaborations:
StringMerger provides custom split information to StringSplitter.
- do_match(line: Line) Ok[List[int]] | Err[CannotTransform]#
- Returns:
Ok(string_indices) such that for each index, line.leaves[index] is our target string if a match was able to be made. For transformers that don’t result in more lines (e.g. StringMerger, StringParenStripper), multiple matches and transforms are done at once to reduce the complexity. OR
Err(CannotTransform), if no match could be made.
- do_transform(line: Line, string_indices: List[int]) Iterator[Ok[Line] | Err[CannotTransform]]#
- Yields:
Ok(new_line) where new_line is the new transformed line. OR
Err(CannotTransform) if the transformation failed for some reason. The do_match(…) template method should usually be used to reject the form of the given Line, but in some cases it is difficult to know whether or not a Line meets the StringTransformer’s requirements until the transformation is already midway.
- Side Effects:
This method should NOT mutate @line directly, but it MAY mutate the Line’s underlying Node structure. (WARNING: If the underlying Node structure IS altered, then this method should NOT be allowed to yield an CannotTransform after that point.)
StringParenStripper#
- class black.trans.StringParenStripper(line_length: int, normalize_strings: bool)#
Bases:
StringTransformerStringTransformer that strips surrounding parentheses from strings.
- Requirements:
- The line contains a string which is surrounded by parentheses and:
The target string is NOT the only argument to a function call.
The target string is NOT a “pointless” string.
If the target string contains a PERCENT, the brackets are not preceded or followed by an operator with higher precedence than PERCENT.
- Transformations:
The parentheses mentioned in the ‘Requirements’ section are stripped.
- Collaborations:
StringParenStripper has its own inherent usefulness, but it is also relied on to clean up the parentheses created by StringParenWrapper (in the event that they are no longer needed).
- do_match(line: Line) Ok[List[int]] | Err[CannotTransform]#
- Returns:
Ok(string_indices) such that for each index, line.leaves[index] is our target string if a match was able to be made. For transformers that don’t result in more lines (e.g. StringMerger, StringParenStripper), multiple matches and transforms are done at once to reduce the complexity. OR
Err(CannotTransform), if no match could be made.
- do_transform(line: Line, string_indices: List[int]) Iterator[Ok[Line] | Err[CannotTransform]]#
- Yields:
Ok(new_line) where new_line is the new transformed line. OR
Err(CannotTransform) if the transformation failed for some reason. The do_match(…) template method should usually be used to reject the form of the given Line, but in some cases it is difficult to know whether or not a Line meets the StringTransformer’s requirements until the transformation is already midway.
- Side Effects:
This method should NOT mutate @line directly, but it MAY mutate the Line’s underlying Node structure. (WARNING: If the underlying Node structure IS altered, then this method should NOT be allowed to yield an CannotTransform after that point.)
BaseStringSplitter#
- class black.trans.BaseStringSplitter(line_length: int, normalize_strings: bool)#
Bases:
StringTransformerAbstract class for StringTransformers which transform a Line’s strings by splitting them or placing them on their own lines where necessary to avoid going over the configured line length.
- Requirements:
The target string value is responsible for the line going over the line length limit. It follows that after all of black’s other line split methods have been exhausted, this line (or one of the resulting lines after all line splits are performed) would still be over the line_length limit unless we split this string. AND
The target string is NOT a “pointless” string (i.e. a string that has no parent or siblings). AND
The target string is not followed by an inline comment that appears to be a pragma. AND
The target string is not a multiline (i.e. triple-quote) string.
- abstract do_splitter_match(line: Line) Ok[List[int]] | Err[CannotTransform]#
BaseStringSplitter asks its clients to override this method instead of StringTransformer.do_match(…).
Follows the same protocol as StringTransformer.do_match(…).
Refer to help(StringTransformer.do_match) for more information.
- do_match(line: Line) Ok[List[int]] | Err[CannotTransform]#
- Returns:
Ok(string_indices) such that for each index, line.leaves[index] is our target string if a match was able to be made. For transformers that don’t result in more lines (e.g. StringMerger, StringParenStripper), multiple matches and transforms are done at once to reduce the complexity. OR
Err(CannotTransform), if no match could be made.
StringSplitter#
- class black.trans.StringSplitter(line_length: int, normalize_strings: bool)#
Bases:
BaseStringSplitter,CustomSplitMapMixinStringTransformer that splits “atom” strings (i.e. strings which exist on lines by themselves).
- Requirements:
The line consists ONLY of a single string (possibly prefixed by a string operator [e.g. ‘+’ or ‘==’]), MAYBE a string trailer, and MAYBE a trailing comma. AND
All of the requirements listed in BaseStringSplitter’s docstring.
- Transformations:
The string mentioned in the ‘Requirements’ section is split into as many substrings as necessary to adhere to the configured line length.
In the final set of substrings, no substring should be smaller than MIN_SUBSTR_SIZE characters.
The string will ONLY be split on spaces (i.e. each new substring should start with a space). Note that the string will NOT be split on a space which is escaped with a backslash.
If the string is an f-string, it will NOT be split in the middle of an f-expression (e.g. in f”FooBar: {foo() if x else bar()}”, {foo() if x else bar()} is an f-expression).
If the string that is being split has an associated set of custom split records and those custom splits will NOT result in any line going over the configured line length, those custom splits are used. Otherwise the string is split as late as possible (from left-to-right) while still adhering to the transformation rules listed above.
- Collaborations:
StringSplitter relies on StringMerger to construct the appropriate CustomSplit objects and add them to the custom split map.
- do_splitter_match(line: Line) Ok[List[int]] | Err[CannotTransform]#
BaseStringSplitter asks its clients to override this method instead of StringTransformer.do_match(…).
Follows the same protocol as StringTransformer.do_match(…).
Refer to help(StringTransformer.do_match) for more information.
- do_transform(line: Line, string_indices: List[int]) Iterator[Ok[Line] | Err[CannotTransform]]#
- Yields:
Ok(new_line) where new_line is the new transformed line. OR
Err(CannotTransform) if the transformation failed for some reason. The do_match(…) template method should usually be used to reject the form of the given Line, but in some cases it is difficult to know whether or not a Line meets the StringTransformer’s requirements until the transformation is already midway.
- Side Effects:
This method should NOT mutate @line directly, but it MAY mutate the Line’s underlying Node structure. (WARNING: If the underlying Node structure IS altered, then this method should NOT be allowed to yield an CannotTransform after that point.)
StringParenWrapper#
- class black.trans.StringParenWrapper(line_length: int, normalize_strings: bool)#
Bases:
BaseStringSplitter,CustomSplitMapMixinStringTransformer that wraps strings in parens and then splits at the LPAR.
- Requirements:
All of the requirements listed in BaseStringSplitter’s docstring in addition to the requirements listed below:
The line is a return/yield statement, which returns/yields a string. OR
The line is part of a ternary expression (e.g. x = y if cond else z) such that the line starts with else <string>, where <string> is some string. OR
The line is an assert statement, which ends with a string. OR
The line is an assignment statement (e.g. x = <string> or x += <string>) such that the variable is being assigned the value of some string. OR
The line is a dictionary key assignment where some valid key is being assigned the value of some string. OR
The line is an lambda expression and the value is a string. OR
The line starts with an “atom” string that prefers to be wrapped in parens. It’s preferred to be wrapped when it’s is an immediate child of a list/set/tuple literal, AND the string is surrounded by commas (or is the first/last child).
- Transformations:
The chosen string is wrapped in parentheses and then split at the LPAR.
We then have one line which ends with an LPAR and another line that starts with the chosen string. The latter line is then split again at the RPAR. This results in the RPAR (and possibly a trailing comma) being placed on its own line.
NOTE: If any leaves exist to the right of the chosen string (except for a trailing comma, which would be placed after the RPAR), those leaves are placed inside the parentheses. In effect, the chosen string is not necessarily being “wrapped” by parentheses. We can, however, count on the LPAR being placed directly before the chosen string.
In other words, StringParenWrapper creates “atom” strings. These can then be split again by StringSplitter, if necessary.
- Collaborations:
In the event that a string line split by StringParenWrapper is changed such that it no longer needs to be given its own line, StringParenWrapper relies on StringParenStripper to clean up the parentheses it created.
For “atom” strings that prefers to be wrapped in parens, it requires StringSplitter to hold the split until the string is wrapped in parens.
- do_splitter_match(line: Line) Ok[List[int]] | Err[CannotTransform]#
BaseStringSplitter asks its clients to override this method instead of StringTransformer.do_match(…).
Follows the same protocol as StringTransformer.do_match(…).
Refer to help(StringTransformer.do_match) for more information.
- do_transform(line: Line, string_indices: List[int]) Iterator[Ok[Line] | Err[CannotTransform]]#
- Yields:
Ok(new_line) where new_line is the new transformed line. OR
Err(CannotTransform) if the transformation failed for some reason. The do_match(…) template method should usually be used to reject the form of the given Line, but in some cases it is difficult to know whether or not a Line meets the StringTransformer’s requirements until the transformation is already midway.
- Side Effects:
This method should NOT mutate @line directly, but it MAY mutate the Line’s underlying Node structure. (WARNING: If the underlying Node structure IS altered, then this method should NOT be allowed to yield an CannotTransform after that point.)
StringParser#
- class black.trans.StringParser#
A state machine that aids in parsing a string’s “trailer”, which can be either non-existent, an old-style formatting sequence (e.g. % varX or % (varX, varY)), or a method-call / attribute access (e.g. .format(varX, varY)).
NOTE: A new StringParser object MUST be instantiated for each string trailer we need to parse.
Examples
We shall assume that line equals the Line object that corresponds to the following line of python code:
` x = "Some {}.".format("String") + some_other_string `Furthermore, we will assume that string_idx is some index such that:
` assert line.leaves[string_idx].value == "Some {}." `The following code snippet then holds:
` string_parser = StringParser() idx = string_parser.parse(line.leaves, string_idx) assert line.leaves[idx].type == token.PLUS `
DebugVisitor#
Replacement#
CellMagic#
CellMagicFinder#
- class black.handle_ipynb_magics.CellMagicFinder(cell_magic: CellMagic | None = None)#
Bases:
NodeVisitorFind cell magics.
Note that the source of the abstract syntax tree will already have been processed by IPython’s TransformerManager().transform_cell.
For example,
%%time
foo()
would have been transformed to
get_ipython().run_cell_magic(‘time’, ‘’, ‘foo()n’)
and we look for instances of the latter.
OffsetAndMagic#
MagicFinder#
- class black.handle_ipynb_magics.MagicFinder#
Bases:
NodeVisitorVisit cell to look for get_ipython calls.
Note that the source of the abstract syntax tree will already have been processed by IPython’s TransformerManager().transform_cell.
For example,
%matplotlib inline
would have been transformed to
get_ipython().run_line_magic(‘matplotlib’, ‘inline’)
and we look for instances of the latter (and likewise for other types of magics).
- visit_Assign(node: Assign) None#
Look for system assign magics.
For example,
black_version = !black –version env = %env var
would have been (respectively) transformed to
black_version = get_ipython().getoutput(‘black –version’) env = get_ipython().run_line_magic(‘env’, ‘var’)
and we look for instances of any of the latter.
- visit_Expr(node: Expr) None#
Look for magics in body of cell.
For examples,
!ls !!ls ?ls ??ls
would (respectively) get transformed to
get_ipython().system(‘ls’) get_ipython().getoutput(‘ls’) get_ipython().run_line_magic(‘pinfo’, ‘ls’) get_ipython().run_line_magic(‘pinfo2’, ‘ls’)
and we look for instances of any of the latter.
Cache#
- class black.cache.Cache(mode: black.mode.Mode, cache_file: pathlib.Path, file_data: Dict[str, black.cache.FileData] = <factory>)#
Bases:
object- classmethod read(mode: Mode) Self#
Read the cache if it exists and is well formed.
If it is not well formed, the call to write later should resolve the issue.
Enum Classes#
Classes inherited from Python Enum class.