diff --git a/black.py b/black.py index 087683a34f5..376c0d24299 100644 --- a/black.py +++ b/black.py @@ -5156,7 +5156,7 @@ def generate_ignored_nodes(leaf: Leaf) -> Iterator[LN]: """ container: Optional[LN] = container_of(leaf) while container is not None and container.type != token.ENDMARKER: - if fmt_on(container): + if is_fmt_on(container): return # fix for fmt: on in children @@ -5170,7 +5170,11 @@ def generate_ignored_nodes(leaf: Leaf) -> Iterator[LN]: container = container.next_sibling -def fmt_on(container: LN) -> bool: +def is_fmt_on(container: LN) -> bool: + """Determine whether formatting is switched on within a container. + + Determined by whether the last `# fmt:` comment is `on` or `off`. + """ is_fmt_on = False for comment in list_comments(container.prefix, is_endmarker=False): if comment.value in FMT_ON: @@ -5181,6 +5185,8 @@ def fmt_on(container: LN) -> bool: def contains_fmt_on_at_column(container: LN, column: int) -> bool: + """Determine if children at a given column have formatting switched on. + """ for child in container.children: if ( isinstance(child, Node) @@ -5188,13 +5194,14 @@ def contains_fmt_on_at_column(container: LN, column: int) -> bool: or isinstance(child, Leaf) and child.column == column ): - if fmt_on(child): + if is_fmt_on(child): return True return False def first_leaf_column(node: Node) -> Optional[int]: + """Returns the column of the first leaf child of a node.""" for child in node.children: if isinstance(child, Leaf): return child.column diff --git a/docs/reference/reference_functions.rst b/docs/reference/reference_functions.rst index 459e4980ae7..fc5cefb241b 100644 --- a/docs/reference/reference_functions.rst +++ b/docs/reference/reference_functions.rst @@ -135,6 +135,12 @@ Utilities .. autofunction:: black.generate_ignored_nodes +.. autofunction:: black.is_fmt_on + +.. autofunction:: black.contains_fmt_on_at_column + +.. autofunction:: black.first_leaf_column + .. autofunction:: black.generate_trailers_to_omit .. autofunction:: black.get_future_imports