Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Black fails on docstring with linebreak #3727

Closed
DiscoveryFox opened this issue Jun 9, 2023 · 6 comments · Fixed by #4008
Closed

Black fails on docstring with linebreak #3727

DiscoveryFox opened this issue Jun 9, 2023 · 6 comments · Fixed by #4008
Labels
C: crash Black is crashing F: docstrings How we format docstrings T: bug Something isn't working

Comments

@DiscoveryFox
Copy link

Describe the bug

When you have a docstring and add a \ at the end of the line to get a line break black can't deal with it.

To Reproduce

For example, take this code:

class Database:
    """
    ## Database Base Class
    The custom ORM specificaly created for the [gitlab-audit project](https://gitlab.itwm.fraunhofer.de/it-linux/gitlab-audit).
    Provides a lot of functions to interact with the database in a pythonic, easy and
    fast way.
    """
    def __init__(self):
        ...

It works completely fine(im on python version 3.9.7). But when I now add a \ to get a linebreak it stops working

class Database:
    """
    ## Database Base Class
    The custom ORM specificaly created for the [gitlab-audit project](https://gitlab.itwm.fraunhofer.de/it-linux/gitlab-audit).\ 
    Provides a lot of functions to interact with the database in a pythonic, easy and
    fast way.
    """
    def __init__(self):
        ...

The resulting error is:

error: cannot format /u/f/fuchsf/Documents/gitlab-audit/tools/database_helper.py: INTERNAL ERROR: Black produced code that is not equivalent to the source.  Please report a bug on https://github.com/psf/black/issues.  This diff might be helpful: /var/tmp/blk_jkcx46wd.log

Content of /var/tmp/blk_jkcx46wd.log:

--- src
+++ dst
@@ -2569,11 +2569,11 @@
           value=
             Constant(
               kind=
                 None,  # NoneType
               value=
-                '## Database Base Class\nThe custom ORM specificaly created for the [gitlab-audit project](https://gitlab.itwm.fraunhofer.de/it-linux/gitlab-audit).\\\nProvides a lot of functions to interact with the database in a pythonic, easy and\nfast way.',  # str
+                '## Database Base Class\nThe custom ORM specificaly created for the [gitlab-audit project](https://gitlab.itwm.fraunhofer.de/it-linux/gitlab-audit).    Provides a lot of functions to interact with the database in a pythonic, easy and\nfast way.',  # str
             )  # /Constant
         )  # /Expr
         FunctionDef(
           args=
             arguments(

Expected behavior

Black usually shouldn't mess with docstrings since they are not part of the source code. And can sometimes be confusing semi-code. It should just work.
Environment

  • Black's version: 23.3.0
  • OS and Python version: Red Hat Linux with Python 3.9.7 in a Virtualenv

Additional context

Sadly I can't share anymore code since it's from a closed codebase but if there are any more questions I will try to answer as good as I can

@DiscoveryFox DiscoveryFox added the T: bug Something isn't working label Jun 9, 2023
@JelleZijlstra JelleZijlstra added F: docstrings How we format docstrings C: crash Black is crashing labels Jun 9, 2023
@henriholopainen
Copy link
Contributor

Can't repro on current main nor on 23.3.0 running Python 3.9.16.

% black --version                  
black, 23.3.0 (compiled: yes)
Python (CPython) 3.9.16

% black --diff issue_3727.py
--- issue_3727.py	2023-10-29 19:41:26.784549 +0000
+++ issue_3727.py	2023-10-29 19:42:14.183941 +0000
@@ -3,7 +3,8 @@
     ## Database Base Class
     The custom ORM specificaly created for the [gitlab-audit project](https://gitlab.itwm.fraunhofer.de/it-linux/gitlab-audit).\
     Provides a lot of functions to interact with the database in a pythonic, easy and
     fast way.
     """
+
     def __init__(self):
         print("foo")
would reformat issue_3727.py

All done! ✨ 🍰 ✨
1 file would be reformatted.

There also seems to be plenty of tests for trailing backslash in docstrings. So maybe this should be closed?

@hauntsaninja
Copy link
Collaborator

Interesting, I can still repro on f7cbe4a:

(black-drsy) ~/dev/black main λ python --version         
Python 3.11.5
(black-drsy) ~/dev/black main λ cat test.py
class Database:
    """
    ## Database Base Class
    The custom ORM specificaly created for the [gitlab-audit project](https://gitlab.itwm.fraunhofer.de/it-linux/gitlab-audit).\ 
    Provides a lot of functions to interact with the database in a pythonic, easy and
    fast way.
    """
    def __init__(self):
        ...
(black-drsy) ~/dev/black main λ python -m black test.py --check
error: cannot format test.py: INTERNAL ERROR: Black produced code that is not equivalent to the source.  Please report a bug on https://github.com/psf/black/issues.  This diff might be helpful: /var/folders/0y/wt5dx2vj6t16wq97pglrkynm0000gp/T/blk_b16gcy_0.log

Oh no! 💥 💔 💥
1 file would fail to reformat.

@hauntsaninja
Copy link
Collaborator

hauntsaninja commented Oct 30, 2023

Playground link

@JelleZijlstra
Copy link
Collaborator

I can also still reproduce it, both on current main and on 23.3.0 as @henriholopainen tried, and both with and without --preview.

@henriholopainen
Copy link
Contributor

Ok, apparently the issue is a trailing whitespace after the backslash. I can try and take a look at this tomorrow. Thanks for the repro steps all!

@henriholopainen
Copy link
Contributor

While this was a true error, the error was rooted in the trailing whitespace, which probably wasn't intentional. Fix in 4008.

JelleZijlstra pushed a commit that referenced this issue Oct 31, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C: crash Black is crashing F: docstrings How we format docstrings T: bug Something isn't working
Projects
None yet
4 participants