Why does dynamic doc string do not work?

Discussion in 'Python' started by Miki Tebeka, Aug 21, 2012.

  1. Miki Tebeka

    Miki Tebeka Guest

    Greetings,

    >>> class A:

    .... '''a doc string'''
    ....
    >>> A.__doc__

    'a doc string'
    >>> class B:

    .... '''a {} string'''.format('doc')
    ....
    >>> B.__doc__
    >>>


    Is there's a reason for this?

    I know I can do:
    >>> class B:

    .... __doc__ = '''a {} string'''.format('doc')

    And it'll work, but I wonder why the first B docstring is empty.

    Thanks,
    --
    Miki
    Miki Tebeka, Aug 21, 2012
    #1
    1. Advertising

  2. Miki Tebeka

    Ian Kelly Guest

    On Tue, Aug 21, 2012 at 10:44 AM, Miki Tebeka <> wrote:
    > Greetings,
    >
    >>>> class A:

    > ... '''a doc string'''
    > ...
    >>>> A.__doc__

    > 'a doc string'
    >>>> class B:

    > ... '''a {} string'''.format('doc')
    > ...
    >>>> B.__doc__
    >>>>

    >
    > Is there's a reason for this?
    >
    > I know I can do:
    >>>> class B:

    > ... __doc__ = '''a {} string'''.format('doc')
    >
    > And it'll work, but I wonder why the first B docstring is empty.


    The docstring is built at compile-time, not at run-time, so it must be
    a literal, not an arbitrary expression.
    Ian Kelly, Aug 21, 2012
    #2
    1. Advertising

  3. Miki Tebeka

    MRAB Guest

    On 21/08/2012 17:44, Miki Tebeka wrote:
    > Greetings,
    >
    >>>> class A:

    > ... '''a doc string'''
    > ...
    >>>> A.__doc__

    > 'a doc string'
    >>>> class B:

    > ... '''a {} string'''.format('doc')
    > ...
    >>>> B.__doc__
    >>>>

    >
    > Is there's a reason for this?
    >
    > I know I can do:
    >>>> class B:

    > ... __doc__ = '''a {} string'''.format('doc')
    >
    > And it'll work, but I wonder why the first B docstring is empty.
    >

    I think what's happening is that it's being parsed and then checked to
    see whether it's a string literal.

    This:

    "doc string"

    is OK, as is this:

    "doc" "string"

    (implied concatenation) and this:

    ("doc string")

    but this isn't:

    "doc" + " string"

    because its syntax is:

    ADD(STRING_LITERAL, STRING_LITERAL)

    In other words, it's looking at the syntax, not the resulting value.
    MRAB, Aug 21, 2012
    #3
  4. Miki Tebeka

    Ian Kelly Guest

    On Tue, Aug 21, 2012 at 11:09 AM, Ian Kelly <> wrote:
    > On Tue, Aug 21, 2012 at 10:44 AM, Miki Tebeka <> wrote:
    >> Greetings,
    >>
    >>>>> class A:

    >> ... '''a doc string'''
    >> ...
    >>>>> A.__doc__

    >> 'a doc string'
    >>>>> class B:

    >> ... '''a {} string'''.format('doc')
    >> ...
    >>>>> B.__doc__
    >>>>>

    >>
    >> Is there's a reason for this?
    >>
    >> I know I can do:
    >>>>> class B:

    >> ... __doc__ = '''a {} string'''.format('doc')
    >>
    >> And it'll work, but I wonder why the first B docstring is empty.

    >
    > The docstring is built at compile-time, not at run-time, so it must be
    > a literal, not an arbitrary expression.


    Also, if it did allow arbitrary expressions, then the syntax would be ambiguous.

    def a():
    foo()
    do_stuff()

    Is "foo()" intended to return a doc string? If so, then it should be
    called when the function object is built, not when the function is
    called. On the other hand, maybe it's intended to be part of the
    function's code, in which case it should be called only when the
    function itself is called.
    Ian Kelly, Aug 21, 2012
    #4
  5. On Tue, 21 Aug 2012 09:44:10 -0700, Miki Tebeka wrote:

    > Greetings,
    >
    >>>> class A:

    > ... '''a doc string'''
    > ...
    >>>> A.__doc__

    > 'a doc string'
    >>>> class B:

    > ... '''a {} string'''.format('doc') ...
    >>>> B.__doc__
    >>>>
    >>>>

    > Is there's a reason for this?


    Yes. Python only generates docstrings automatically from string literals,
    not arbitrary expressions.

    Arbitrary expressions are evaluated and then garbage collected, so:

    class B:
    '''a {} string'''.format('doc')

    is equivalent to:

    class B:
    __doc__ = None
    _tmp = '''a {} string'''.format('doc')
    del _tmp

    except that the name "_tmp" doesn't actually get used.



    --
    Steven
    Steven D'Aprano, Aug 21, 2012
    #5
  6. Miki Tebeka

    Dave Angel Guest

    On 08/21/2012 12:44 PM, Miki Tebeka wrote:
    > <snip>
    >>> class B:

    > ... '''a {} string'''.format('doc')
    > ...
    >>>> B.__doc__
    >>>>

    > <snip> I wonder why the first B docstring is empty. Thanks, -- Miki


    According to some early documentation:

    "convenient initialization of the |__doc__| attribute of modules,
    classes and functions by placing a string literal by itself as the first
    statement in the suite. It must be a literal -- an expression yielding a
    string object is not accepted as a documentation string, since future
    tools may need to derive documentation from source by parsing."

    --

    DaveA
    Dave Angel, Aug 21, 2012
    #6
  7. Miki Tebeka

    Miki Tebeka Guest

    Thanks!

    > On 08/21/2012 12:44 PM, Miki Tebeka wrote:
    >
    > > <snip>

    >
    > >>> class B:

    >
    > > ... '''a {} string'''.format('doc')

    >
    > > ...

    >
    > >>>> B.__doc__

    >
    > >>>>

    >
    > > <snip> I wonder why the first B docstring is empty. Thanks, -- Miki

    >
    >
    >
    > According to some early documentation:
    >
    >
    >
    > "convenient initialization of the |__doc__| attribute of modules,
    >
    > classes and functions by placing a string literal by itself as the first
    >
    > statement in the suite. It must be a literal -- an expression yielding a
    >
    > string object is not accepted as a documentation string, since future
    >
    > tools may need to derive documentation from source by parsing."
    >
    >
    >
    > --
    >
    >
    >
    > DaveA
    Miki Tebeka, Aug 21, 2012
    #7
  8. Miki Tebeka

    Miki Tebeka Guest

    Thanks!

    > On 08/21/2012 12:44 PM, Miki Tebeka wrote:
    >
    > > <snip>

    >
    > >>> class B:

    >
    > > ... '''a {} string'''.format('doc')

    >
    > > ...

    >
    > >>>> B.__doc__

    >
    > >>>>

    >
    > > <snip> I wonder why the first B docstring is empty. Thanks, -- Miki

    >
    >
    >
    > According to some early documentation:
    >
    >
    >
    > "convenient initialization of the |__doc__| attribute of modules,
    >
    > classes and functions by placing a string literal by itself as the first
    >
    > statement in the suite. It must be a literal -- an expression yielding a
    >
    > string object is not accepted as a documentation string, since future
    >
    > tools may need to derive documentation from source by parsing."
    >
    >
    >
    > --
    >
    >
    >
    > DaveA
    Miki Tebeka, Aug 21, 2012
    #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. Matt
    Replies:
    3
    Views:
    485
    Tor Iver Wilhelmsen
    Sep 17, 2004
  2. Horace Nunley

    why why why does function not work

    Horace Nunley, Sep 27, 2006, in forum: ASP .Net
    Replies:
    1
    Views:
    452
    =?Utf-8?B?UGV0ZXIgQnJvbWJlcmcgW0MjIE1WUF0=?=
    Sep 27, 2006
  3. Mr. SweatyFinger

    why why why why why

    Mr. SweatyFinger, Nov 28, 2006, in forum: ASP .Net
    Replies:
    4
    Views:
    863
    Mark Rae
    Dec 21, 2006
  4. Mr. SweatyFinger
    Replies:
    2
    Views:
    1,769
    Smokey Grindel
    Dec 2, 2006
  5. Will
    Replies:
    5
    Views:
    272
    Alan J. Flavell
    Dec 2, 2003
Loading...

Share This Page