""" Leading summary whitespace (as in this issue title)."""
olibre opened this issue · comments
For better readability, some people prefer inserting a space between the triple quotes """ and the summary text:
def is_ascii(text):
""" Checks if contains only ASCII characters."""
return all(ord(letter) < 128 for letter in text)
The leading whitespace:
🡇
""" Checks if contains only ASCII characters."""
Without that whitespace:
"""Checks if contains only ASCII characters."""
We may add an option --leading-summary-space or --pre-summary-space or --space-before-summary or --space-after-triple-quotes... What option name do you prefer?
Attention, this option has no effect on multi-lines docstring when --pre-summary-newline is used.
Thanks
--pre-summary-space matches the --pre-summary-newline option for naming, so would probably be the least confusing.
@ndevenish Made a pull request adding this option. Mind trying it out?
😮 I have seen extra spaces around a one-line docstring, or extra leading space on the first line of a multiline docstring, but didn’t know there was a style of one-line docstring with leading space but no trailing space.
Note that black inserts the leading whitespace. Therefore if you use both black and docformatter you'll be in formatting limbo.
See psf/black#2912
Also worth pointing out https://docs.python.org/3/library/inspect.html#inspect.cleandoc strips this, so it should have no semantic difference (help docs do not have the whitespace).
Last comment, black only inserts the leading space if the first character is the quote, so it's obvious there's an extra quote. Otherwise there isn't a leading space.
E.g.
# Adds leading space
""" "I'm quoted"."""
# But also doesn't
"""I'm not quoted."""So applying the space everywhere would still land you in limbo.
@thejcannon thanks for pointing this out.
PR #46 is submitted to add the leading space. Once that PR is merged, using the --pre-summary-space option will maintain the black-inserted space. For those who prefer the non-space formatting they would need to run black first, then docformatter. I've asked the #46 pull requester to address this interaction in the README.
Closed by #46