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

Unable to include empty docstring #2168

Closed
sbliven opened this issue Apr 29, 2021 · 3 comments · Fixed by #2249
Closed

Unable to include empty docstring #2168

sbliven opened this issue Apr 29, 2021 · 3 comments · Fixed by #2249
Labels
F: strings Related to our handling of strings T: bug Something isn't working

Comments

@sbliven
Copy link

sbliven commented Apr 29, 2021

Empty docstrings are used by sphinx to indicate methods that should not be included in the documentation. However, as of 21.4b0 black reformats empty docstrings to contain a space.

To Reproduce:
Source:

def foo():
    """"""
    ...

gets reformatted to

def foo():
    """ """
    ...

Expected behavior I'm generally supportive of the style changes introduced in #1740. However, in this case black is changing the code in a meaningful way. I suggest that empty docstrings be ignored as a special case. I am agnostic on whether the empty docstring should be spelled "" or """""".

Environment:

  • Version: 21.4b2
  • OS and Python version: debian 10/Python 3.7.10

Does this bug also happen on master? Yes

@sbliven sbliven added the T: bug Something isn't working label Apr 29, 2021
sbliven added a commit to sbliven/rcsbsearch that referenced this issue Apr 29, 2021
Black 21.4b0 introduced a change in how docstrings are handled. This
breaks removing methods for sphinx.
See psf/black#2168

This change should fix travis, which has been failing since the 21.4b0
release.
@JelleZijlstra
Copy link
Collaborator

See #2150 for some similar previous discussion. I'm supportive of leaving empty docstrings alone to support this use case.

@sbliven
Copy link
Author

sbliven commented May 1, 2021

See #2150 for some similar previous discussion. I'm supportive of leaving empty docstrings alone to support this use case.

If #2150 resolves in favor of reducing AST modifications that would certainly fix this bug. However a special case allowing empty docstrings would be sufficient for my use case.

@ichard26 ichard26 added the F: strings Related to our handling of strings label May 6, 2021
@sethmlarson
Copy link
Member

sethmlarson commented May 21, 2021

This is impacting the urllib3 documentation, we use an empty docstring to avoid having subclass methods from Python's http.client.HTTPConnection that aren't relevant to our users show up in our documentation generated via autodoc.

Reference: urllib3/urllib3#2239

JelleZijlstra pushed a commit that referenced this issue May 25, 2021
Resolves #2168 by disabling the insertion of a " " when the docstring is entirely empty.

Note that this PR is focussed only on the case of empty docstrings. In particular this does not make any changes to the behaviour that a " " is inserted if a non-empty docstring begins with the quoting character. That is, black still prefers:

    """ "something" """

to:

    """"something" """

and that:

    """"Something""""

is not a legal docstring.
ncoish pushed a commit to ncoish/rcsbsearch that referenced this issue Jul 13, 2022
Black 21.4b0 introduced a change in how docstrings are handled. This
breaks removing methods for sphinx.
See psf/black#2168

This change should fix travis, which has been failing since the 21.4b0
release.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
F: strings Related to our handling of strings T: bug Something isn't working
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants