Add newline after module docstrings in preview style #8283
Conversation
Change ```python """Test docstring""" a = 1 ``` to ```python """Test docstring""" a = 1 ``` in preview style, but don't touch the docstring otherwise. Do we want to ask black to also format the content of module level docstrings? Seems inconsistent to me that we change function and class docstring indentation/contents but not module docstrings. Fixes #7995
konstin
added
formatter
| +++ Preview | ||
| @@ -1,4 +1,5 @@ | ||
| 0.1 | ||
| + |
There was a problem hiding this comment.
This should also be fixed by #8216
There was a problem hiding this comment.
Trying to understand, why / how is this happening?
There was a problem hiding this comment.
Ah, I see, there's a bug in try_from_docstring that's fixed in that PR. I'm just gonna copy that fix in here -- seems odd to commit without it.
There was a problem hiding this comment.
my plan was to merge the other one first and then rebase, but this does too
PR Check ResultsEcosystem✅ ecosystem check detected no format changes. |
| return match value { | ||
| Constant::Str(value) if !value.implicit_concatenated => Some(DocstringStmt(stmt)), | ||
| Constant::Bytes(value) if !value.implicit_concatenated => Some(DocstringStmt(stmt)), | ||
| _ => None, | ||
| }; |
There was a problem hiding this comment.
I don't think bytes can be used as docstrings, right?
$ cat src/play.py
b"docstring"
$ python
Python 3.11.3 (main, Apr 19 2023, 22:45:48) [Clang 16.0.1 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from src import play
>>> play.__doc__
>>>
$ cat src/play.py
"docstring"
$ python
Python 3.11.3 (main, Apr 19 2023, 22:45:48) [Clang 16.0.1 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from src import play
>>> play.__doc__
'docstring'
>>> There was a problem hiding this comment.
Thanks for making double check! psf/black#4002
We previously incorrectly treated byte strings in docstring position as docstrings because black does so (#8283 (comment), psf/black#4002), even CPython doesn't recognize them: ```console $ python3.12 Python 3.12.0 (main, Oct 6 2023, 17:57:44) [GCC 11.4.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> def f(): ... b""" a""" ... >>> print(str(f.__doc__)) None ```
We previously incorrectly treated byte strings in docstring position as docstrings because black does so (#8283 (comment), psf/black#4002), even CPython doesn't recognize them: ```console $ python3.12 Python 3.12.0 (main, Oct 6 2023, 17:57:44) [GCC 11.4.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> def f(): ... b""" a""" ... >>> print(str(f.__doc__)) None ``` <!-- Thank you for contributing to Ruff! To help us out with reviewing, please consider the following: - Does this pull request include a summary of the change? (See below.) - Does this pull request include a descriptive title? - Does this pull request include references to any relevant issues? -->
|
This conflicts with https://github.com/asottile/reorder-python-imports v3.12.0 which removes any blank lines between the module docstring and the import lines. i.e. ruff format in v0.3.0 has the same issue reported in black as psf/black#4175 which is currently unresolved. P.S. See also asottile/reorder-python-imports#366 - we can expect no fixes there 😞 Update: Consensus seems to be switch to isort instead. |
|
is there any config property which disables this behavior? |
No, there's no such configuration option. |
|
I'd like to have an option to disable this behavior. I didn't have this when using Black 24 with preview features on. |
|
@MichaReiser It looks like a newline is inserted when preview style is disabled. Is this intended? |
|
@MichaReiser Never mind. Just saw #9639. |
Change
to
in preview style, but don't touch the docstring otherwise.
Do we want to ask black to also format the content of module level docstrings? Seems inconsistent to me that we change function and class docstring indentation/contents but not module docstrings.
Fixes #7995