Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #27573 > unrolled thread

Why does dynamic doc string do not work?

Back to article view | Back to comp.lang.python

Contents

  Why does dynamic doc string do not work? Miki Tebeka <miki.tebeka@gmail.com> - 2012-08-21 09:44 -0700
    Re: Why does dynamic doc string do not work? Ian Kelly <ian.g.kelly@gmail.com> - 2012-08-21 11:09 -0600
    Re: Why does dynamic doc string do not work? MRAB <python@mrabarnett.plus.com> - 2012-08-21 18:16 +0100
    Re: Why does dynamic doc string do not work? Ian Kelly <ian.g.kelly@gmail.com> - 2012-08-21 11:21 -0600
    Re: Why does dynamic doc string do not work? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2012-08-21 17:22 +0000
    Re: Why does dynamic doc string do not work? Dave Angel <d@davea.name> - 2012-08-21 13:30 -0400
      Re: Why does dynamic doc string do not work? Miki Tebeka <miki.tebeka@gmail.com> - 2012-08-21 10:40 -0700
      Re: Why does dynamic doc string do not work? Miki Tebeka <miki.tebeka@gmail.com> - 2012-08-21 10:40 -0700

#27573 — Why does dynamic doc string do not work?

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

[toc] | [next] | [standalone]

#27577

On Tue, Aug 21, 2012 at 10:44 AM, Miki Tebeka <miki.tebeka@gmail.com> 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.

[toc] | [prev] | [next] | [standalone]

#27580

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.

[toc] | [prev] | [next] | [standalone]

#27582

On Tue, Aug 21, 2012 at 11:09 AM, Ian Kelly <ian.g.kelly@gmail.com> wrote:
> On Tue, Aug 21, 2012 at 10:44 AM, Miki Tebeka <miki.tebeka@gmail.com> 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.

[toc] | [prev] | [next] | [standalone]

#27583

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

[toc] | [prev] | [next] | [standalone]

#27586

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

[toc] | [prev] | [next] | [standalone]

#27587

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

[toc] | [prev] | [next] | [standalone]

#27588

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

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web