Re: How to create a docstring for a module?
In article , alex23 wrote: >"Phillip M. Feldman" wrote: >> It does seem as though IPython could be a bit more clever about this. =A0 > >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? 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. -- -- Albert van der Horst, UTRECHT,THE NETHERLANDS Economic growth -- being exponential -- ultimately falters. alb...@spe&ar&c.xs4all.nl &=n http://home.hccnet.nl/a.w.m.van.der.horst -- http://mail.python.org/mailman/listinfo/python-list
Re: How to create a docstring for a module?
En Sun, 06 Dec 2009 23:51:30 -0300, alex23 escribió:
"Phillip M. Feldman" wrote:
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?
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.
...
--
Gabriel Genellina
--
http://mail.python.org/mailman/listinfo/python-list
Re: How to create a docstring for a module?
"Phillip M. Feldman" wrote: > 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? -- http://mail.python.org/mailman/listinfo/python-list
Re: How to create a docstring for a module?
Chris Rebert wrote: On Sun, Dec 6, 2009 at 12:34 PM, Dr. Phillip M. Feldman wrote: 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/ in () NameError: name 'pickle' is not defined In [5]: import pickle In [6]: ?pickle 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\nPickler\nUnpickler\n\nFunctions:\n\n dump(object, file)\ndumps(object) -> string\nload(file) -> object\nloads(string) -> object\n\nMisc variables:\n\n __version__\nformat_version\ncompatible_formats\n\n' Cheers, Chris -- http://blog.rebertia.com 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: How to create a docstring for a module?
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 -- http://mail.python.org/mailman/listinfo/python-list
Re: How to create a docstring for a module?
On Sun, Dec 6, 2009 at 12:34 PM, Dr. Phillip M. Feldman wrote: > 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/ in () NameError: name 'pickle' is not defined In [5]: import pickle In [6]: ?pickle 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\nPickler\nUnpickler\n\nFunctions:\n\n dump(object, file)\ndumps(object) -> string\nload(file) -> object\nloads(string) -> object\n\nMisc variables:\n\n __version__\nformat_version\ncompatible_formats\n\n' Cheers, Chris -- http://blog.rebertia.com -- http://mail.python.org/mailman/listinfo/python-list
Re: How to create a docstring for a module?
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. -- View this message in context: http://old.nabble.com/How-to-create-a-docstring-for-a-module--tp26662729p26668758.html Sent from the Python - python-list mailing list archive at Nabble.com. -- http://mail.python.org/mailman/listinfo/python-list
Re: How to create a docstring for a module?
Steven D'Aprano-7 wrote: > > On Sun, 06 Dec 2009 10:55:50 +0100, Andreas Waldenburger wrote: > >> On Sat, 5 Dec 2009 23:04:42 -0800 (PST) "Dr. Phillip M. Feldman" >> wrote: >> >> >>> 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. > > 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. > > > -- > Steven > -- > http://mail.python.org/mailman/listinfo/python-list > > 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! -- View this message in context: http://old.nabble.com/How-to-create-a-docstring-for-a-module--tp26662729p26668719.html Sent from the Python - python-list mailing list archive at Nabble.com. -- http://mail.python.org/mailman/listinfo/python-list
Re: How to create a docstring for a module?
On Dec 6, 7:43 am, Steven D'Aprano wrote: > On Sun, 06 Dec 2009 06:34:17 -0600, Tim Chase wrote: > > 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. > > -- > Steven 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: How to create a docstring for a module?
On Sun, 06 Dec 2009 06:34:17 -0600, Tim Chase wrote: >> * 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: Unfortunately, and surprisingly, assigning to __doc__ doesn't work with new-style classes. >>> class K(object): ... pass ... >>> K.__doc__ is None True >>> K.__doc__ = "docstring" Traceback (most recent call last): File "", line 1, in AttributeError: attribute '__doc__' of 'type' objects is not writable -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: How to create a docstring for a module?
* 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
>>> import ds
>>> help(ds)
...
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
>>> import ds2
>>> c = ds2.C("Hello")
>>> c.__doc__
>>> c.__doc__
>>> c.__doc__
Are you REALLY that forgetful?!
>>> c.__doc__
-tkc
--
http://mail.python.org/mailman/listinfo/python-list
Re: How to create a docstring for a module?
On Sun, 06 Dec 2009 10:55:50 +0100, Andreas Waldenburger wrote: > On Sat, 5 Dec 2009 23:04:42 -0800 (PST) "Dr. Phillip M. Feldman" > wrote: > > >> 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. 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. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: How to create a docstring for a module?
On Sat, 5 Dec 2009 23:04:42 -0800 (PST) "Dr. Phillip M. Feldman" wrote: > > 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 -- INVALID? DE! -- http://mail.python.org/mailman/listinfo/python-list
How to create a docstring for a module?
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? -- View this message in context: http://old.nabble.com/How-to-create-a-docstring-for-a-module--tp26662729p26662729.html Sent from the Python - python-list mailing list archive at Nabble.com. -- http://mail.python.org/mailman/listinfo/python-list
