How to create a docstring for a module?

[Dr. Phillip M. Feldman]

If I create a module xyz.py with a docstring """xyz does everything you could
possibly want.""" at the top, the command ?xyz issued at the IPython prompt
does not display this docstring. What am I doing wrong?

 

[Andreas Waldenburger]

If I create a module xyz.py with a docstring """xyz does everything
you could possibly want.""" at the top, the command ?xyz issued at
the IPython prompt does not display this docstring. What am I doing
wrong?

Stab in the dark: You have imported the module first, right?

Also: Never, EVER, ask a question like this on any technical forum
without posting your code (or rather: a minimal version of it that
still exhibits the problem). That way, people can help you directly
instead of taking wild guesses at what your problem might be.

/W

 

[Steven D'Aprano]

Stab in the dark: You have imported the module first, right?

Also: Never, EVER, ask a question like this on any technical forum
without posting your code (or rather: a minimal version of it that still
exhibits the problem). That way, people can help you directly instead of
taking wild guesses at what your problem might be.

In fairness, Phillip's description of the problem is pretty straight-
forward: he has a module xyz.py with a docstring. The minimal version of
the code is no code at all, just a docstring:

"""xyz does everything you could possibly want."""

His problem isn't an error when running the code, but an error with
IPython's command ?xyz.

What he didn't say is what IPython prints instead of the expected
docstring. Over to you Phillip, don't just tell us what IPython doesn't
do, tell us what it does do.

My guesses are:

* He hasn't imported the module, so he gets an error of some sort.

* He hasn't actually defined a docstring. Docstrings have to be string
literals, you can't do this:

"""%s does everything you could possibly want.""" % "xyz"

Nor can you have anything except comments and whitespace between the top
of the module and the string.

* He has another module called xyz which is shadowing the module he
expects, and so he sees that module's docstring instead.

 

[Tim Chase]

* He hasn't actually defined a docstring. Docstrings have to be string

literals, you can't do this:

"""%s does everything you could possibly want.""" % "xyz"

I've occasionally wanted something like this, and have found that
it can be done by manually assigning to __doc__ (either at the
module-level or classes) which can make some documentation bits a
little easier:

# ds.py ##############
"original docstring"
OPTIONS = {
'FOO': 'bar',
'BAZ': 'boing',
}
__doc__ = """
This is %(FOO)s and it does %(BAZ)s
""" % OPTIONS
more_code_that_uses(OPTIONS)
######################


you can then
...

and see the formatted help that makes use of the options in the
file. Being lazy, I'm all for self-updating documentation ;-)

Even weirder is assigning a repr()/str()'able class-instance as
the __doc__ for even crazier behaviors (though it looks like the
internal help() function ignores them, perhaps requiring
isinstance(__doc__, basestring) to pass)

# ds2.py ###############
class DynamicHelp:
def __init__(self, name, count=0):
self.name = name
self.count = count
def __str__(self):
self.count += 1
if self.count = 3:
return "Are you REALLY that forgetful?!"
return "%s:%i" % (self.name, self.count)
def __repr__(self):
return "<%s>" % self

class C:
"Raw C"
def __init__(self, name):
self.__doc__ = DynamicHelp(name)

where you can then do weird things like
<Hello:4>

-tkc

 

[Steven D'Aprano]

I've occasionally wanted something like this, and have found that it can
be done by manually assigning to __doc__ (either at the module-level or
classes) which can make some documentation bits a little easier:

Unfortunately, and surprisingly, assigning to __doc__ doesn't work with
new-style classes.
.... pass
....Traceback (most recent call last):
File "<stdin>", line 1, in <module>
AttributeError: attribute '__doc__' of 'type' objects is not writable

 

[Paul McGuire]

Unfortunately, and surprisingly, assigning to __doc__ doesn't work with
new-style classes.

Fortunately, in the OP's case, he isn't trying to do this with a
class, but with a module. For me, assigning to __doc__ at the module
works in defining a docstring for pyparsing, at least for Py2.5.

-- Paul

 

[Dr. Phillip M. Feldman]

In fairness, Phillip's description of the problem is pretty straight-
forward: he has a module xyz.py with a docstring. The minimal version of
the code is no code at all, just a docstring:

"""xyz does everything you could possibly want."""

His problem isn't an error when running the code, but an error with
IPython's command ?xyz.

What he didn't say is what IPython prints instead of the expected
docstring. Over to you Phillip, don't just tell us what IPython doesn't
do, tell us what it does do.

My guesses are:

* He hasn't imported the module, so he gets an error of some sort.

* He hasn't actually defined a docstring. Docstrings have to be string
literals, you can't do this:

"""%s does everything you could possibly want.""" % "xyz"

Nor can you have anything except comments and whitespace between the top
of the module and the string.

* He has another module called xyz which is shadowing the module he
expects, and so he sees that module's docstring instead.

My bad. This is working for me now. I could swear that I imported the
module previously, but perhaps I didn't . My apologies, and thanks for the
help!

 

[Dr. Phillip M. Feldman]

OK. I was able to reproduce the problem. My difficulty was that the command
that I issued initially was "from xyz import *" rather than just "import
xyz". If I say "import xyz", then the docstring is defined; if I say "from
xyz import *", it isn't. I'm not sure whether this is a bug or expected
behavior.

 

[Chris Rebert]

OK.  I was able to reproduce the problem.  My difficulty was that the command
that I issued initially was "from xyz import *" rather than just "import
xyz".  If I say "import xyz", then the docstring is defined; if I say "from
xyz import *", it isn't.  I'm not sure whether this is a bug or expected
behavior.

Expected behavior. If you `from foo import bar`, the name `foo` won't
be bound, so needless to say you won't be able to access its docstring
foo.__doc__.

$ ipython
Python 2.6.2 (r262:71600, Nov 5 2009, 15:03:16)
Type "copyright", "credits" or "license" for more information.

IPython 0.10 -- An enhanced Interactive Python.
? -> Introduction and overview of IPython's features.
%quickref -> Quick reference.
help -> Python's own help system.
object? -> Details about 'object'. ?object also works, ?? prints more.

In [1]: ?pickle
Object `pickle` not found.

In [2]: from pickle import *

In [3]: ?pickle
Object `pickle` not found.

In [4]: pickle.__doc__
---------------------------------------------------------------------------
NameError Traceback (most recent call last)

/Users/chris/<ipython console> in <module>()

NameError: name 'pickle' is not defined

In [5]: import pickle

In [6]: ?pickle

<shows the documentation>

In [7]: pickle.__doc__
Out[7]: 'Create portable serialized representations of Python
objects.\n\nSee module cPickle for a (much) faster
implementation.\nSee module copy_reg for a mechanism for registering
custom picklers.\nSee module pickletools source for extensive
comments.\n\nClasses:\n\n Pickler\n Unpickler\n\nFunctions:\n\n
dump(object, file)\n dumps(object) -> string\n load(file) ->
object\n loads(string) -> object\n\nMisc variables:\n\n
__version__\n format_version\n compatible_formats\n\n'


Cheers,
Chris

 

[Stefan Behnel]

Dr. Phillip M. Feldman, 06.12.2009 21:34:

OK. I was able to reproduce the problem. My difficulty was that the command
that I issued initially was "from xyz import *" rather than just "import
xyz". If I say "import xyz", then the docstring is defined; if I say "from
xyz import *", it isn't. I'm not sure whether this is a bug or expected
behavior.

Definitely expected behaviour.

The problem isn't the docstring but what you import. "from xyz import
a,b,c" does not import "xyz" into the current namespace. Only the names
a,b,c are imported. If you do "import xyz", then "xyz" becomes a defined
name in your current namespace.

Stefan

 

[Phillip M. Feldman]

OK. I was able to reproduce the problem. My difficulty was that the command
that I issued initially was "from xyz import *" rather than just "import
xyz". If I say "import xyz", then the docstring is defined; if I say "from
xyz import *", it isn't. I'm not sure whether this is a bug or expected
behavior.

Expected behavior. If you `from foo import bar`, the name `foo` won't
be bound, so needless to say you won't be able to access its docstring
foo.__doc__.

$ ipython
Python 2.6.2 (r262:71600, Nov 5 2009, 15:03:16)
Type "copyright", "credits" or "license" for more information.

IPython 0.10 -- An enhanced Interactive Python.
? -> Introduction and overview of IPython's features.
%quickref -> Quick reference.
help -> Python's own help system.
object? -> Details about 'object'. ?object also works, ?? prints more.

In [1]: ?pickle
Object `pickle` not found.

In [2]: from pickle import *

In [3]: ?pickle
Object `pickle` not found.

In [4]: pickle.__doc__
---------------------------------------------------------------------------
NameError Traceback (most recent call last)

/Users/chris/<ipython console> in <module>()

NameError: name 'pickle' is not defined

In [5]: import pickle

In [6]: ?pickle

<shows the documentation>

In [7]: pickle.__doc__
Out[7]: 'Create portable serialized representations of Python
objects.\n\nSee module cPickle for a (much) faster
implementation.\nSee module copy_reg for a mechanism for registering
custom picklers.\nSee module pickletools source for extensive
comments.\n\nClasses:\n\n Pickler\n Unpickler\n\nFunctions:\n\n
dump(object, file)\n dumps(object) -> string\n load(file) ->
object\n loads(string) -> object\n\nMisc variables:\n\n
__version__\n format_version\n compatible_formats\n\n'


Cheers,
Chris

Hello Chris-

It does seem as though IPython could be a bit more clever about this.
If the user asks for documentation on xyz via "?xyz" and xyz is not
defined, then I'd like to see IPython check for a module named "xyz" and
if it exists, extract and display the docstring.

Phillip

 

[alex23]

It does seem as though IPython could be a bit more clever about this.  

I disagree. I _like_ that IPython is only reporting on the current
state of the interpreter and not trying to second guess what I meant.

If the user asks for documentation on xyz via "?xyz" and xyz is not
defined, then I'd like to see IPython check for a module named "xyz" and
if it exists, extract and display the docstring.

How would you recommend IPython distinguish between which "xyz" you
meant: the one in site-packages, the one in some package on the python
path, or the one in the folder you're running IPython from?

 

[Gabriel Genellina]

I disagree. I _like_ that IPython is only reporting on the current
state of the interpreter and not trying to second guess what I meant.


How would you recommend IPython distinguish between which "xyz" you
meant: the one in site-packages, the one in some package on the python
path, or the one in the folder you're running IPython from?

The "xyz" that would be imported by executing "import xyz", I'd say.
The standard interpreter does that:

Python 2.6.4 (r264:75708, Oct 26 2009, 08:23:19) [MSC v.1500
32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more in
formation.
py> help("poplib")
Help on module poplib:

NAME
poplib - A POP3 client class.
....

 

[Albert van der Horst]

I disagree. I _like_ that IPython is only reporting on the current
state of the interpreter and not trying to second guess what I meant.


How would you recommend IPython distinguish between which "xyz" you
meant: the one in site-packages, the one in some package on the python
path, or the one in the folder you're running IPython from?

Alternatively, it could state that "xyz" is not loaded, but could be
loaded from one of the places you summarize.
(Kind of what Ubuntu does: hack?, I have no "hack" but such command
could be installed from BSD classical games. )

Groetjes Albert.