Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Python > Why does dynamic doc string do not work?

Reply
Thread Tools

Why does dynamic doc string do not work?

 
 
Miki Tebeka
Guest
Posts: n/a
 
      08-21-2012
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
 
Reply With Quote
 
 
 
 
Ian Kelly
Guest
Posts: n/a
 
      08-21-2012
On Tue, Aug 21, 2012 at 10:44 AM, Miki Tebeka <(E-Mail Removed)> 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.
 
Reply With Quote
 
 
 
 
MRAB
Guest
Posts: n/a
 
      08-21-2012
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.
 
Reply With Quote
 
Ian Kelly
Guest
Posts: n/a
 
      08-21-2012
On Tue, Aug 21, 2012 at 11:09 AM, Ian Kelly <(E-Mail Removed)> wrote:
> On Tue, Aug 21, 2012 at 10:44 AM, Miki Tebeka <(E-Mail Removed)> 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.
 
Reply With Quote
 
Steven D'Aprano
Guest
Posts: n/a
 
      08-21-2012
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
 
Reply With Quote
 
Dave Angel
Guest
Posts: n/a
 
      08-21-2012
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

 
Reply With Quote
 
Miki Tebeka
Guest
Posts: n/a
 
      08-21-2012
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


 
Reply With Quote
 
Miki Tebeka
Guest
Posts: n/a
 
      08-21-2012
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


 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Word Doc Does Not Open On First Attempt, But Does On Second Martin Computer Support 1 01-07-2009 09:18 PM
why why why why why Mr. SweatyFinger ASP .Net 4 12-21-2006 01:15 PM
findcontrol("PlaceHolderPrice") why why why why why why why why why why why Mr. SweatyFinger ASP .Net 2 12-02-2006 03:46 PM
String[] files = {"a.doc, b.doc"}; VERSUS String[] files = new String[] {"a.doc, b.doc"}; Matt Java 3 09-17-2004 10:28 PM
Parsing MS Word client doc into server-side doc... John Wallace ASP .Net 0 07-22-2003 06:49 PM



Advertisments