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

Discussion in 'Python' started by Brian van den Broek, Apr 16, 2005.

  1. 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
     
    Brian van den Broek, Apr 16, 2005
    #1
    1. Advertising

  2. Brian van den Broek

    Thomas Rast Guest

    Re: pydoc preference for triple double over triple single quotes --any reason?

    Brian van den Broek <> 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'.
     
    Thomas Rast, Apr 16, 2005
    #2
    1. Advertising

  3. Brian van den Broek

    Kent Johnson Guest

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

    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
     
    Kent Johnson, Apr 16, 2005
    #3
  4. Re: pydoc preference for triple double over triple single quotes-- anyreason?

    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
     
    Brian van den Broek, Apr 17, 2005
    #4
  5. Brian van den Broek

    Kent Johnson Guest

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

    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
     
    Kent Johnson, Apr 17, 2005
    #5
  6. Re: pydoc preference for triple double over triple single quotes--anyreason?

    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
     
    Brian van den Broek, Apr 17, 2005
    #6
  7. Brian van den Broek

    Kent Johnson Guest

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

    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])
     
    Kent Johnson, Apr 18, 2005
    #7
  8. Re: pydoc preference for triple double over triplesingle quotes--anyreason?

    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.php?func=detail&aid=1185124&group_id=5470&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
     
    Brian van den Broek, Apr 19, 2005
    #8
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Chris White

    Quotes/Double Quotes in Image Control

    Chris White, Sep 22, 2004, in forum: ASP .Net
    Replies:
    1
    Views:
    4,918
    Hermit Dave
    Sep 22, 2004
  2. Chris
    Replies:
    1
    Views:
    13,768
    Oisin
    Mar 24, 2006
  3. BartlebyScrivener

    pydoc script.py vs. pydoc scriptpy

    BartlebyScrivener, Oct 20, 2007, in forum: Python
    Replies:
    1
    Views:
    691
    Stargaming
    Oct 22, 2007
  4. nirman longjam
    Replies:
    1
    Views:
    286
    Miki Tebeka
    Nov 24, 2011
  5. jOhn
    Replies:
    1
    Views:
    277
    Phlip
    Jan 29, 2008
Loading...

Share This Page