Sequence,
Set,
Tuple,
- Type,
TypeVar,
Union,
cast,
"""
-class FormatError(Exception):
- """Base exception for `# fmt: on` and `# fmt: off` handling.
-
- It holds the number of bytes of the prefix consumed before the format
- control comment appeared.
- """
-
- def __init__(self, consumed: int) -> None:
- super().__init__(consumed)
- self.consumed = consumed
-
- def trim_prefix(self, leaf: Leaf) -> None:
- leaf.prefix = leaf.prefix[self.consumed :]
-
- def leaf_from_consumed(self, leaf: Leaf) -> Leaf:
- """Returns a new Leaf from the consumed part of the prefix."""
- unformatted_prefix = leaf.prefix[: self.consumed]
- return Leaf(token.NEWLINE, unformatted_prefix)
-
-
-class FormatOn(FormatError):
- """Found a comment like `# fmt: on` in the file."""
-
-
-class FormatOff(FormatError):
- """Found a comment like `# fmt: off` in the file."""
-
-
class WriteBack(Enum):
NO = 0
YES = 1
is_pyi = bool(mode & FileMode.PYI)
py36 = bool(mode & FileMode.PYTHON36) or is_python36(src_node)
normalize_strings = not bool(mode & FileMode.NO_STRING_NORMALIZATION)
+ normalize_fmt_off(src_node)
lines = LineGenerator(
remove_u_prefix=py36 or "unicode_literals" in future_imports,
is_pyi=is_pyi,
out(f" {node.value!r}", fg="blue", bold=False)
@classmethod
- def show(cls, code: str) -> None:
+ def show(cls, code: Union[str, Leaf, Node]) -> None:
"""Pretty-print the lib2to3 AST of a given string of `code`.
Convenience method for debugging.
"""
v: DebugVisitor[None] = DebugVisitor()
- list(v.visit(lib2to3_parse(code)))
+ if isinstance(code, str):
+ code = lib2to3_parse(code)
+ list(v.visit(code))
KEYWORDS = set(keyword.kwlist)
syms.classdef,
}
STANDALONE_COMMENT = 153
+token.tok_name[STANDALONE_COMMENT] = "STANDALONE_COMMENT"
LOGIC_OPERATORS = {"and", "or"}
COMPARATORS = {
token.LESS,
syms.testlist_gexp,
syms.testlist_star_expr,
}
+SURROUNDED_BY_BRACKETS = {
+ syms.typedargslist,
+ syms.arglist,
+ syms.subscriptlist,
+ syms.vfplist,
+ syms.import_as_names,
+ syms.yield_expr,
+ syms.testlist_gexp,
+ syms.testlist_star_expr,
+ syms.listmaker,
+ syms.dictsetmaker,
+}
TEST_DESCENDANTS = {
syms.test,
syms.lambdef,
def is_complex_subscript(self, leaf: Leaf) -> bool:
"""Return True iff `leaf` is part of a slice with non-trivial exprs."""
- open_lsqb = (
- leaf if leaf.type == token.LSQB else self.bracket_tracker.get_open_lsqb()
- )
+ open_lsqb = self.bracket_tracker.get_open_lsqb()
if open_lsqb is None:
return False
subscript_start = open_lsqb.next_sibling
- if (
- isinstance(subscript_start, Node)
- and subscript_start.type == syms.subscriptlist
- ):
- subscript_start = child_towards(subscript_start, leaf)
+
+ if isinstance(subscript_start, Node):
+ if subscript_start.type == syms.listmaker:
+ return False
+
+ if subscript_start.type == syms.subscriptlist:
+ subscript_start = child_towards(subscript_start, leaf)
return subscript_start is not None and any(
n.type in TEST_DESCENDANTS for n in subscript_start.pre_order()
)
return bool(self.leaves or self.comments)
-class UnformattedLines(Line):
- """Just like :class:`Line` but stores lines which aren't reformatted."""
-
- def append(self, leaf: Leaf, preformatted: bool = True) -> None:
- """Just add a new `leaf` to the end of the lines.
-
- The `preformatted` argument is ignored.
-
- Keeps track of indentation `depth`, which is useful when the user
- says `# fmt: on`. Otherwise, doesn't do anything with the `leaf`.
- """
- try:
- list(generate_comments(leaf))
- except FormatOn as f_on:
- self.leaves.append(f_on.leaf_from_consumed(leaf))
- raise
-
- self.leaves.append(leaf)
- if leaf.type == token.INDENT:
- self.depth += 1
- elif leaf.type == token.DEDENT:
- self.depth -= 1
-
- def __str__(self) -> str:
- """Render unformatted lines from leaves which were added with `append()`.
-
- `depth` is not used for indentation in this case.
- """
- if not self:
- return "\n"
-
- res = ""
- for leaf in self.leaves:
- res += str(leaf)
- return res
-
- def append_comment(self, comment: Leaf) -> bool:
- """Not implemented in this class. Raises `NotImplementedError`."""
- raise NotImplementedError("Unformatted lines don't store comments separately.")
-
- def maybe_remove_trailing_comma(self, closing: Leaf) -> bool:
- """Does nothing and returns False."""
- return False
-
- def maybe_increment_for_loop_variable(self, leaf: Leaf) -> bool:
- """Does nothing and returns False."""
- return False
-
-
@dataclass
class EmptyLineTracker:
"""Provides a stateful method that returns the number of potential extra
This is for separating `def`, `async def` and `class` with extra empty
lines (two on module-level).
"""
- if isinstance(current_line, UnformattedLines):
- return 0, 0
-
before, after = self._maybe_empty_lines(current_line)
before -= self.previous_after
self.previous_after = after
before = 0 if depth else 1
else:
before = 1 if depth else 2
- is_decorator = current_line.is_decorator
- if is_decorator or current_line.is_def or current_line.is_class:
- if not is_decorator:
- self.previous_defs.append(depth)
- if self.previous_line is None:
- # Don't insert empty lines before the first line in the file.
- return 0, 0
-
- if self.previous_line.is_decorator:
- return 0, 0
-
- if self.previous_line.depth < current_line.depth and (
- self.previous_line.is_class or self.previous_line.is_def
- ):
- return 0, 0
-
- if (
- self.previous_line.is_comment
- and self.previous_line.depth == current_line.depth
- and before == 0
- ):
- return 0, 0
-
- if self.is_pyi:
- if self.previous_line.depth > current_line.depth:
- newlines = 1
- elif current_line.is_class or self.previous_line.is_class:
- if current_line.is_stub_class and self.previous_line.is_stub_class:
- newlines = 0
- else:
- newlines = 1
- else:
- newlines = 0
- else:
- newlines = 2
- if current_line.depth and newlines:
- newlines -= 1
- return newlines, 0
+ if current_line.is_decorator or current_line.is_def or current_line.is_class:
+ return self._maybe_empty_lines_for_class_or_def(current_line, before)
if (
self.previous_line
return before, 0
+ def _maybe_empty_lines_for_class_or_def(
+ self, current_line: Line, before: int
+ ) -> Tuple[int, int]:
+ if not current_line.is_decorator:
+ self.previous_defs.append(current_line.depth)
+ if self.previous_line is None:
+ # Don't insert empty lines before the first line in the file.
+ return 0, 0
+
+ if self.previous_line.is_decorator:
+ return 0, 0
+
+ if self.previous_line.depth < current_line.depth and (
+ self.previous_line.is_class or self.previous_line.is_def
+ ):
+ return 0, 0
+
+ if (
+ self.previous_line.is_comment
+ and self.previous_line.depth == current_line.depth
+ and before == 0
+ ):
+ return 0, 0
+
+ if self.is_pyi:
+ if self.previous_line.depth > current_line.depth:
+ newlines = 1
+ elif current_line.is_class or self.previous_line.is_class:
+ if current_line.is_stub_class and self.previous_line.is_stub_class:
+ # No blank line between classes with an emty body
+ newlines = 0
+ else:
+ newlines = 1
+ elif current_line.is_def and not self.previous_line.is_def:
+ # Blank line between a block of functions and a block of non-functions
+ newlines = 1
+ else:
+ newlines = 0
+ else:
+ newlines = 2
+ if current_line.depth and newlines:
+ newlines -= 1
+ return newlines, 0
+
@dataclass
class LineGenerator(Visitor[Line]):
current_line: Line = Factory(Line)
remove_u_prefix: bool = False
- def line(self, indent: int = 0, type: Type[Line] = Line) -> Iterator[Line]:
+ def line(self, indent: int = 0) -> Iterator[Line]:
"""Generate a line.
If the line is empty, only emit if it makes sense.
If any lines were generated, set up a new current_line.
"""
if not self.current_line:
- if self.current_line.__class__ == type:
- self.current_line.depth += indent
- else:
- self.current_line = type(depth=self.current_line.depth + indent)
+ self.current_line.depth += indent
return # Line is empty, don't emit. Creating a new one unnecessary.
complete_line = self.current_line
- self.current_line = type(depth=complete_line.depth + indent)
+ self.current_line = Line(depth=complete_line.depth + indent)
yield complete_line
- def visit(self, node: LN) -> Iterator[Line]:
- """Main method to visit `node` and its children.
-
- Yields :class:`Line` objects.
- """
- if isinstance(self.current_line, UnformattedLines):
- # File contained `# fmt: off`
- yield from self.visit_unformatted(node)
-
- else:
- yield from super().visit(node)
-
def visit_default(self, node: LN) -> Iterator[Line]:
"""Default `visit_*()` implementation. Recurses to children of `node`."""
if isinstance(node, Leaf):
any_open_brackets = self.current_line.bracket_tracker.any_open_brackets()
- try:
- for comment in generate_comments(node):
- if any_open_brackets:
- # any comment within brackets is subject to splitting
- self.current_line.append(comment)
- elif comment.type == token.COMMENT:
- # regular trailing comment
- self.current_line.append(comment)
- yield from self.line()
-
- else:
- # regular standalone comment
- yield from self.line()
-
- self.current_line.append(comment)
- yield from self.line()
-
- except FormatOff as f_off:
- f_off.trim_prefix(node)
- yield from self.line(type=UnformattedLines)
- yield from self.visit(node)
-
- except FormatOn as f_on:
- # This only happens here if somebody says "fmt: on" multiple
- # times in a row.
- f_on.trim_prefix(node)
- yield from self.visit_default(node)
+ for comment in generate_comments(node):
+ if any_open_brackets:
+ # any comment within brackets is subject to splitting
+ self.current_line.append(comment)
+ elif comment.type == token.COMMENT:
+ # regular trailing comment
+ self.current_line.append(comment)
+ yield from self.line()
- else:
- normalize_prefix(node, inside_brackets=any_open_brackets)
- if self.normalize_strings and node.type == token.STRING:
- normalize_string_prefix(node, remove_u_prefix=self.remove_u_prefix)
- normalize_string_quotes(node)
- if node.type not in WHITESPACE:
- self.current_line.append(node)
+ else:
+ # regular standalone comment
+ yield from self.line()
+
+ self.current_line.append(comment)
+ yield from self.line()
+
+ normalize_prefix(node, inside_brackets=any_open_brackets)
+ if self.normalize_strings and node.type == token.STRING:
+ normalize_string_prefix(node, remove_u_prefix=self.remove_u_prefix)
+ normalize_string_quotes(node)
+ if node.type not in WHITESPACE:
+ self.current_line.append(node)
yield from super().visit_default(node)
def visit_INDENT(self, node: Node) -> Iterator[Line]:
yield from self.visit_default(leaf)
yield from self.line()
- def visit_unformatted(self, node: LN) -> Iterator[Line]:
- """Used when file contained a `# fmt: off`."""
- if isinstance(node, Node):
- for child in node.children:
- yield from self.visit(child)
-
- else:
- try:
- self.current_line.append(node)
- except FormatOn as f_on:
- f_on.trim_prefix(node)
- yield from self.line()
- yield from self.visit(node)
-
- if node.type == token.ENDMARKER:
- # somebody decided not to put a final `# fmt: on`
- yield from self.line()
+ def visit_STANDALONE_COMMENT(self, leaf: Leaf) -> Iterator[Line]:
+ if not self.current_line.bracket_tracker.any_open_brackets():
+ yield from self.line()
+ yield from self.visit_default(leaf)
def __attrs_post_init__(self) -> None:
"""You are in a twisty little maze of passages."""
return node
+def container_of(leaf: Leaf) -> LN:
+ """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.
+ """
+ same_prefix = leaf.prefix
+ container: LN = leaf
+ while container:
+ parent = container.parent
+ if parent is None:
+ break
+
+ if parent.children[0].prefix != same_prefix:
+ break
+
+ if parent.type == syms.file_input:
+ break
+
+ if parent.type in SURROUNDED_BY_BRACKETS:
+ break
+
+ container = parent
+ return container
+
+
def is_split_after_delimiter(leaf: Leaf, previous: Leaf = None) -> int:
"""Return the priority of the `leaf` delimiter, given a line break after it.
return 0
+FMT_OFF = {"# fmt: off", "# fmt:off", "# yapf: disable"}
+FMT_ON = {"# fmt: on", "# fmt:on", "# yapf: enable"}
+
+
def generate_comments(leaf: LN) -> Iterator[Leaf]:
"""Clean the prefix of the `leaf` and generate comments from it, if any.
Inline comments are emitted as regular token.COMMENT leaves. Standalone
are emitted with a fake STANDALONE_COMMENT token identifier.
"""
- p = leaf.prefix
- if not p:
- return
+ for pc in list_comments(leaf.prefix, is_endmarker=leaf.type == token.ENDMARKER):
+ yield Leaf(pc.type, pc.value, prefix="\n" * pc.newlines)
- if "#" not in p:
- return
+
+@dataclass
+class ProtoComment:
+ type: int # token.COMMENT or STANDALONE_COMMENT
+ value: str # content of the comment
+ newlines: int # how many newlines before the comment
+ consumed: int # how many characters of the original leaf's prefix did we consume
+
+
+@lru_cache(maxsize=4096)
+def list_comments(prefix: str, *, is_endmarker: bool) -> List[ProtoComment]:
+ result: List[ProtoComment] = []
+ if not prefix or "#" not in prefix:
+ return result
consumed = 0
nlines = 0
- for index, line in enumerate(p.split("\n")):
+ for index, line in enumerate(prefix.split("\n")):
consumed += len(line) + 1 # adding the length of the split '\n'
line = line.lstrip()
if not line:
if not line.startswith("#"):
continue
- if index == 0 and leaf.type != token.ENDMARKER:
+ if index == 0 and not is_endmarker:
comment_type = token.COMMENT # simple trailing comment
else:
comment_type = STANDALONE_COMMENT
comment = make_comment(line)
- yield Leaf(comment_type, comment, prefix="\n" * nlines)
-
- if comment in {"# fmt: on", "# yapf: enable"}:
- raise FormatOn(consumed)
-
- if comment in {"# fmt: off", "# yapf: disable"}:
- if comment_type == STANDALONE_COMMENT:
- raise FormatOff(consumed)
-
- prev = preceding_leaf(leaf)
- if not prev or prev.type in WHITESPACE: # standalone comment in disguise
- raise FormatOff(consumed)
-
+ result.append(
+ ProtoComment(
+ type=comment_type, value=comment, newlines=nlines, consumed=consumed
+ )
+ )
nlines = 0
+ return result
def make_comment(content: str) -> str:
If `py36` is True, splitting may generate syntax that is only compatible
with Python 3.6 and later.
"""
- if isinstance(line, UnformattedLines) or line.is_comment:
+ if line.is_comment:
yield line
return
prefix = leaf.value[:first_quote_pos]
unescaped_new_quote = re.compile(rf"(([^\\]|^)(\\\\)*){new_quote}")
- escaped_new_quote = re.compile(rf"([^\\]|^)\\(\\\\)*{new_quote}")
- escaped_orig_quote = re.compile(rf"([^\\]|^)\\(\\\\)*{orig_quote}")
+ escaped_new_quote = re.compile(rf"([^\\]|^)\\((?:\\\\)*){new_quote}")
+ escaped_orig_quote = re.compile(rf"([^\\]|^)\\((?:\\\\)*){orig_quote}")
body = leaf.value[first_quote_pos + len(orig_quote) : -len(orig_quote)]
if "r" in prefix.casefold():
if unescaped_new_quote.search(body):
# Do not introduce or remove backslashes in raw strings
new_body = body
else:
- # remove unnecessary quotes
+ # remove unnecessary escapes
new_body = sub_twice(escaped_new_quote, rf"\1\2{new_quote}", body)
if body != new_body:
- # Consider the string without unnecessary quotes as the original
+ # Consider the string without unnecessary escapes as the original
body = new_body
leaf.value = f"{prefix}{orig_quote}{body}{orig_quote}"
new_body = sub_twice(escaped_orig_quote, rf"\1\2{orig_quote}", new_body)
Standardizes on visible parentheses for single-element tuples, and keeps
existing visible parentheses for other tuples and generator expressions.
"""
- try:
- list(generate_comments(node))
- except FormatOff:
- return # This `node` has a prefix with `# fmt: off`, don't mess with parens.
+ for pc in list_comments(node.prefix, is_endmarker=False):
+ if pc.value in FMT_OFF:
+ # This `node` has a prefix with `# fmt: off`, don't mess with parens.
+ return
check_lpar = False
for index, child in enumerate(list(node.children)):
check_lpar = isinstance(child, Leaf) and child.value in parens_after
+def normalize_fmt_off(node: Node) -> None:
+ """Convert content between `# fmt: off`/`# fmt: on` into standalone comments."""
+ try_again = True
+ while try_again:
+ try_again = convert_one_fmt_off_pair(node)
+
+
+def convert_one_fmt_off_pair(node: Node) -> bool:
+ """Convert content of a single `# fmt: off`/`# fmt: on` into a standalone comment.
+
+ Returns True if a pair was converted.
+ """
+ for leaf in node.leaves():
+ previous_consumed = 0
+ for comment in list_comments(leaf.prefix, is_endmarker=False):
+ if comment.value in FMT_OFF:
+ # We only want standalone comments. If there's no previous leaf or
+ # the previous leaf is indentation, it's a standalone comment in
+ # disguise.
+ if comment.type != STANDALONE_COMMENT:
+ prev = preceding_leaf(leaf)
+ if prev and prev.type not in WHITESPACE:
+ continue
+
+ ignored_nodes = list(generate_ignored_nodes(leaf))
+ first = ignored_nodes[0] # Can be a container node with the `leaf`.
+ parent = first.parent
+ prefix = first.prefix
+ first.prefix = prefix[comment.consumed :]
+ hidden_value = (
+ comment.value + "\n" + "".join(str(n) for n in ignored_nodes)
+ )
+ if hidden_value.endswith("\n"):
+ # That happens when one of the `ignored_nodes` ended with a NEWLINE
+ # leaf (possibly followed by a DEDENT).
+ hidden_value = hidden_value[:-1]
+ first_idx = None
+ for ignored in ignored_nodes:
+ index = ignored.remove()
+ if first_idx is None:
+ first_idx = index
+ assert parent is not None, "INTERNAL ERROR: fmt: on/off handling (1)"
+ assert first_idx is not None, "INTERNAL ERROR: fmt: on/off handling (2)"
+ parent.insert_child(
+ first_idx,
+ Leaf(
+ STANDALONE_COMMENT,
+ hidden_value,
+ prefix=prefix[:previous_consumed] + "\n" * comment.newlines,
+ ),
+ )
+ return True
+
+ previous_consumed += comment.consumed
+
+ return False
+
+
+def generate_ignored_nodes(leaf: Leaf) -> Iterator[LN]:
+ """Starting from the container of `leaf`, generate all leaves until `# fmt: on`.
+
+ Stops at the end of the block.
+ """
+ container: Optional[LN] = container_of(leaf)
+ while container is not None and container.type != token.ENDMARKER:
+ for comment in list_comments(container.prefix, is_endmarker=False):
+ if comment.value in FMT_ON:
+ return
+
+ yield container
+
+ container = container.next_sibling
+
+
def maybe_make_parens_invisible_in_atom(node: LN) -> bool:
"""If it's safe, make the parens in the atom `node` invisible, recursively."""
if (
"""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.
"""
assert root.is_absolute(), f"INTERNAL ERROR: `root` must be absolute but is {root}"
for child in path.iterdir():
- normalized_path = "/" + child.resolve().relative_to(root).as_posix()
+ try:
+ normalized_path = "/" + child.resolve().relative_to(root).as_posix()
+ except ValueError:
+ if child.is_symlink():
+ report.path_ignored(
+ child,
+ "is a symbolic link that points outside of the root directory",
+ )
+ continue
+
+ raise
+
if child.is_dir():
normalized_path += "/"
exclude_match = exclude.search(normalized_path)