Brevity: only use the variables required to convey the intended expressions

[etc/vim.git] / src / black / __init__.py

diff --git a/src/black/__init__.py b/src/black/__init__.py
index c1db8e6ef64812842be8efb4b48490a2c60927bb..67eef95390d76693be184a7f67c81836b28e8409 100644 (file)
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -42,7 +42,6 @@ from typing import (
     cast,
     TYPE_CHECKING,
 )
     cast,
     TYPE_CHECKING,
 )

-from typing_extensions import Final

 from mypy_extensions import mypyc_attr
 
 from appdirs import user_cache_dir
 from mypy_extensions import mypyc_attr
 
 from appdirs import user_cache_dir


@@ -61,6 +60,11 @@ from blib2to3.pgen2.parse import ParseError
 
 from _black_version import version as __version__
 
 
 from _black_version import version as __version__
 

+if sys.version_info < (3, 8):
+    from typing_extensions import Final
+else:
+    from typing import Final
+

 if TYPE_CHECKING:
     import colorama  # noqa: F401
 
 if TYPE_CHECKING:
     import colorama  # noqa: F401
 


@@ -68,6 +72,7 @@ DEFAULT_LINE_LENGTH = 88
 DEFAULT_EXCLUDES = r"/(\.direnv|\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_build|buck-out|build|dist)/"  # noqa: B950
 DEFAULT_INCLUDES = r"\.pyi?$"
 CACHE_DIR = Path(user_cache_dir("black", version=__version__))
 DEFAULT_EXCLUDES = r"/(\.direnv|\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_build|buck-out|build|dist)/"  # noqa: B950
 DEFAULT_INCLUDES = r"\.pyi?$"
 CACHE_DIR = Path(user_cache_dir("black", version=__version__))

+STDIN_PLACEHOLDER = "__BLACK_STDIN_FILENAME__"

 
 STRING_PREFIX_CHARS: Final = "furbFURB"  # All possible string prefix characters.
 
 
 STRING_PREFIX_CHARS: Final = "furbFURB"  # All possible string prefix characters.
 


@@ -88,7 +93,7 @@ Transformer = Callable[["Line", Collection["Feature"]], Iterator["Line"]]
 Timestamp = float
 FileSize = int
 CacheInfo = Tuple[Timestamp, FileSize]
 Timestamp = float
 FileSize = int
 CacheInfo = Tuple[Timestamp, FileSize]

-Cache = Dict[Path, CacheInfo]
+Cache = Dict[str, CacheInfo]

 out = partial(click.secho, bold=True, err=True)
 err = partial(click.secho, fg="red", err=True)
 
 out = partial(click.secho, bold=True, err=True)
 err = partial(click.secho, fg="red", err=True)
 


@@ -255,6 +260,7 @@ class Mode:
     target_versions: Set[TargetVersion] = field(default_factory=set)
     line_length: int = DEFAULT_LINE_LENGTH
     string_normalization: bool = True
     target_versions: Set[TargetVersion] = field(default_factory=set)
     line_length: int = DEFAULT_LINE_LENGTH
     string_normalization: bool = True

+    magic_trailing_comma: bool = True

     experimental_string_processing: bool = False
     is_pyi: bool = False
 
     experimental_string_processing: bool = False
     is_pyi: bool = False
 


@@ -392,6 +398,12 @@ def target_version_option_callback(
     is_flag=True,
     help="Don't normalize string quotes or prefixes.",
 )
     is_flag=True,
     help="Don't normalize string quotes or prefixes.",
 )

+@click.option(
+    "-C",
+    "--skip-magic-trailing-comma",
+    is_flag=True,
+    help="Don't use trailing commas as a reason to split lines.",
+)

 @click.option(
     "--experimental-string-processing",
     is_flag=True,
 @click.option(
     "--experimental-string-processing",
     is_flag=True,


@@ -454,7 +466,16 @@ def target_version_option_callback(
     type=str,
     help=(
         "Like --exclude, but files and directories matching this regex will be "
     type=str,
     help=(
         "Like --exclude, but files and directories matching this regex will be "

-        "excluded even when they are passed explicitly as arguments"
+        "excluded even when they are passed explicitly as arguments."
+    ),
+)
+@click.option(
+    "--stdin-filename",
+    type=str,
+    help=(
+        "The name of the file when passing it through stdin. Useful to make "
+        "sure Black will respect --force-exclude option on some "
+        "editors that rely on using stdin."

     ),
 )
 @click.option(
     ),
 )
 @click.option(


@@ -510,12 +531,14 @@ def main(
     fast: bool,
     pyi: bool,
     skip_string_normalization: bool,
     fast: bool,
     pyi: bool,
     skip_string_normalization: bool,

+    skip_magic_trailing_comma: bool,

     experimental_string_processing: bool,
     quiet: bool,
     verbose: bool,
     include: str,
     exclude: str,
     force_exclude: Optional[str],
     experimental_string_processing: bool,
     quiet: bool,
     verbose: bool,
     include: str,
     exclude: str,
     force_exclude: Optional[str],

+    stdin_filename: Optional[str],

     src: Tuple[str, ...],
     config: Optional[str],
 ) -> None:
     src: Tuple[str, ...],
     config: Optional[str],
 ) -> None:


@@ -531,6 +554,7 @@ def main(
         line_length=line_length,
         is_pyi=pyi,
         string_normalization=not skip_string_normalization,
         line_length=line_length,
         is_pyi=pyi,
         string_normalization=not skip_string_normalization,

+        magic_trailing_comma=not skip_magic_trailing_comma,

         experimental_string_processing=experimental_string_processing,
     )
     if config and verbose:
         experimental_string_processing=experimental_string_processing,
     )
     if config and verbose:


@@ -548,6 +572,7 @@ def main(
         exclude=exclude,
         force_exclude=force_exclude,
         report=report,
         exclude=exclude,
         force_exclude=force_exclude,
         report=report,

+        stdin_filename=stdin_filename,

     )
 
     path_empty(
     )
 
     path_empty(


@@ -587,6 +612,7 @@ def get_sources(
     exclude: str,
     force_exclude: Optional[str],
     report: "Report",
     exclude: str,
     force_exclude: Optional[str],
     report: "Report",

+    stdin_filename: Optional[str],

 ) -> Set[Path]:
     """Compute the set of files to be formatted."""
     try:
 ) -> Set[Path]:
     """Compute the set of files to be formatted."""
     try:


@@ -613,22 +639,14 @@ def get_sources(
     gitignore = get_gitignore(root)
 
     for s in src:
     gitignore = get_gitignore(root)
 
     for s in src:

-        p = Path(s)
-        if p.is_dir():
-            sources.update(
-                gen_python_files(
-                    p.iterdir(),
-                    root,
-                    include_regex,
-                    exclude_regex,
-                    force_exclude_regex,
-                    report,
-                    gitignore,
-                )
-            )
-        elif s == "-":
-            sources.add(p)
-        elif p.is_file():
+        if s == "-" and stdin_filename:
+            p = Path(stdin_filename)
+            is_stdin = True
+        else:
+            p = Path(s)
+            is_stdin = False
+
+        if is_stdin or p.is_file():

             normalized_path = normalize_path_maybe_ignore(p, root, report)
             if normalized_path is None:
                 continue
             normalized_path = normalize_path_maybe_ignore(p, root, report)
             if normalized_path is None:
                 continue


@@ -643,6 +661,23 @@ def get_sources(
                 report.path_ignored(p, "matches the --force-exclude regular expression")
                 continue
 
                 report.path_ignored(p, "matches the --force-exclude regular expression")
                 continue
 

+            if is_stdin:
+                p = Path(f"{STDIN_PLACEHOLDER}{str(p)}")
+
+            sources.add(p)
+        elif p.is_dir():
+            sources.update(
+                gen_python_files(
+                    p.iterdir(),
+                    root,
+                    include_regex,
+                    exclude_regex,
+                    force_exclude_regex,
+                    report,
+                    gitignore,
+                )
+            )
+        elif s == "-":

             sources.add(p)
         else:
             err(f"invalid path: {s}")
             sources.add(p)
         else:
             err(f"invalid path: {s}")


@@ -670,7 +705,18 @@ def reformat_one(
     """
     try:
         changed = Changed.NO
     """
     try:
         changed = Changed.NO

-        if not src.is_file() and str(src) == "-":
+
+        if str(src) == "-":
+            is_stdin = True
+        elif str(src).startswith(STDIN_PLACEHOLDER):
+            is_stdin = True
+            # Use the original name again in case we want to print something
+            # to the user
+            src = Path(str(src)[len(STDIN_PLACEHOLDER) :])
+        else:
+            is_stdin = False
+
+        if is_stdin:

             if format_stdin_to_stdout(fast=fast, write_back=write_back, mode=mode):
                 changed = Changed.YES
         else:
             if format_stdin_to_stdout(fast=fast, write_back=write_back, mode=mode):
                 changed = Changed.YES
         else:


@@ -678,7 +724,8 @@ def reformat_one(
             if write_back not in (WriteBack.DIFF, WriteBack.COLOR_DIFF):
                 cache = read_cache(mode)
                 res_src = src.resolve()
             if write_back not in (WriteBack.DIFF, WriteBack.COLOR_DIFF):
                 cache = read_cache(mode)
                 res_src = src.resolve()

-                if res_src in cache and cache[res_src] == get_cache_info(res_src):
+                res_src_s = str(res_src)
+                if res_src_s in cache and cache[res_src_s] == get_cache_info(res_src):

                     changed = Changed.CACHED
             if changed is not Changed.CACHED and format_file_in_place(
                 src, fast=fast, write_back=write_back, mode=mode
                     changed = Changed.CACHED
             if changed is not Changed.CACHED and format_file_in_place(
                 src, fast=fast, write_back=write_back, mode=mode


@@ -704,7 +751,7 @@ def reformat_many(
     worker_count = os.cpu_count()
     if sys.platform == "win32":
         # Work around https://bugs.python.org/issue26903
     worker_count = os.cpu_count()
     if sys.platform == "win32":
         # Work around https://bugs.python.org/issue26903

-        worker_count = min(worker_count, 61)
+        worker_count = min(worker_count, 60)

     try:
         executor = ProcessPoolExecutor(max_workers=worker_count)
     except (ImportError, OSError):
     try:
         executor = ProcessPoolExecutor(max_workers=worker_count)
     except (ImportError, OSError):


@@ -859,9 +906,9 @@ def color_diff(contents: str) -> str:
     for i, line in enumerate(lines):
         if line.startswith("+++") or line.startswith("---"):
             line = "\033[1;37m" + line + "\033[0m"  # bold white, reset
     for i, line in enumerate(lines):
         if line.startswith("+++") or line.startswith("---"):
             line = "\033[1;37m" + line + "\033[0m"  # bold white, reset

-        if line.startswith("@@"):
+        elif line.startswith("@@"):

             line = "\033[36m" + line + "\033[0m"  # cyan, reset
             line = "\033[36m" + line + "\033[0m"  # cyan, reset

-        if line.startswith("+"):
+        elif line.startswith("+"):

             line = "\033[32m" + line + "\033[0m"  # green, reset
         elif line.startswith("-"):
             line = "\033[31m" + line + "\033[0m"  # red, reset
             line = "\033[32m" + line + "\033[0m"  # green, reset
         elif line.startswith("-"):
             line = "\033[31m" + line + "\033[0m"  # red, reset


@@ -871,30 +918,22 @@ def color_diff(contents: str) -> str:
 
 def wrap_stream_for_windows(
     f: io.TextIOWrapper,
 
 def wrap_stream_for_windows(
     f: io.TextIOWrapper,

-) -> Union[io.TextIOWrapper, "colorama.AnsiToWin32.AnsiToWin32"]:
+) -> Union[io.TextIOWrapper, "colorama.AnsiToWin32"]:

     """
     """

-    Wrap the stream in colorama's wrap_stream so colors are shown on Windows.
+    Wrap stream with colorama's wrap_stream so colors are shown on Windows.

 
 

-    If `colorama` is not found, then no change is made. If `colorama` does
-    exist, then it handles the logic to determine whether or not to change
-    things.
+    If `colorama` is unavailable, the original stream is returned unmodified.
+    Otherwise, the `wrap_stream()` function determines whether the stream needs
+    to be wrapped for a Windows environment and will accordingly either return
+    an `AnsiToWin32` wrapper or the original stream.

     """
     try:
     """
     try:

-        from colorama import initialise
-
-        # We set `strip=False` so that we can don't have to modify
-        # test_express_diff_with_color.
-        f = initialise.wrap_stream(
-            f, convert=None, strip=False, autoreset=False, wrap=True
-        )
-
-        # wrap_stream returns a `colorama.AnsiToWin32.AnsiToWin32` object
-        # which does not have a `detach()` method. So we fake one.
-        f.detach = lambda *args, **kwargs: None  # type: ignore
+        from colorama.initialise import wrap_stream

     except ImportError:
     except ImportError:

-        pass
-
-    return f
+        return f
+    else:
+        # Set `strip=False` to avoid needing to modify test_express_diff_with_color.
+        return wrap_stream(f, convert=None, strip=False, autoreset=False, wrap=True)

 
 
 def format_stdin_to_stdout(
 
 
 def format_stdin_to_stdout(


@@ -961,7 +1000,7 @@ def format_str(src_contents: str, *, mode: Mode) -> FileContent:
     allowed.  Example:
 
     >>> import black
     allowed.  Example:
 
     >>> import black

-    >>> print(black.format_str("def f(arg:str='')->None:...", mode=Mode()))
+    >>> print(black.format_str("def f(arg:str='')->None:...", mode=black.Mode()))

     def f(arg: str = "") -> None:
         ...
 
     def f(arg: str = "") -> None:
         ...
 


@@ -993,13 +1032,12 @@ def format_str(src_contents: str, *, mode: Mode) -> FileContent:
         versions = detect_target_versions(src_node)
     normalize_fmt_off(src_node)
     lines = LineGenerator(
         versions = detect_target_versions(src_node)
     normalize_fmt_off(src_node)
     lines = LineGenerator(

+        mode=mode,

         remove_u_prefix="unicode_literals" in future_imports
         or supports_feature(versions, Feature.UNICODE_LITERALS),
         remove_u_prefix="unicode_literals" in future_imports
         or supports_feature(versions, Feature.UNICODE_LITERALS),

-        is_pyi=mode.is_pyi,
-        normalize_strings=mode.string_normalization,

     )
     elt = EmptyLineTracker(is_pyi=mode.is_pyi)
     )
     elt = EmptyLineTracker(is_pyi=mode.is_pyi)

-    empty_line = Line()
+    empty_line = Line(mode=mode)

     after = 0
     split_line_features = {
         feature
     after = 0
     split_line_features = {
         feature


@@ -1435,6 +1473,7 @@ class BracketTracker:
 class Line:
     """Holds leaves and comments. Can be printed with `str(line)`."""
 
 class Line:
     """Holds leaves and comments. Can be printed with `str(line)`."""
 

+    mode: Mode

     depth: int = 0
     leaves: List[Leaf] = field(default_factory=list)
     # keys ordered like `leaves`
     depth: int = 0
     leaves: List[Leaf] = field(default_factory=list)
     # keys ordered like `leaves`


@@ -1442,6 +1481,7 @@ class Line:
     bracket_tracker: BracketTracker = field(default_factory=BracketTracker)
     inside_brackets: bool = False
     should_explode: bool = False
     bracket_tracker: BracketTracker = field(default_factory=BracketTracker)
     inside_brackets: bool = False
     should_explode: bool = False

+    magic_trailing_comma: Optional[Leaf] = None

 
     def append(self, leaf: Leaf, preformatted: bool = False) -> None:
         """Add a new `leaf` to the end of the line.
 
     def append(self, leaf: Leaf, preformatted: bool = False) -> None:
         """Add a new `leaf` to the end of the line.


@@ -1467,8 +1507,11 @@ class Line:
             )
         if self.inside_brackets or not preformatted:
             self.bracket_tracker.mark(leaf)
             )
         if self.inside_brackets or not preformatted:
             self.bracket_tracker.mark(leaf)

-            if self.maybe_should_explode(leaf):
-                self.should_explode = True
+            if self.mode.magic_trailing_comma:
+                if self.has_magic_trailing_comma(leaf):
+                    self.magic_trailing_comma = leaf
+            elif self.has_magic_trailing_comma(leaf, ensure_removable=True):
+                self.remove_trailing_comma()

         if not self.append_comment(leaf):
             self.leaves.append(leaf)
 
         if not self.append_comment(leaf):
             self.leaves.append(leaf)
 


@@ -1644,10 +1687,14 @@ class Line:
     def contains_multiline_strings(self) -> bool:
         return any(is_multiline_string(leaf) for leaf in self.leaves)
 
     def contains_multiline_strings(self) -> bool:
         return any(is_multiline_string(leaf) for leaf in self.leaves)
 

-    def maybe_should_explode(self, closing: Leaf) -> bool:
-        """Return True if this line should explode (always be split), that is when:
-        - there's a trailing comma here; and
-        - it's not a one-tuple.
+    def has_magic_trailing_comma(
+        self, 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
+        Additionally, if ensure_removable:
+        - it's not from square bracket indexing

         """
         if not (
             closing.type in CLOSING_BRACKETS
         """
         if not (
             closing.type in CLOSING_BRACKETS


@@ -1656,9 +1703,15 @@ class Line:
         ):
             return False
 
         ):
             return False
 

-        if closing.type in {token.RBRACE, token.RSQB}:
+        if closing.type == token.RBRACE:

             return True
 
             return True
 

+        if closing.type == token.RSQB:
+            if not ensure_removable:
+                return True
+            comma = self.leaves[-1]
+            return bool(comma.parent and comma.parent.type == syms.listmaker)
+

         if self.is_import:
             return True
 
         if self.is_import:
             return True
 


@@ -1736,9 +1789,11 @@ class Line:
 
     def clone(self) -> "Line":
         return Line(
 
     def clone(self) -> "Line":
         return Line(

+            mode=self.mode,

             depth=self.depth,
             inside_brackets=self.inside_brackets,
             should_explode=self.should_explode,
             depth=self.depth,
             inside_brackets=self.inside_brackets,
             should_explode=self.should_explode,

+            magic_trailing_comma=self.magic_trailing_comma,

         )
 
     def __str__(self) -> str:
         )
 
     def __str__(self) -> str:


@@ -1894,10 +1949,9 @@ class LineGenerator(Visitor[Line]):
     in ways that will no longer stringify to valid Python code on the tree.
     """
 
     in ways that will no longer stringify to valid Python code on the tree.
     """
 

-    is_pyi: bool = False
-    normalize_strings: bool = True
-    current_line: Line = field(default_factory=Line)
+    mode: Mode

     remove_u_prefix: bool = False
     remove_u_prefix: bool = False

+    current_line: Line = field(init=False)

 
     def line(self, indent: int = 0) -> Iterator[Line]:
         """Generate a line.
 
     def line(self, indent: int = 0) -> Iterator[Line]:
         """Generate a line.


@@ -1912,7 +1966,7 @@ class LineGenerator(Visitor[Line]):
             return  # Line is empty, don't emit. Creating a new one unnecessary.
 
         complete_line = self.current_line
             return  # Line is empty, don't emit. Creating a new one unnecessary.
 
         complete_line = self.current_line

-        self.current_line = Line(depth=complete_line.depth + indent)
+        self.current_line = Line(mode=self.mode, depth=complete_line.depth + indent)

         yield complete_line
 
     def visit_default(self, node: LN) -> Iterator[Line]:
         yield complete_line
 
     def visit_default(self, node: LN) -> Iterator[Line]:


@@ -1936,7 +1990,7 @@ class LineGenerator(Visitor[Line]):
                     yield from self.line()
 
             normalize_prefix(node, inside_brackets=any_open_brackets)
                     yield from self.line()
 
             normalize_prefix(node, inside_brackets=any_open_brackets)

-            if self.normalize_strings and node.type == token.STRING:
+            if self.mode.string_normalization and node.type == token.STRING:

                 normalize_string_prefix(node, remove_u_prefix=self.remove_u_prefix)
                 normalize_string_quotes(node)
             if node.type == token.NUMBER:
                 normalize_string_prefix(node, remove_u_prefix=self.remove_u_prefix)
                 normalize_string_quotes(node)
             if node.type == token.NUMBER:


@@ -1988,7 +2042,7 @@ class LineGenerator(Visitor[Line]):
 
     def visit_suite(self, node: Node) -> Iterator[Line]:
         """Visit a suite."""
 
     def visit_suite(self, node: Node) -> Iterator[Line]:
         """Visit a suite."""

-        if self.is_pyi and is_stub_suite(node):
+        if self.mode.is_pyi and is_stub_suite(node):

             yield from self.visit(node.children[2])
         else:
             yield from self.visit_default(node)
             yield from self.visit(node.children[2])
         else:
             yield from self.visit_default(node)


@@ -1997,7 +2051,7 @@ class LineGenerator(Visitor[Line]):
         """Visit a statement without nested statements."""
         is_suite_like = node.parent and node.parent.type in STATEMENT
         if is_suite_like:
         """Visit a statement without nested statements."""
         is_suite_like = node.parent and node.parent.type in STATEMENT
         if is_suite_like:

-            if self.is_pyi and is_stub_body(node):
+            if self.mode.is_pyi and is_stub_body(node):

                 yield from self.visit_default(node)
             else:
                 yield from self.line(+1)
                 yield from self.visit_default(node)
             else:
                 yield from self.line(+1)


@@ -2005,7 +2059,11 @@ class LineGenerator(Visitor[Line]):
                 yield from self.line(-1)
 
         else:
                 yield from self.line(-1)
 
         else:

-            if not self.is_pyi or not node.parent or not is_stub_suite(node.parent):
+            if (
+                not self.mode.is_pyi
+                or not node.parent
+                or not is_stub_suite(node.parent)
+            ):

                 yield from self.line()
             yield from self.visit_default(node)
 
                 yield from self.line()
             yield from self.visit_default(node)
 


@@ -2081,6 +2139,8 @@ class LineGenerator(Visitor[Line]):
 
     def __post_init__(self) -> None:
         """You are in a twisty little maze of passages."""
 
     def __post_init__(self) -> None:
         """You are in a twisty little maze of passages."""

+        self.current_line = Line(mode=self.mode)
+

         v = self.visit_stmt
         Ø: Set[str] = set()
         self.visit_assert_stmt = partial(v, keywords={"assert"}, parens={"assert", ","})
         v = self.visit_stmt
         Ø: Set[str] = set()
         self.visit_assert_stmt = partial(v, keywords={"assert"}, parens={"assert", ","})


@@ -2523,6 +2583,8 @@ def is_split_before_delimiter(leaf: Leaf, previous: Optional[Leaf] = None) -> Pr
 
 
 FMT_OFF = {"# fmt: off", "# fmt:off", "# yapf: disable"}
 
 
 FMT_OFF = {"# fmt: off", "# fmt:off", "# yapf: disable"}

+FMT_SKIP = {"# fmt: skip", "# fmt:skip"}
+FMT_PASS = {*FMT_OFF, *FMT_SKIP}

 FMT_ON = {"# fmt: on", "# fmt:on", "# yapf: enable"}
 
 
 FMT_ON = {"# fmt: on", "# fmt:on", "# yapf: enable"}
 
 


@@ -2577,7 +2639,7 @@ def list_comments(prefix: str, *, is_endmarker: bool) -> List[ProtoComment]:
     consumed = 0
     nlines = 0
     ignored_lines = 0
     consumed = 0
     nlines = 0
     ignored_lines = 0

-    for index, line in enumerate(prefix.split("\n")):
+    for index, line in enumerate(re.split("\r?\n", prefix)):

         consumed += len(line) + 1  # adding the length of the split '\n'
         line = line.lstrip()
         if not line:
         consumed += len(line) + 1  # adding the length of the split '\n'
         line = line.lstrip()
         if not line:


@@ -2650,7 +2712,7 @@ def transform_line(
     transformers: List[Transformer]
     if (
         not line.contains_uncollapsable_type_comments()
     transformers: List[Transformer]
     if (
         not line.contains_uncollapsable_type_comments()

-        and not line.should_explode
+        and not (line.should_explode or line.magic_trailing_comma)

         and (
             is_line_short_enough(line, line_length=mode.line_length, line_str=line_str)
             or line.contains_unsplittable_type_ignore()
         and (
             is_line_short_enough(line, line_length=mode.line_length, line_str=line_str)
             or line.contains_unsplittable_type_ignore()


@@ -3246,7 +3308,8 @@ class StringParenStripper(StringTransformer):
 
     Requirements:
         The line contains a string which is surrounded by parentheses and:
 
     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 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
               preceeded or followed by an operator with higher precedence than
               PERCENT.
             - If the target string contains a PERCENT, the brackets are not
               preceeded or followed by an operator with higher precedence than
               PERCENT.


@@ -3270,6 +3333,14 @@ class StringParenStripper(StringTransformer):
             if leaf.type != token.STRING:
                 continue
 
             if leaf.type != token.STRING:
                 continue
 

+            # If this is a "pointless" string...
+            if (
+                leaf.parent
+                and leaf.parent.parent
+                and leaf.parent.parent.type == syms.simple_stmt
+            ):
+                continue
+

             # Should be preceded by a non-empty LPAR...
             if (
                 not is_valid_index(idx - 1)
             # Should be preceded by a non-empty LPAR...
             if (
                 not is_valid_index(idx - 1)


@@ -3598,7 +3669,8 @@ class StringSplitter(CustomSplitMapMixin, BaseStringSplitter):
         MIN_SUBSTR_SIZE characters.
 
         The string will ONLY be split on spaces (i.e. each new substring should
         MIN_SUBSTR_SIZE characters.
 
         The string will ONLY be split on spaces (i.e. each new substring should

-        start with a space).
+        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
 
         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


@@ -3618,13 +3690,14 @@ class StringSplitter(CustomSplitMapMixin, BaseStringSplitter):
     MIN_SUBSTR_SIZE = 6
     # Matches an "f-expression" (e.g. {var}) that might be found in an f-string.
     RE_FEXPR = r"""
     MIN_SUBSTR_SIZE = 6
     # Matches an "f-expression" (e.g. {var}) that might be found in an f-string.
     RE_FEXPR = r"""

-    (?<!\{)\{
+    (?<!\{) (?:\{\{)* \{ (?!\{)

         (?:
             [^\{\}]
             | \{\{
             | \}\}
         (?:
             [^\{\}]
             | \{\{
             | \}\}

+            | (?R)

         )+?
         )+?

-    (?<!\})(?:\}\})*\}(?!\})
+    (?<!\}) \} (?:\}\})* (?!\})

     """
 
     def do_splitter_match(self, line: Line) -> TMatchResult:
     """
 
     def do_splitter_match(self, line: Line) -> TMatchResult:


@@ -3938,11 +4011,23 @@ class StringSplitter(CustomSplitMapMixin, BaseStringSplitter):
                 section of this classes' docstring would be be met by returning @i.
             """
             is_space = string[i] == " "
                 section of this classes' docstring would be be met by returning @i.
             """
             is_space = string[i] == " "

+
+            is_not_escaped = True
+            j = i - 1
+            while is_valid_index(j) and string[j] == "\\":
+                is_not_escaped = not is_not_escaped
+                j -= 1
+

             is_big_enough = (
                 len(string[i:]) >= self.MIN_SUBSTR_SIZE
                 and len(string[:i]) >= self.MIN_SUBSTR_SIZE
             )
             is_big_enough = (
                 len(string[i:]) >= self.MIN_SUBSTR_SIZE
                 and len(string[:i]) >= self.MIN_SUBSTR_SIZE
             )

-            return is_space and is_big_enough and not breaks_fstring_expression(i)
+            return (
+                is_space
+                and is_not_escaped
+                and is_big_enough
+                and not breaks_fstring_expression(i)
+            )

 
         # First, we check all indices BELOW @max_break_idx.
         break_idx = max_break_idx
 
         # First, we check all indices BELOW @max_break_idx.
         break_idx = max_break_idx


@@ -4298,9 +4383,11 @@ class StringParenWrapper(CustomSplitMapMixin, BaseStringSplitter):
         # `StringSplitter` will break it down further if necessary.
         string_value = LL[string_idx].value
         string_line = Line(
         # `StringSplitter` will break it down further if necessary.
         string_value = LL[string_idx].value
         string_line = Line(

+            mode=line.mode,

             depth=line.depth + 1,
             inside_brackets=True,
             should_explode=line.should_explode,
             depth=line.depth + 1,
             inside_brackets=True,
             should_explode=line.should_explode,

+            magic_trailing_comma=line.magic_trailing_comma,

         )
         string_leaf = Leaf(token.STRING, string_value)
         insert_str_child(string_leaf)
         )
         string_leaf = Leaf(token.STRING, string_value)
         insert_str_child(string_leaf)


@@ -4891,7 +4978,7 @@ def bracket_split_build_line(
     If `is_body` is True, the result line is one-indented inside brackets and as such
     has its first leaf's prefix normalized and a trailing comma added when expected.
     """
     If `is_body` is True, the result line is one-indented inside brackets and as such
     has its first leaf's prefix normalized and a trailing comma added when expected.
     """

-    result = Line(depth=original.depth)
+    result = Line(mode=original.mode, depth=original.depth)

     if is_body:
         result.inside_brackets = True
         result.depth += 1
     if is_body:
         result.inside_brackets = True
         result.depth += 1


@@ -4921,7 +5008,7 @@ def bracket_split_build_line(
         result.append(leaf, preformatted=True)
         for comment_after in original.comments_after(leaf):
             result.append(comment_after, preformatted=True)
         result.append(leaf, preformatted=True)
         for comment_after in original.comments_after(leaf):
             result.append(comment_after, preformatted=True)

-    if is_body and should_split_body_explode(result, opening_bracket):
+    if is_body and should_split(result, opening_bracket):

         result.should_explode = True
     return result
 
         result.should_explode = True
     return result
 


@@ -4963,7 +5050,9 @@ def delimiter_split(line: Line, features: Collection[Feature] = ()) -> Iterator[
         if bt.delimiter_count_with_priority(delimiter_priority) == 1:
             raise CannotSplit("Splitting a single attribute from its owner looks wrong")
 
         if bt.delimiter_count_with_priority(delimiter_priority) == 1:
             raise CannotSplit("Splitting a single attribute from its owner looks wrong")
 

-    current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
+    current_line = Line(
+        mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
+    )

     lowest_depth = sys.maxsize
     trailing_comma_safe = True
 
     lowest_depth = sys.maxsize
     trailing_comma_safe = True
 


@@ -4975,7 +5064,9 @@ def delimiter_split(line: Line, features: Collection[Feature] = ()) -> Iterator[
         except ValueError:
             yield current_line
 
         except ValueError:
             yield current_line
 

-            current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
+            current_line = Line(
+                mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
+            )

             current_line.append(leaf)
 
     for leaf in line.leaves:
             current_line.append(leaf)
 
     for leaf in line.leaves:


@@ -4999,7 +5090,9 @@ def delimiter_split(line: Line, features: Collection[Feature] = ()) -> Iterator[
         if leaf_priority == delimiter_priority:
             yield current_line
 
         if leaf_priority == delimiter_priority:
             yield current_line
 

-            current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
+            current_line = Line(
+                mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
+            )

     if current_line:
         if (
             trailing_comma_safe
     if current_line:
         if (
             trailing_comma_safe


@@ -5020,7 +5113,9 @@ def standalone_comment_split(
     if not line.contains_standalone_comments(0):
         raise CannotSplit("Line does not have any standalone comments")
 
     if not line.contains_standalone_comments(0):
         raise CannotSplit("Line does not have any standalone comments")
 

-    current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
+    current_line = Line(
+        mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
+    )

 
     def append_to_line(leaf: Leaf) -> Iterator[Line]:
         """Append `leaf` to current line or to new line if appending impossible."""
 
     def append_to_line(leaf: Leaf) -> Iterator[Line]:
         """Append `leaf` to current line or to new line if appending impossible."""


@@ -5030,7 +5125,9 @@ def standalone_comment_split(
         except ValueError:
             yield current_line
 
         except ValueError:
             yield current_line
 

-            current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
+            current_line = Line(
+                line.mode, depth=line.depth, inside_brackets=line.inside_brackets
+            )

             current_line.append(leaf)
 
     for leaf in line.leaves:
             current_line.append(leaf)
 
     for leaf in line.leaves:


@@ -5186,31 +5283,52 @@ def normalize_numeric_literal(leaf: Leaf) -> None:
         # Leave octal and binary literals alone.
         pass
     elif text.startswith("0x"):
         # Leave octal and binary literals alone.
         pass
     elif text.startswith("0x"):

-        # Change hex literals to upper case.
-        before, after = text[:2], text[2:]
-        text = f"{before}{after.upper()}"
+        text = format_hex(text)

     elif "e" in text:
     elif "e" in text:

-        before, after = text.split("e")
-        sign = ""
-        if after.startswith("-"):
-            after = after[1:]
-            sign = "-"
-        elif after.startswith("+"):
-            after = after[1:]
-        before = format_float_or_int_string(before)
-        text = f"{before}e{sign}{after}"
+        text = format_scientific_notation(text)

     elif text.endswith(("j", "l")):
     elif text.endswith(("j", "l")):

-        number = text[:-1]
-        suffix = text[-1]
-        # Capitalize in "2L" because "l" looks too similar to "1".
-        if suffix == "l":
-            suffix = "L"
-        text = f"{format_float_or_int_string(number)}{suffix}"
+        text = format_long_or_complex_number(text)

     else:
         text = format_float_or_int_string(text)
     leaf.value = text
 
 
     else:
         text = format_float_or_int_string(text)
     leaf.value = text
 
 

+def format_hex(text: str) -> str:
+    """
+    Formats a hexadecimal string like "0x12b3"
+
+    Uses lowercase because of similarity between "B" and "8", which
+    can cause security issues.
+    see: https://github.com/psf/black/issues/1692
+    """
+
+    before, after = text[:2], text[2:]
+    return f"{before}{after.lower()}"
+
+
+def format_scientific_notation(text: str) -> str:
+    """Formats a numeric string utilizing scentific notation"""
+    before, after = text.split("e")
+    sign = ""
+    if after.startswith("-"):
+        after = after[1:]
+        sign = "-"
+    elif after.startswith("+"):
+        after = after[1:]
+    before = format_float_or_int_string(before)
+    return f"{before}e{sign}{after}"
+
+
+def format_long_or_complex_number(text: str) -> str:
+    """Formats a long or complex string like `10L` or `10j`"""
+    number = text[:-1]
+    suffix = text[-1]
+    # Capitalize in "2L" because "l" looks too similar to "1".
+    if suffix == "l":
+        suffix = "L"
+    return f"{format_float_or_int_string(number)}{suffix}"
+
+

 def format_float_or_int_string(text: str) -> str:
     """Formats a float string like "1.0"."""
     if "." not in text:
 def format_float_or_int_string(text: str) -> str:
     """Formats a float string like "1.0"."""
     if "." not in text:


@@ -5291,58 +5409,80 @@ def convert_one_fmt_off_pair(node: Node) -> bool:
     for leaf in node.leaves():
         previous_consumed = 0
         for comment in list_comments(leaf.prefix, is_endmarker=False):
     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:
+            if comment.value not in FMT_PASS:
+                previous_consumed = comment.consumed
+                continue
+            # 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.value in FMT_PASS and comment.type != STANDALONE_COMMENT:
+                prev = preceding_leaf(leaf)
+                if prev:
+                    if comment.value in FMT_OFF and prev.type not in WHITESPACE:
+                        continue
+                    if comment.value in FMT_SKIP and prev.type in WHITESPACE:

                         continue
 
                         continue
 

-                ignored_nodes = list(generate_ignored_nodes(leaf))
-                if not ignored_nodes:
-                    continue
-
-                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: Optional[int] = 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
+            ignored_nodes = list(generate_ignored_nodes(leaf, comment))
+            if not ignored_nodes:
+                continue

 
 

-            previous_consumed = comment.consumed
+            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 = "".join(str(n) for n in ignored_nodes)
+            if comment.value in FMT_OFF:
+                hidden_value = comment.value + "\n" + hidden_value
+            if comment.value in FMT_SKIP:
+                hidden_value += "  " + comment.value
+            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: Optional[int] = 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

 
     return False
 
 
 
     return False
 
 

-def generate_ignored_nodes(leaf: Leaf) -> Iterator[LN]:
+def generate_ignored_nodes(leaf: Leaf, comment: ProtoComment) -> Iterator[LN]:

     """Starting from the container of `leaf`, generate all leaves until `# fmt: on`.
 
     """Starting from the container of `leaf`, generate all leaves until `# fmt: on`.
 

+    If comment is skip, returns leaf only.

     Stops at the end of the block.
     """
     container: Optional[LN] = container_of(leaf)
     Stops at the end of the block.
     """
     container: Optional[LN] = container_of(leaf)

+    if comment.value in FMT_SKIP:
+        prev_sibling = leaf.prev_sibling
+        if comment.value in leaf.prefix and prev_sibling is not None:
+            leaf.prefix = leaf.prefix.replace(comment.value, "")
+            siblings = [prev_sibling]
+            while (
+                "\n" not in prev_sibling.prefix
+                and prev_sibling.prev_sibling is not None
+            ):
+                prev_sibling = prev_sibling.prev_sibling
+                siblings.insert(0, prev_sibling)
+            for sibling in siblings:
+                yield sibling
+        elif leaf.parent is not None:
+            yield leaf.parent
+        return

     while container is not None and container.type != token.ENDMARKER:
         if is_fmt_on(container):
             return
     while container is not None and container.type != token.ENDMARKER:
         if is_fmt_on(container):
             return


@@ -5673,7 +5813,7 @@ def ensure_visible(leaf: Leaf) -> None:
         leaf.value = ")"
 
 
         leaf.value = ")"
 
 

-def should_split_body_explode(line: Line, opening_bracket: Leaf) -> bool:
+def should_split(line: Line, opening_bracket: Leaf) -> bool:

     """Should `line` be immediately split with `delimiter_split()` after RHS?"""
 
     if not (opening_bracket.parent and opening_bracket.value in "[{("):
     """Should `line` be immediately split with `delimiter_split()` after RHS?"""
 
     if not (opening_bracket.parent and opening_bracket.value in "[{("):


@@ -5694,7 +5834,7 @@ def should_split_body_explode(line: Line, opening_bracket: Leaf) -> bool:
         return False
 
     return max_priority == COMMA_PRIORITY and (
         return False
 
     return max_priority == COMMA_PRIORITY and (

-        trailing_comma
+        (line.mode.magic_trailing_comma and trailing_comma)

         # always explode imports
         or opening_bracket.parent.type in {syms.atom, syms.import_from}
     )
         # always explode imports
         or opening_bracket.parent.type in {syms.atom, syms.import_from}
     )


@@ -5809,7 +5949,7 @@ def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[Leaf
     """
 
     omit: Set[LeafID] = set()
     """
 
     omit: Set[LeafID] = set()

-    if not line.should_explode:
+    if not line.should_explode and not line.magic_trailing_comma:

         yield omit
 
     length = 4 * line.depth
         yield omit
 
     length = 4 * line.depth


@@ -5831,7 +5971,7 @@ def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[Leaf
             elif leaf.type in CLOSING_BRACKETS:
                 prev = line.leaves[index - 1] if index > 0 else None
                 if (
             elif leaf.type in CLOSING_BRACKETS:
                 prev = line.leaves[index - 1] if index > 0 else None
                 if (

-                    line.should_explode
+                    line.magic_trailing_comma

                     and prev
                     and prev.type == token.COMMA
                     and not is_one_tuple_between(
                     and prev
                     and prev.type == token.COMMA
                     and not is_one_tuple_between(


@@ -5859,7 +5999,7 @@ def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[Leaf
                 yield omit
 
             if (
                 yield omit
 
             if (

-                line.should_explode
+                line.magic_trailing_comma

                 and prev
                 and prev.type == token.COMMA
                 and not is_one_tuple_between(leaf.opening_bracket, leaf, line.leaves)
                 and prev
                 and prev.type == token.COMMA
                 and not is_one_tuple_between(leaf.opening_bracket, leaf, line.leaves)


@@ -6492,7 +6632,7 @@ def can_omit_invisible_parens(
 
     penultimate = line.leaves[-2]
     last = line.leaves[-1]
 
     penultimate = line.leaves[-2]
     last = line.leaves[-1]

-    if line.should_explode:
+    if line.should_explode or line.magic_trailing_comma:

         try:
             penultimate, last = last_two_except(line.leaves, omit=omit_on_explode)
         except LookupError:
         try:
             penultimate, last = last_two_except(line.leaves, omit=omit_on_explode)
         except LookupError:


@@ -6519,7 +6659,7 @@ def can_omit_invisible_parens(
             # unnecessary.
             return True
 
             # unnecessary.
             return True
 

-        if line.should_explode and penultimate.type == token.COMMA:
+        if line.magic_trailing_comma and penultimate.type == token.COMMA:

             # The rightmost non-omitted bracket pair is the one we want to explode on.
             return True
 
             # The rightmost non-omitted bracket pair is the one we want to explode on.
             return True
 


@@ -6669,8 +6809,8 @@ def filter_cached(cache: Cache, sources: Iterable[Path]) -> Tuple[Set[Path], Set
     """
     todo, done = set(), set()
     for src in sources:
     """
     todo, done = set(), set()
     for src in sources:

-        src = src.resolve()
-        if cache.get(src) != get_cache_info(src):
+        res_src = src.resolve()
+        if cache.get(str(res_src)) != get_cache_info(res_src):

             todo.add(src)
         else:
             done.add(src)
             todo.add(src)
         else:
             done.add(src)


@@ -6682,7 +6822,10 @@ def write_cache(cache: Cache, sources: Iterable[Path], mode: Mode) -> None:
     cache_file = get_cache_file(mode)
     try:
         CACHE_DIR.mkdir(parents=True, exist_ok=True)
     cache_file = get_cache_file(mode)
     try:
         CACHE_DIR.mkdir(parents=True, exist_ok=True)

-        new_cache = {**cache, **{src.resolve(): get_cache_info(src) for src in sources}}
+        new_cache = {
+            **cache,
+            **{str(src.resolve()): get_cache_info(src) for src in sources},
+        }

         with tempfile.NamedTemporaryFile(dir=str(cache_file.parent), delete=False) as f:
             pickle.dump(new_cache, f, protocol=4)
         os.replace(f.name, cache_file)
         with tempfile.NamedTemporaryFile(dir=str(cache_file.parent), delete=False) as f:
             pickle.dump(new_cache, f, protocol=4)
         os.replace(f.name, cache_file)


@@ -6738,13 +6881,33 @@ def is_docstring(leaf: Leaf) -> bool:
     return False
 
 
     return False
 
 

+def lines_with_leading_tabs_expanded(s: str) -> List[str]:
+    """
+    Splits string into lines and expands only leading tabs (following the normal
+    Python rules)
+    """
+    lines = []
+    for line in s.splitlines():
+        # Find the index of the first non-whitespace character after a string of
+        # whitespace that includes at least one tab
+        match = re.match(r"\s*\t+\s*(\S)", line)
+        if match:
+            first_non_whitespace_idx = match.start(1)
+
+            lines.append(
+                line[:first_non_whitespace_idx].expandtabs()
+                + line[first_non_whitespace_idx:]
+            )
+        else:
+            lines.append(line)
+    return lines
+
+

 def fix_docstring(docstring: str, prefix: str) -> str:
     # https://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation
     if not docstring:
         return ""
 def fix_docstring(docstring: str, prefix: str) -> str:
     # https://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation
     if not docstring:
         return ""

-    # Convert tabs to spaces (following the normal Python rules)
-    # and split into a list of lines:
-    lines = docstring.expandtabs().splitlines()
+    lines = lines_with_leading_tabs_expanded(docstring)

     # Determine minimum indentation (first line doesn't count):
     indent = sys.maxsize
     for line in lines[1:]:
     # Determine minimum indentation (first line doesn't count):
     indent = sys.maxsize
     for line in lines[1:]: