... # 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 \
... # 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
...
```
+(labels/preview-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
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():
+```python
+some_dict[
+ "with_a_long_key"
+] = some_looooooooong_module.some_looooooooooooooong_function_name(
+ first_argument, second_argument, third_argument
+)
+```
- print("The line above me will be deleted!")
- ```
+will be changed to:
- will be changed to:
+```python
+some_dict["with_a_long_key"] = (
+ some_looooooooong_module.some_looooooooooooooong_function_name(
+ first_argument, second_argument, third_argument
+ )
+)
+```
- ```python
- def my_func():
- print("The line above me will be deleted!")
- ```
+### Improved parentheses management
- This new feature will be applied to **all code blocks**: `def`, `class`, `if`,
- `for`, `while`, `with`, `case` and `match`.
+For dict literals with long values, they are now wrapped in parentheses. Unnecessary
+parentheses are now removed. For example:
-2. _Black_ will enforce empty lines before classes and functions with leading comments.
- For example:
+```python
+my_dict = {
+ "a key in my dict": a_very_long_variable
+ * and_a_very_long_function_call()
+ / 100000.0,
+ "another key": (short_value),
+}
+```
- ```python
- some_var = 1
- # Leading sticky comment
- def my_func():
- ...
- ```
+will be changed to:
- will be changed to:
+```python
+my_dict = {
+ "a key in my dict": (
+ a_very_long_variable * and_a_very_long_function_call() / 100000.0
+ ),
+ "another key": short_value,
+}
+```
- ```python
- some_var = 1
+### Improved multiline string handling
+_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.
- # Leading sticky comment
- def my_func():
- ...
- ```
+For example, _Black_ will reformat
-### Improved parentheses management
+```python
+textwrap.dedent(
+ """\
+ This is a
+ multiline string
+"""
+)
+```
-_Black_ will format parentheses around return annotations similarly to other sets of
-parentheses. For example:
+to:
```python
-def foo() -> (int):
- ...
+textwrap.dedent("""\
+ This is a
+ multiline string
+""")
+```
-def foo() -> looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong:
- ...
+And:
+
+```python
+MULTILINE = """
+foobar
+""".replace(
+ "\n", ""
+)
```
-will be changed to:
+to:
```python
-def foo() -> int:
- ...
+MULTILINE = """
+foobar
+""".replace("\n", "")
+```
+Implicit multiline strings are special, because they can have inline comments. Strings
+without comments are merged, for example
-def foo() -> (
- looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong
-):
- ...
+```python
+s = (
+ "An "
+ "implicit "
+ "multiline "
+ "string"
+)
```
-And, extra parentheses in `await` expressions and `with` statements are removed. For
-example:
+becomes
```python
-with ((open("bla.txt")) as f, open("x")):
- ...
+s = "An implicit multiline string"
+```
+
+A comment on any line of the string (or between two string lines) will block the
+merging, so
-async def main():
- await (asyncio.sleep(1))
+```python
+s = (
+ "An " # Important comment concerning just this line
+ "implicit "
+ "multiline "
+ "string"
+)
```
-will be changed to:
+and
```python
-with open("bla.txt") as f, open("x"):
- ...
+s = (
+ "An "
+ "implicit "
+ # Comment in between
+ "multiline "
+ "string"
+)
+```
+will not be merged. Having the comment after or before the string lines (but still
+inside the parens) will merge the string. For example
-async def main():
- await asyncio.sleep(1)
+```python
+s = ( # Top comment
+ "An "
+ "implicit "
+ "multiline "
+ "string"
+ # Bottom comment
+)
+```
+
+becomes
+
+```python
+s = ( # Top comment
+ "An implicit multiline string"
+ # Bottom comment
+)
```
projects / etc / vim.git / blobdiff