Python Forum
a longer docstring - Printable Version

+- Python Forum (https://python-forum.io)
+-- Forum: Python Coding (https://python-forum.io/forum-7.html)
+--- Forum: General Coding Help (https://python-forum.io/forum-8.html)
+--- Thread: a longer docstring (/thread-38035.html)

a longer docstring - Skaperen - Aug-24-2022

a function i am creating needs a longer docstring. it's not huge, but it is longer than 80 characters. to stay all on one line, it will need to be around 120 characters long. that or it needs to be split to two lines in a way that still leaves just one line in the string.

i am wondering what is the common way to do this. using triple quotes will cause two lines in the string. or should this be done with just one quote?

RE: a longer docstring - Gribouillis - Aug-24-2022

I've been experimenting and you can use parentheses and implicit string concatenation
>>> def func():
...     ("This is the beginning of a very long docstring which must stand on one line"
...     " now the rest of this very long docstring hope it will be allright.")
...     print('Hello from func()')
... 
>>> func()
Hello from func()
>>> func.__doc__
'This is the beginning of a very long docstring which must stand on one line now the rest of this very long docstring hope it will be allright.'
The uncommon part is that usually docstrings have a reasonably sized first line and may have other lines.

RE: a longer docstring - Skaperen - Aug-25-2022

that looks like a nice way to code all docstrings, just to be consistent between functions. when both parenthesis are on the same line with just one literal string, they have no real effect.

RE: a longer docstring - Gribouillis - Aug-25-2022

One can also use the backslash as a line continuation character
>>> def func():
...     "The first part of the docstring,"\
...     " now the rest of it,"\
...     " and some more."
...     pass
... 
>>> func()
>>> func.__doc__
'The first part of the docstring, now the rest of it, and some more.'
An even wilder option
>>> def func():
...     "spam \
... ham \
... eggs"
...     print('Hi')
... 
>>> func()
Hi
>>> func.__doc__
'spam ham eggs'
>>>


RE: a longer docstring - perfringo - Aug-25-2022

I prefer to stick to conventions. PEP8 for line length and PEP257 Docstring Conventions for docstring. If you don't follow the first then you will face problems with implementing the second.

RE: a longer docstring - Gribouillis - Aug-25-2022

(Aug-25-2022, 01:40 PM)perfringo Wrote: I prefer to stick to conventions. PEP8
This is probably the most reasonable thing to do, however when I started programming Python more than 25 years ago, there was no PEP8, we lived in Python's paradise, therefore I feel no guilt at all in breaking all these rules that were invented later. There was really a huge sense of freedom in the small Python community at that time.

Also note that subjecting every Python software to follow PEP8 is an abuse of PEP8. Indeed, it was only intended as a style guide for developers of the standard library. GvR was a benevolent dictator but not a megalomaniac.

RE: a longer docstring - perfringo - Aug-25-2022

Docstrings and their conventions are important when you write code for others to read/use. Like PEP257 mentions:

Quote:But some software (such as the Docutils docstring processing system PEP 256, PEP 258) will be aware of the conventions, so following them will get you the best results.

/.../

Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line.

For personal project you do whatever pleases you Smile

RE: a longer docstring - Gribouillis - Aug-25-2022

PEP8 Wrote:Many projects have their own coding style guidelines. In the event of any conflicts, such project-specific guides take precedence for that project.
This means that any project can do whatever pleases them.
PEP257 Wrote:“A universal convention supplies all of maintainability, clarity, consistency, and a foundation for good programming habits too. What it doesn’t do is insist that you follow it against your will. That’s Python!”
—Tim Peters on comp.lang.python, 2001-06-16
For me, Python still rhymes with freedom.

RE: a longer docstring - Skaperen - Aug-25-2022

(Aug-25-2022, 01:40 PM)perfringo Wrote: I prefer to stick to conventions.
what is the convention for a case of staying within 71 columns per line in the coding and having up to 120 characters of text for a docstring?