]> git.madduck.net Git - etc/vim.git/blobdiff - docs/the_black_code_style/future_style.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Bump peter-evans/create-or-update-comment from 2.1.0 to 2.1.1 (#3548)
[etc/vim.git] / docs / the_black_code_style / future_style.md
index 9ca260fc0add91c82ed4b1640a6114f890a851f6..96abc99ef41335cefd7d88fab8245156f0d2ad64 100644 (file)
@@ -31,8 +31,8 @@ with \
     ...  # backslashes and an ugly stranded colon
 ```
 
-Although when the target version is Python 3.9 or higher, _Black_ will, when we
-implement this, 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
@@ -63,92 +63,99 @@ 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).
 
-### Improved empty line management
+### Improved line breaks
 
-1.  _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
-    def my_func():
-
-        print("The line above me will be deleted!")
-    ```
-
-    will be changed to:
-
-    ```python
-    def my_func():
-        print("The line above me will be deleted!")
-    ```
-
-    This new feature will be applied to **all code blocks**: `def`, `class`, `if`,
-    `for`, `while`, `with`, `case` and `match`.
-
-2.  _Black_ will enforce empty lines before classes and functions with leading comments.
-    For example:
-
-    ```python
-    some_var = 1
-    # Leading sticky comment
-    def my_func():
-        ...
-    ```
-
-    will be changed to:
-
-    ```python
-    some_var = 1
+```python
+some_dict[
+    "with_a_long_key"
+] = some_looooooooong_module.some_looooooooooooooong_function_name(
+    first_argument, second_argument, third_argument
+)
+```
 
+will be changed to:
 
-    # Leading sticky comment
-    def my_func():
-        ...
-    ```
+```python
+some_dict["with_a_long_key"] = (
+    some_looooooooong_module.some_looooooooooooooong_function_name(
+        first_argument, second_argument, third_argument
+    )
+)
+```
 
 ### 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
-def foo() -> (int):
-    ...
-
-def foo() -> looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong:
-    ...
+my_dict = {
+    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
-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
-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
-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", "")
 ```