Why does dynamic doc string do not work?

[Miki Tebeka]

Greetings,
.... '''a doc string'''
........ '''a {} string'''.format('doc')
....
Is there's a reason for this?

I know I can do:.... __doc__ = '''a {} string'''.format('doc')

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

Thanks,

 

[Ian Kelly]

Greetings,

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

Is there's a reason for this?

I know I can do:
... __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.

 

[MRAB]

Greetings,

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

Is there's a reason for this?

I know I can do:
... __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.

 

[Ian Kelly]

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.

 

[Steven D'Aprano]

Greetings,

... '''a doc string'''
...
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.

 

[Dave Angel]

... '''a {} string'''.format('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."

 

[Miki Tebeka]

Thanks!

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]

Thanks!

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