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

[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.php?func=detail&aid=1185124&group_id=5470&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])