Standardize type comments to form # type: (value) (psf#2097)

ranjodhsingh1729 · Pedro-Muller29 · ranjodhsingh1729 · commit a969e00a73d1 · 2025-04-08T02:33:16.000+05:30
Co-authored-by: Pedro Mezacasa Muller &lt;Pedro-Muller29@users.noreply.github.com&gt;
diff --git a/CHANGES.md b/CHANGES.md
@@ -19,7 +19,7 @@
 ### Preview style
 
 <!-- Changes that affect Black's preview style -->
-
+- Standardize type comments to form `# type: <value>` (#4645)
 - Fix a bug where one-liner functions/conditionals marked with `# fmt: skip`
   would still be formatted (#4552)
 
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
@@ -29,6 +29,8 @@ Currently, the following features are included in the preview style:
 - `fix_fmt_skip_in_one_liners`: Fix `# fmt: skip` behaviour on one-liner declarations,
   such as `def foo(): return "mock"  # fmt: skip`, where previously the declaration
   would have been incorrectly collapsed.
+- `standardize_type_comments`: Format type comments which have zero or more spaces between `#` and `type:` or between `type:` and value
+  to `# type: (value)`
 
 (labels/unstable-features)=
 
diff --git a/src/black/comments.py b/src/black/comments.py
@@ -13,6 +13,7 @@
     first_leaf_of,
     make_simple_prefix,
     preceding_leaf,
+    is_type_comment_string,
     syms,
 )
 from blib2to3.pgen2 import token
@@ -50,7 +51,7 @@ class ProtoComment:
     leading_whitespace: str  # leading whitespace before the comment, if any
 
 
-def generate_comments(leaf: LN) -> Iterator[Leaf]:
+def generate_comments(leaf: LN, mode: Mode) -> Iterator[Leaf]:
     """Clean the prefix of the `leaf` and generate comments from it, if any.
 
     Comments in lib2to3 are shoved into the whitespace prefix.  This happens
@@ -70,15 +71,17 @@ def generate_comments(leaf: LN) -> Iterator[Leaf]:
     are emitted with a fake STANDALONE_COMMENT token identifier.
     """
     total_consumed = 0
-    for pc in list_comments(leaf.prefix, is_endmarker=leaf.type == token.ENDMARKER):
+    for pc in list_comments(
+        leaf.prefix, is_endmarker=leaf.type == token.ENDMARKER, mode=mode
+    ):
         total_consumed = pc.consumed
         prefix = make_simple_prefix(pc.newlines, pc.form_feed)
         yield Leaf(pc.type, pc.value, prefix=prefix)
     normalize_trailing_prefix(leaf, total_consumed)
 
 
 @lru_cache(maxsize=4096)
-def list_comments(prefix: str, *, is_endmarker: bool) -> list[ProtoComment]:
+def list_comments(prefix: str, *, is_endmarker: bool, mode: Mode) -> list[ProtoComment]:
     """Return a list of :class:`ProtoComment` objects parsed from the given `prefix`."""
     result: list[ProtoComment] = []
     if not prefix or "#" not in prefix:
@@ -109,7 +112,7 @@ def list_comments(prefix: str, *, is_endmarker: bool) -> list[ProtoComment]:
             comment_type = token.COMMENT  # simple trailing comment
         else:
             comment_type = STANDALONE_COMMENT
-        comment = make_comment(line)
+        comment = make_comment(line, mode=mode)
         result.append(
             ProtoComment(
                 type=comment_type,
@@ -140,7 +143,7 @@ def normalize_trailing_prefix(leaf: LN, total_consumed: int) -> None:
     leaf.prefix = ""
 
 
-def make_comment(content: str) -> str:
+def make_comment(content: str, mode: Mode) -> str:
     """Return a consistently formatted comment from the given `content` string.
 
     All comments (except for "##", "#!", "#:", '#'") should have a single
@@ -158,9 +161,18 @@ def make_comment(content: str) -> str:
     if (
         content
         and content[0] == NON_BREAKING_SPACE
-        and not content.lstrip().startswith("type:")
+        and not is_type_comment_string("# " + content.lstrip(), mode=mode)
     ):
         content = " " + content[1:]  # Replace NBSP by a simple space
+    if (
+        Preview.standardize_type_comments in mode
+        and content
+        and NON_BREAKING_SPACE not in content
+        and is_type_comment_string("# " + content.lstrip(), mode=mode)
+    ):
+        type_part, value_part = content.strip().split(":", 1)
+        content = type_part.strip() + ": " + value_part.strip()
+
     if content and content[0] not in COMMENT_EXCEPTIONS:
         content = " " + content
     return "#" + content
@@ -184,7 +196,7 @@ def convert_one_fmt_off_pair(
     """
     for leaf in node.leaves():
         previous_consumed = 0
-        for comment in list_comments(leaf.prefix, is_endmarker=False):
+        for comment in list_comments(leaf.prefix, is_endmarker=False, mode=mode):
             is_fmt_off = comment.value in FMT_OFF
             is_fmt_skip = _contains_fmt_skip_comment(comment.value, mode)
             if (not is_fmt_off and not is_fmt_skip) or (
@@ -274,13 +286,13 @@ def generate_ignored_nodes(
         return
     container: Optional[LN] = container_of(leaf)
     while container is not None and container.type != token.ENDMARKER:
-        if is_fmt_on(container):
+        if is_fmt_on(container, mode=mode):
             return
 
         # fix for fmt: on in children
-        if children_contains_fmt_on(container):
+        if children_contains_fmt_on(container, mode=mode):
             for index, child in enumerate(container.children):
-                if isinstance(child, Leaf) and is_fmt_on(child):
+                if isinstance(child, Leaf) and is_fmt_on(child, mode=mode):
                     if child.type in CLOSING_BRACKETS:
                         # This means `# fmt: on` is placed at a different bracket level
                         # than `# fmt: off`. This is an invalid use, but as a courtesy,
@@ -291,12 +303,14 @@ def generate_ignored_nodes(
                 if (
                     child.type == token.INDENT
                     and index < len(container.children) - 1
-                    and children_contains_fmt_on(container.children[index + 1])
+                    and children_contains_fmt_on(
+                        container.children[index + 1], mode=mode
+                    )
                 ):
                     # This means `# fmt: on` is placed right after an indentation
                     # level, and we shouldn't swallow the previous INDENT token.
                     return
-                if children_contains_fmt_on(child):
+                if children_contains_fmt_on(child, mode=mode):
                     return
                 yield child
         else:
@@ -317,7 +331,7 @@ def _generate_ignored_nodes_from_fmt_skip(
     ignored_nodes: list[LN] = []
     # Need to properly format the leaf prefix to compare it to comment.value,
     # which is also formatted
-    comments = list_comments(leaf.prefix, is_endmarker=False)
+    comments = list_comments(leaf.prefix, is_endmarker=False, mode=mode)
     if not comments or comment.value != comments[0].value:
         return
     if prev_sibling is not None:
@@ -393,24 +407,24 @@ def _generate_ignored_nodes_from_fmt_skip(
         yield from iter(ignored_nodes)
 
 
-def is_fmt_on(container: LN) -> bool:
+def is_fmt_on(container: LN, mode: Mode) -> bool:
     """Determine whether formatting is switched on within a container.
     Determined by whether the last `# fmt:` comment is `on` or `off`.
     """
     fmt_on = False
-    for comment in list_comments(container.prefix, is_endmarker=False):
+    for comment in list_comments(container.prefix, is_endmarker=False, mode=mode):
         if comment.value in FMT_ON:
             fmt_on = True
         elif comment.value in FMT_OFF:
             fmt_on = False
     return fmt_on
 
 
-def children_contains_fmt_on(container: LN) -> bool:
+def children_contains_fmt_on(container: LN, mode: Mode) -> bool:
     """Determine if children have formatting switched on."""
     for child in container.children:
         leaf = first_leaf_of(child)
-        if leaf is not None and is_fmt_on(leaf):
+        if leaf is not None and is_fmt_on(leaf, mode=mode):
             return True
 
     return False
diff --git a/src/black/linegen.py b/src/black/linegen.py
@@ -139,7 +139,7 @@ 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()
-            for comment in generate_comments(node):
+            for comment in generate_comments(node, mode=self.mode):
                 if any_open_brackets:
                     # any comment within brackets is subject to splitting
                     self.current_line.append(comment)
@@ -249,6 +249,7 @@ def visit_dictsetmaker(self, node: Node) -> Iterator[Line]:
                         maybe_make_parens_invisible_in_atom(
                             child,
                             parent=node,
+                            mode=self.mode,
                             remove_brackets_around_comma=False,
                         )
                     else:
@@ -269,6 +270,7 @@ def visit_funcdef(self, node: Node) -> Iterator[Line]:
                     if maybe_make_parens_invisible_in_atom(
                         child,
                         parent=node,
+                        mode=self.mode,
                         remove_brackets_around_comma=False,
                     ):
                         wrap_in_parentheses(node, child, visible=False)
@@ -362,7 +364,7 @@ def visit_power(self, node: Node) -> Iterator[Line]:
             ):
                 wrap_in_parentheses(node, leaf)
 
-        remove_await_parens(node)
+        remove_await_parens(node, mode=self.mode)
 
         yield from self.visit_default(node)
 
@@ -409,7 +411,9 @@ def foo(a: int, b: float = 7): ...
         def foo(a: (int), b: (float) = 7): ...
         """
         assert len(node.children) == 3
-        if maybe_make_parens_invisible_in_atom(node.children[2], parent=node):
+        if maybe_make_parens_invisible_in_atom(
+            node.children[2], parent=node, mode=self.mode
+        ):
             wrap_in_parentheses(node, node.children[2], visible=False)
 
         yield from self.visit_default(node)
@@ -515,7 +519,9 @@ def visit_atom(self, node: Node) -> Iterator[Line]:
                 first.type == token.LBRACE and last.type == token.RBRACE
             ):
                 # Lists or sets of one item
-                maybe_make_parens_invisible_in_atom(node.children[1], parent=node)
+                maybe_make_parens_invisible_in_atom(
+                    node.children[1], parent=node, mode=self.mode
+                )
 
         yield from self.visit_default(node)
 
@@ -1381,7 +1387,7 @@ def normalize_invisible_parens(  # noqa: C901
     Standardizes on visible parentheses for single-element tuples, and keeps
     existing visible parentheses for other tuples and generator expressions.
     """
-    for pc in list_comments(node.prefix, is_endmarker=False):
+    for pc in list_comments(node.prefix, is_endmarker=False, mode=mode):
         if pc.value in FMT_OFF:
             # This `node` has a prefix with `# fmt: off`, don't mess with parens.
             return
@@ -1433,15 +1439,17 @@ def normalize_invisible_parens(  # noqa: C901
                 if maybe_make_parens_invisible_in_atom(
                     child,
                     parent=node,
+                    mode=mode,
                     remove_brackets_around_comma=True,
                 ):
                     wrap_in_parentheses(node, child, visible=False)
             elif isinstance(child, Node) and node.type == syms.with_stmt:
-                remove_with_parens(child, node)
+                remove_with_parens(child, node, mode=mode)
             elif child.type == syms.atom:
                 if maybe_make_parens_invisible_in_atom(
                     child,
                     parent=node,
+                    mode=mode,
                 ):
                     wrap_in_parentheses(node, child, visible=False)
             elif is_one_tuple(child):
@@ -1493,7 +1501,7 @@ def _normalize_import_from(parent: Node, child: LN, index: int) -> None:
         parent.append_child(Leaf(token.RPAR, ""))
 
 
-def remove_await_parens(node: Node) -> None:
+def remove_await_parens(node: Node, mode: Mode) -> None:
     if node.children[0].type == token.AWAIT and len(node.children) > 1:
         if (
             node.children[1].type == syms.atom
@@ -1502,6 +1510,7 @@ def remove_await_parens(node: Node) -> None:
             if maybe_make_parens_invisible_in_atom(
                 node.children[1],
                 parent=node,
+                mode=mode,
                 remove_brackets_around_comma=True,
             ):
                 wrap_in_parentheses(node, node.children[1], visible=False)
@@ -1570,7 +1579,7 @@ def _maybe_wrap_cms_in_parens(
         node.insert_child(1, new_child)
 
 
-def remove_with_parens(node: Node, parent: Node) -> None:
+def remove_with_parens(node: Node, parent: Node, mode: Mode) -> None:
     """Recursively hide optional parens in `with` statements."""
     # Removing all unnecessary parentheses in with statements in one pass is a tad
     # complex as different variations of bracketed statements result in pretty
@@ -1592,21 +1601,23 @@ def remove_with_parens(node: Node, parent: Node) -> None:
         if maybe_make_parens_invisible_in_atom(
             node,
             parent=parent,
+            mode=mode,
             remove_brackets_around_comma=True,
         ):
             wrap_in_parentheses(parent, node, visible=False)
         if isinstance(node.children[1], Node):
-            remove_with_parens(node.children[1], node)
+            remove_with_parens(node.children[1], node, mode=mode)
     elif node.type == syms.testlist_gexp:
         for child in node.children:
             if isinstance(child, Node):
-                remove_with_parens(child, node)
+                remove_with_parens(child, node, mode=mode)
     elif node.type == syms.asexpr_test and not any(
         leaf.type == token.COLONEQUAL for leaf in node.leaves()
     ):
         if maybe_make_parens_invisible_in_atom(
             node.children[0],
             parent=node,
+            mode=mode,
             remove_brackets_around_comma=True,
         ):
             wrap_in_parentheses(node, node.children[0], visible=False)
@@ -1615,6 +1626,7 @@ def remove_with_parens(node: Node, parent: Node) -> None:
 def maybe_make_parens_invisible_in_atom(
     node: LN,
     parent: LN,
+    mode: Mode,
     remove_brackets_around_comma: bool = False,
 ) -> bool:
     """If it's safe, make the parens in the atom `node` invisible, recursively.
@@ -1668,13 +1680,14 @@ def maybe_make_parens_invisible_in_atom(
         if (
             # If the prefix of `middle` includes a type comment with
             # ignore annotation, then we do not remove the parentheses
-            not is_type_ignore_comment_string(middle.prefix.strip())
+            not is_type_ignore_comment_string(middle.prefix.strip(), mode=mode)
         ):
             first.value = ""
             last.value = ""
         maybe_make_parens_invisible_in_atom(
             middle,
             parent=parent,
+            mode=mode,
             remove_brackets_around_comma=remove_brackets_around_comma,
         )
 
diff --git a/src/black/lines.py b/src/black/lines.py
@@ -286,9 +286,9 @@ def contains_uncollapsable_type_comments(self) -> bool:
         comment_seen = False
         for leaf_id, comments in self.comments.items():
             for comment in comments:
-                if is_type_comment(comment):
+                if is_type_comment(comment, mode=self.mode):
                     if comment_seen or (
-                        not is_type_ignore_comment(comment)
+                        not is_type_ignore_comment(comment, mode=self.mode)
                         and leaf_id not in ignored_ids
                     ):
                         return True
@@ -325,7 +325,7 @@ def contains_unsplittable_type_ignore(self) -> bool:
             # line.
             for node in self.leaves[-2:]:
                 for comment in self.comments.get(id(node), []):
-                    if is_type_ignore_comment(comment):
+                    if is_type_ignore_comment(comment, mode=self.mode):
                         return True
 
         return False
@@ -400,7 +400,7 @@ def append_comment(self, comment: Leaf) -> bool:
             and not last_leaf.value
             and last_leaf.parent
             and len(list(last_leaf.parent.leaves())) <= 3
-            and not is_type_comment(comment)
+            and not is_type_comment(comment, mode=self.mode)
         ):
             # Comments on an optional parens wrapping a single leaf should belong to
             # the wrapped node except if it's a type comment. Pinning the comment like
diff --git a/src/black/mode.py b/src/black/mode.py
@@ -204,6 +204,7 @@ class Preview(Enum):
     multiline_string_handling = auto()
     always_one_newline_after_import = auto()
     fix_fmt_skip_in_one_liners = auto()
+    standardize_type_comments = auto()
 
 
 UNSTABLE_FEATURES: set[Preview] = {
@@ -285,3 +286,18 @@ def get_cache_key(self) -> str:
             features_and_magics,
         ]
         return ".".join(parts)
+
+    def __hash__(self) -> int:
+        return hash((
+            frozenset(self.target_versions),
+            self.line_length,
+            self.string_normalization,
+            self.is_pyi,
+            self.is_ipynb,
+            self.skip_source_first_line,
+            self.magic_trailing_comma,
+            frozenset(self.python_cell_magics),
+            self.preview,
+            self.unstable,
+            frozenset(self.enabled_features),
+        ))
diff --git a/src/black/nodes.py b/src/black/nodes.py
diff --git a/src/black/resources/black.schema.json b/src/black/resources/black.schema.json
diff --git a/tests/data/cases/preview_standardize_type_comments.py b/tests/data/cases/preview_standardize_type_comments.py
