Explicitly annotate this with `Final[str]` to make it work in mypyc 1.0.0+. (#3645)

[etc/vim.git] / docs / the_black_code_style / future_style.md

diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index fab4bca120e634f26ec79ef4de9412c2de6196fa..bfab905b288182c3fa1c9d80058d1b3e2a90a9bb 100644 (file)
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -19,26 +19,39 @@ with make_context_manager1() as cm1, make_context_manager2() as cm2, make_contex
     ...  # nothing to split on - line too long
 ```
 
     ...  # nothing to split on - line too long
 ```
 

-So _Black_ will eventually format it like this:
+So _Black_ will, when we implement this, format it like this:

 
 ```py3
 with \
 
 ```py3
 with \

-     make_context_manager(1) as cm1, \
-     make_context_manager(2) as cm2, \
-     make_context_manager(3) as cm3, \
-     make_context_manager(4) as cm4 \
+     make_context_manager1() as cm1, \
+     make_context_manager2() as cm2, \
+     make_context_manager3() as cm3, \
+     make_context_manager4() as cm4 \

 :
     ...  # backslashes and an ugly stranded colon
 ```
 
 :
     ...  # backslashes and an ugly stranded colon
 ```
 

-Although when the target version is Python 3.9 or higher, _Black_ will use parentheses
-instead since they're allowed in Python 3.9 and higher.
+Although when the target version is Python 3.9 or higher, _Black_ uses parentheses
+instead in `--preview` mode (see below) since they're allowed in Python 3.9 and higher.
+
+An alternative to consider if the backslashes in the above formatting are undesirable is
+to use {external:py:obj}`contextlib.ExitStack` to combine context managers in the
+following way:
+
+```python
+with contextlib.ExitStack() as exit_stack:
+    cm1 = exit_stack.enter_context(make_context_manager1())
+    cm2 = exit_stack.enter_context(make_context_manager2())
+    cm3 = exit_stack.enter_context(make_context_manager3())
+    cm4 = exit_stack.enter_context(make_context_manager4())
+    ...
+```

 
 ## Preview style
 
 Experimental, potentially disruptive style changes are gathered under the `--preview`
 CLI flag. At the end of each year, these changes may be adopted into the default style,
 
 ## Preview style
 
 Experimental, potentially disruptive style changes are gathered under the `--preview`
 CLI flag. At the end of each year, these changes may be adopted into the default style,

-as described in [The Black Code Style](./index.rst). Because the functionality is
+as described in [The Black Code Style](index.md). Because the functionality is

 experimental, feedback and issue reports are highly encouraged!
 
 ### Improved string processing
 experimental, feedback and issue reports are highly encouraged!
 
 ### Improved string processing


@@ -50,71 +63,98 @@ limit. Line continuation backslashes are converted into parenthesized strings.
 Unnecessary parentheses are stripped. The stability and status of this feature is
 tracked in [this issue](https://github.com/psf/black/issues/2188).
 
 Unnecessary parentheses are stripped. The stability and status of this feature is
 tracked in [this issue](https://github.com/psf/black/issues/2188).
 

-### Removing newlines in the beginning of code blocks
+### Improved line breaks

 
 

-_Black_ will remove newlines in the beginning of new code blocks, i.e. when the
-indentation level is increased. For example:
+For assignment expressions, _Black_ now prefers to split and wrap the right side of the
+assignment instead of left side. For example:

 
 ```python
 
 ```python

-def my_func():
-
-    print("The line above me will be deleted!")
+some_dict[
+    "with_a_long_key"
+] = some_looooooooong_module.some_looooooooooooooong_function_name(
+    first_argument, second_argument, third_argument
+)

 ```
 
 will be changed to:
 
 ```python
 ```
 
 will be changed to:
 
 ```python

-def my_func():
-    print("The line above me will be deleted!")
+some_dict["with_a_long_key"] = (
+    some_looooooooong_module.some_looooooooooooooong_function_name(
+        first_argument, second_argument, third_argument
+    )
+)

 ```
 
 ```
 

-This new feature will be applied to **all code blocks**: `def`, `class`, `if`, `for`,
-`while`, `with`, `case` and `match`.
-

 ### Improved parentheses management
 
 ### Improved parentheses management
 

-_Black_ will format parentheses around return annotations similarly to other sets of
-parentheses. For example:
+For dict literals with long values, they are now wrapped in parentheses. Unnecessary
+parentheses are now removed. For example:

 
 ```python
 
 ```python

-def foo() -> (int):
-    ...
-
-def foo() -> looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong:
-    ...
+my_dict = {
+    "a key in my dict": a_very_long_variable
+    * and_a_very_long_function_call()
+    / 100000.0,
+    "another key": (short_value),
+}

 ```
 
 will be changed to:
 
 ```python
 ```
 
 will be changed to:
 
 ```python

-def foo() -> int:
-    ...
+my_dict = {
+    "a key in my dict": (
+        a_very_long_variable * and_a_very_long_function_call() / 100000.0
+    ),
+    "another key": short_value,
+}
+```

 
 

+### Improved multiline string handling

 
 

-def foo() -> (
-    looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong
-):
-    ...
-```
+_Black_ is smarter when formatting multiline strings, especially in function arguments,
+to avoid introducing extra line breaks. Previously, it would always consider multiline
+strings as not fitting on a single line. With this new feature, _Black_ looks at the
+context around the multiline string to decide if it should be inlined or split to a
+separate line. For example, when a multiline string is passed to a function, _Black_
+will only split the multiline string if a line is too long or if multiple arguments are
+being passed.

 
 

-And, extra parentheses in `await` expressions and `with` statements are removed. For
-example:
+For example, _Black_ will reformat

 
 ```python
 
 ```python

-with ((open("bla.txt")) as f, open("x")):
-    ...
+textwrap.dedent(
+    """\
+    This is a
+    multiline string
+"""
+)
+```
+
+to:

 
 

-async def main():
-    await (asyncio.sleep(1))
+```python
+textwrap.dedent("""\
+    This is a
+    multiline string
+""")

 ```
 
 ```
 

-will be changed to:
+And:

 
 ```python
 
 ```python

-with open("bla.txt") as f, open("x"):
-    ...
+MULTILINE = """
+foobar
+""".replace(
+    "\n", ""
+)
+```

 
 

+to:

 
 

-async def main():
-    await asyncio.sleep(1)
+```python
+MULTILINE = """
+foobar
+""".replace("\n", "")

 ```
 ```