pydoc preference for triple double over triple single quotes -- anyreason?

[Brian van den Broek]

Hi all,

I'm posting partly so my problem and solution might be more easily
found by google, and partly out of mere curiosity.

I've just spent a frustrating bit of time figuring out why pydoc
didn't extract a description from my module docstrings. Even though I
had a well formed docstring (one line, followed by a blank line,
followed by the rest of the docstring), when I ran Module docs, my
modules showed up as having "no description". ("Module docs" referring
to the shortcut installed on Windows that launches the pydoc server.)

It turns out that I was using '''triple single quotes''' and pydoc
only pulls a description out from module docstrings that are formatted
in """triple double quotes""". I've poked about with google, and
cannot find any explanation of why pydoc should treat the two cases
differently. Anyone have an idea?

I do see that both <http://www.python.org/peps/pep-0008.html> -- Style
Guide for Python Code and <http://www.python.org/peps/pep-0257.html>
-- Docstring Conventions suggest triple double, so I guess it is my
fault. But still, those PEP's have the tone of suggestions, and since
the two quoting schemes are semantically equivalent . . .

I do prefer the look of triple-single, but oh well. My attempts to
google for an answer didn't come up with anything, so perhaps this
post will help someone else, if nothing else :-)

Best to all,

Brian vdB

[Thomas Rast]

Brian van den Broek <bv****@po-box.mcgill.ca> writes:

It turns out that I was using '''triple single quotes''' and pydoc
only pulls a description out from module docstrings that are formatted
in """triple double quotes""". I've poked about with google, and
cannot find any explanation of why pydoc should treat the two cases
differently. Anyone have an idea?

Maybe because some editors, e.g. Emacs, do not (cannot) properly
handle triple quotes in syntax analysis and highlighting. Instead,
the quotes are treated as ordinary quotes, which breaks

'''This doesn't work'''

but not

"""This'll work"""

due to the apostrophe. pydoc then probably decided to follow PEP 257
which says

For consistency, always use """triple double quotes""" around
docstrings.
[http://www.python.org/peps/pep-0257.html]

- Thomas

--
If you want to reply by mail, substitute my first and last name for
'foo' and 'bar', respectively, and remove '.invalid'.

[Kent Johnson]

Brian van den Broek wrote:

Hi all,

I'm posting partly so my problem and solution might be more easily found
by google, and partly out of mere curiosity.

I've just spent a frustrating bit of time figuring out why pydoc didn't
extract a description from my module docstrings. Even though I had a
well formed docstring (one line, followed by a blank line, followed by
the rest of the docstring), when I ran Module docs, my modules showed up
as having "no description". ("Module docs" referring to the shortcut
installed on Windows that launches the pydoc server.)

?? It works for me with triple-single quoted strings...from a quick look it appears that pydoc uses
inspect which looks at the __doc__ attribute; do your modules have __doc__ attributes?

Kent

[Brian van den Broek]

Kent Johnson said unto the world upon 2005-04-16 16:41:

Brian van den Broek wrote:

Hi all,

I'm posting partly so my problem and solution might be more easily
found by google, and partly out of mere curiosity.

I've just spent a frustrating bit of time figuring out why pydoc
didn't extract a description from my module docstrings. Even though I
had a well formed docstring (one line, followed by a blank line,
followed by the rest of the docstring), when I ran Module docs, my
modules showed up as having "no description". ("Module docs" referring
to the shortcut installed on Windows that launches the pydoc server.)

?? It works for me with triple-single quoted strings...from a quick look
it appears that pydoc uses inspect which looks at the __doc__ attribute;
do your modules have __doc__ attributes?

Kent

Thanks for the reply, Kent. (Also to Thomas in another reply addressed
below.)

Kent, that's odd. My module does have a valid docstring and hence a
__doc__ attribute (I did explicitly check). help(my_module) works fine
at the prompt. It is just the results list in the TKinter interface to
the pydoc server application that doesn't seem to pick up my module's
description (in the first line of its docstring) when the docstring is
triple-single quoted.

Either way, it's no big deal; my post was at least as much to have a
googleable record of the situation as to figure out why. That said, it
still does puzzle me that the pydoc server treats the two styles of
triple quoted docstrings differently on my system (Python 2.4.1,
Windows Me).

Thomas suggested the preference might be related to Emacs
behaviour--that is something I know little about :-)

He also suggested that it could be that pydoc is following the PEP 257
<http://www.python.org/peps/pep-0257.html> recommendation to use
triple-double quoting. That might be, but if that's the explanation,
it just pushes the puzzle up a level for me :-)

Anyway, thanks again to both,

Brian vdB

[Kent Johnson]

Brian van den Broek wrote:

Kent Johnson said unto the world upon 2005-04-16 16:41:

Brian van den Broek wrote:

I've just spent a frustrating bit of time figuring out why pydoc
didn't extract a description from my module docstrings. Even though I
had a well formed docstring (one line, followed by a blank line,
followed by the rest of the docstring), when I ran Module docs, my
modules showed up as having "no description". ("Module docs"
referring to the shortcut installed on Windows that launches the
pydoc server.)

?? It works for me with triple-single quoted strings...from a quick
look it appears that pydoc uses inspect which looks at the __doc__
attribute; do your modules have __doc__ attributes?

Kent, that's odd. My module does have a valid docstring and hence a
__doc__ attribute (I did explicitly check). help(my_module) works fine
at the prompt. It is just the results list in the TKinter interface to
the pydoc server application that doesn't seem to pick up my module's
description (in the first line of its docstring) when the docstring is
triple-single quoted.

I'm not sure what you mean by "the results list in the TKinter interface to the pydoc server". I ran
the server, clicked "open browser" and browsed to a module in site-packages; that worked fine for me
under Win2K and Python 2.4.1.

Kent

[Brian van den Broek]

Kent Johnson said unto the world upon 2005-04-17 16:17:

Brian van den Broek wrote:

Kent Johnson said unto the world upon 2005-04-16 16:41:

Brian van den Broek wrote:

I've just spent a frustrating bit of time figuring out why pydoc
didn't extract a description from my module docstrings. Even though
I had a well formed docstring (one line, followed by a blank line,
followed by the rest of the docstring), when I ran Module docs, my
modules showed up as having "no description". ("Module docs"
referring to the shortcut installed on Windows that launches the
pydoc server.)
?? It works for me with triple-single quoted strings...from a quick
look it appears that pydoc uses inspect which looks at the __doc__
attribute; do your modules have __doc__ attributes?

Kent, that's odd. My module does have a valid docstring and hence a
__doc__ attribute (I did explicitly check). help(my_module) works fine
at the prompt. It is just the results list in the TKinter interface to
the pydoc server application that doesn't seem to pick up my module's
description (in the first line of its docstring) when the docstring is
triple-single quoted.

I'm not sure what you mean by "the results list in the TKinter interface
to the pydoc server". I ran the server, clicked "open browser" and
browsed to a module in site-packages; that worked fine for me under
Win2K and Python 2.4.1.

Kent

By "the TKinter interface to the pydoc server" I mean the window that
pops up when you select the Module Docs shortcut. It is pictured here
<http://www.onlamp.com/python/2001/04/18/graphics/pydoc1.gif>, which
is Fig.1 in an article on pydoc by Cameron Laird
<http://www.onlamp.com/pub/a/python/2001/04/18/pydoc.html>. By
"results list" I mean the gray-backround'ed box immediately below the
"Search for" input box in the illustration.

The puzzle for me was that if I enter my module name in the "Search
for" box, it shows up in the list of results, as expected. But whether
the results list entry for my module incorporates the description form
my module's docstring or instead shows my module as having "(no
description)" is a function of which style of triple quotes I used.
(If my module docstring is enclosed by triple double quotes, the
description is extracted from my module's docstring. If it uses triple
single quotes instead, for purposes of the results list my module's
docstring is ignored, and the module is listed as having "(no
description)".)

At any rate, such was the (minor) irritation which caused me to launch
the thread. It took me a bit to work out that the quote-style was what
made the difference, and a preliminary google didn't cast light.
2/3rd's the point of the post was to make the problem resolvable by
google.

Thanks for your continued efforts to understand what I'm on about. :-)

Best to all,

Brian vdB

[Kent Johnson]

Brian van den Broek wrote:

Kent Johnson said unto the world upon 2005-04-17 16:17:

Brian van den Broek wrote:

Kent Johnson said unto the world upon 2005-04-16 16:41:

Brian van den Broek wrote:

> I've just spent a frustrating bit of time figuring out why pydoc
> didn't extract a description from my module docstrings. Even though
> I had a well formed docstring (one line, followed by a blank line,
> followed by the rest of the docstring), when I ran Module docs, my
> modules showed up as having "no description". ("Module docs"
> referring to the shortcut installed on Windows that launches the
> pydoc server.)
I'm not sure what you mean by "the results list in the TKinter
interface to the pydoc server". I ran the server, clicked "open
browser" and browsed to a module in site-packages; that worked fine
for me under Win2K and Python 2.4.1.

By "the TKinter interface to the pydoc server" I mean the window that
pops up when you select the Module Docs shortcut. It is pictured here
<http://www.onlamp.com/python/2001/04/18/graphics/pydoc1.gif>, which is
Fig.1 in an article on pydoc by Cameron Laird
<http://www.onlamp.com/pub/a/python/2001/04/18/pydoc.html>. By "results
list" I mean the gray-backround'ed box immediately below the "Search
for" input box in the illustration.

The puzzle for me was that if I enter my module name in the "Search for"
box, it shows up in the list of results, as expected. But whether the
results list entry for my module incorporates the description form my
module's docstring or instead shows my module as having "(no
description)" is a function of which style of triple quotes I used. (If
my module docstring is enclosed by triple double quotes, the description
is extracted from my module's docstring. If it uses triple single quotes
instead, for purposes of the results list my module's docstring is
ignored, and the module is listed as having "(no description)".)

OK, now I get it. I don't use pydoc much and I missed that display.

This is indeed a bug in pydoc. If you look at lines 194, 195 and 201 in pydoc.py (Python 2.4.1
version) you can see that it is parsing out the module docstring itself and it only looks for """
strings.

Here is a patch that accepts ''' strings as well. Though a better patch would allow any kind of
string. I filed a bug report at
http://sourceforge.net/tracker/index...70&atid=105470

Kent

194,195c194,195
< if line[:4] == 'r"""': line = line[1:]
< if line[:3] == '"""':
--- if line[:4] == 'r"""' or line[:4] == "r'''": line = line[1:]
if line[:3] == '"""' or line[:3] == "'''": 201c201
< result = strip(split(line, '"""')[0])
--- result = strip(re.split('\'\'\'|"""', line)[0])

[Brian van den Broek]

Kent Johnson said unto the world upon 2005-04-18 08:20:

<SNIP several iterations clarifying the problem>

The puzzle for me was that if I enter my module name in the "Search
for" box, it shows up in the list of results, as expected. But whether
the results list entry for my module incorporates the description form
my module's docstring or instead shows my module as having "(no
description)" is a function of which style of triple quotes I used.
(If my module docstring is enclosed by triple double quotes, the
description is extracted from my module's docstring. If it uses triple
single quotes instead, for purposes of the results list my module's
docstring is ignored, and the module is listed as having "(no
description)".)

OK, now I get it. I don't use pydoc much and I missed that display.

This is indeed a bug in pydoc. If you look at lines 194, 195 and 201 in
pydoc.py (Python 2.4.1 version) you can see that it is parsing out the
module docstring itself and it only looks for """ strings.

Here is a patch that accepts ''' strings as well. Though a better patch
would allow any kind of string. I filed a bug report at
http://sourceforge.net/tracker/index...70&atid=105470
Kent

<SNIP patch>

Thanks for sticking with this, Kent.

Also, thanks for the patch and for filing the bug. (I had thought of
doing so before posting, but don't yet feel quite confident enough in
my judgement that I'd be putting signal rather than noise into the
bug-tracker.)

Best,

Brian vdB