Thread: [Epydoc-devel] epydoc 2.1 can't handle PyGetSetDefs?
Brought to you by:
edloper
From: Barry W. <ba...@py...> - 2006-07-10 21:12:45
|
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Hi all, I've just started to use epydoc 2.1 to document the API for a tool that has a lot of Python code but is also extended/embedded. In general, it seems like a great tool and is producing nice output with the Epytext markup. Nice job! I've had a few minor problems along the way, and some ideas that I'll share later, but I wanted to ask a quick question for my current blocker. It appears that epydoc cannot handle class attributes defined in extension modules with PyGetSetDef. We define almost all of our attributes this way and all I get are things like getset_descriptor | alias_limit = <attribute 'alias_limit' of '...' This even though alias_limit's PyGetSetDef structure contains a docstring and in fact you can get the __doc__ of that descriptor just fine. I think you can prove this to yourself with standard Python 2.4 with the following: >>> from epydoc.html import HTMLFormatter >>> import array >>> HTMLFormatter.format(array.array.typecode) Now, at this point you'll get an exception because the TypeError uses a local variable before its assignment. Okay, that's easily fixed (use type(object) instead of type(link) on line 3381 of epydoc/ html.py). But that just means you'll get the TypeError that was intended: TypeError: You must use a Link or UID object to specify a getset_descriptor which I think indicates that epydoc 2.1 doesn't know how to handle PyGetSetDefs. I haven't dug into epydoc enough to figure out what needs to be changed in order to handle these built-in Python objects. If you have any hints, I'd love to hear them! I wonder if the problem isn't in inspect or pydoc since the interactive prompt's help() doesn't much like these objects either. Try >>> import array >>> help(array.array.typecode) to see the docstring ignoring help output. Thoughts? Clues? Thanks! - -Barry -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.3 (Darwin) iQCVAwUBRLLCw3EjvBPtnXfVAQK/ewP/Y2RwHBvFBbtLkxs1NhGhPI6OFLITJeFN 1c710JRjaRW1vdFXJDFoxpvuF3JRZ3vUcikVu5i6MzMD9wEBVzjpS5UPNA1z0TMt 5ZGFjvEv3kwNj7GHHnREBG4FhVLyIDgWvY3lXWpkryBtQV8ZUDxEcG3m5vI94SeP jAsx1XysQ0M= =Wv4W -----END PGP SIGNATURE----- |
From: Daniele V. <dan...@gm...> - 2006-07-11 12:16:53
|
> I've had a few minor problems along the way, and some ideas that I'll > share later, but I wanted to ask a quick question for my current > blocker. It appears that epydoc cannot handle class attributes > defined in extension modules with PyGetSetDef. Hello Barry, i hammered together a patch: with it getset_descriptors appear like properties. The patch id is 1520501 and it can be downloaded from http://sourceforge.net/tracker/index.php?func=detail&aid=1520501&group_id=32455&atid=405620 Epydoc 3.0 HEAD behaves nicer with getset_descriptors, but it erroneously files it as a class variable (the same thing happened in the making of the 2.1 patch). I will fix it too. Bye! Daniele |
From: Barry W. <ba...@py...> - 2006-07-11 16:10:39
Attachments:
PGP.sig
objdoc.patch
|
On Jul 11, 2006, at 8:16 AM, Daniele Varrazzo wrote: >> I've had a few minor problems along the way, and some ideas that I'll >> share later, but I wanted to ask a quick question for my current >> blocker. It appears that epydoc cannot handle class attributes >> defined in extension modules with PyGetSetDef. > > Hello Barry, > > i hammered together a patch: with it getset_descriptors appear like > properties. > > The patch id is 1520501 and it can be downloaded from > http://sourceforge.net/tracker/index.php? > func=detail&aid=1520501&group_id=32455&atid=405620 > > Epydoc 3.0 HEAD behaves nicer with getset_descriptors, but it > erroneously files it as a class variable (the same thing happened in > the making of the 2.1 patch). I will fix it too. Thanks Daniele, I tested the patch and it appears to work well. I had to make one other small change to objdoc.py for what I think is an unrelated problem (although I'm not sure because I didn't see the bug before). Without this, I'd get a traceback from add_one() because one of my getset descriptors did not have its parent ID in self.data. I don't quite understand why that might be though, except that perhaps it's because the parent is a base class defined in the extension module. In any event, with this patch, I can generate all my docs and even the traceback'ing getset descriptor gets documented correctly. Cheers, -Barry |
From: Barry W. <ba...@py...> - 2006-07-12 19:15:14
Attachments:
PGP.sig
memberdesc.diff
|
On Jul 11, 2006, at 8:16 AM, Daniele Varrazzo wrote: >> I've had a few minor problems along the way, and some ideas that I'll >> share later, but I wanted to ask a quick question for my current >> blocker. It appears that epydoc cannot handle class attributes >> defined in extension modules with PyGetSetDef. > > i hammered together a patch: with it getset_descriptors appear like > properties. Turns out there's another type of built-in objects that need to be supported like properties: member descriptors. An example is datetime.timedelta.days. Here's a patch cargo culted from your previous patch. It seems to do the trick for me. Cheers, -Barry |
From: Edward L. <ed...@gr...> - 2006-07-13 03:17:00
|
On Jul 10, 2006, at 3:12 PM, Barry Warsaw wrote: > It appears that epydoc cannot handle class attributes > defined in extension modules with PyGetSetDef. We define almost all > of our attributes this way and all I get are things like > > getset_descriptor | alias_limit = <attribute 'alias_limit' of '...' > > This even though alias_limit's PyGetSetDef structure contains a > docstring and in fact you can get the __doc__ of that descriptor just > fine. Thanks to Daniele for providing a quick patch to address this. One question that came up in that patch, though, is what the best way is to get at the getset_descriptor type. I suggested the following (which I found via google): >>> print type(types.FunctionType.__dict__.get('__dict__')) <type 'getset_descriptor'> But this seems to be an implementation detail of FunctionType, that's subject to change in the future. It doesn't look like the getset_descriptor type is accessible via the types module. So any suggestions on what the best way to get at this type is? -Edward |
From: Daniele V. <dan...@gm...> - 2006-07-13 06:38:49
|
On 7/13/06, Edward Loper <ed...@gr...> wrote: > On Jul 10, 2006, at 3:12 PM, Barry Warsaw wrote: > > It appears that epydoc cannot handle class attributes > > defined in extension modules with PyGetSetDef. We define almost all > > of our attributes this way and all I get are things like > > > > getset_descriptor | alias_limit = <attribute 'alias_limit' of '...' > > > > This even though alias_limit's PyGetSetDef structure contains a > > docstring and in fact you can get the __doc__ of that descriptor just > > fine. > > Thanks to Daniele for providing a quick patch to address this. One > question that came up in that patch, though, is what the best way is > to get at the getset_descriptor type. I suggested the following > (which I found via google): > > >>> print type(types.FunctionType.__dict__.get('__dict__')) > <type 'getset_descriptor'> > > But this seems to be an implementation detail of FunctionType, that's > subject to change in the future. It doesn't look like the > getset_descriptor type is accessible via the types module. So any > suggestions on what the best way to get at this type is? What about creating an extension module of our own (probably it should be called "epyzoo.so" :D) with a specimen (two in case of Flood) of the different extension types availablein from the C API? It could be used as an addendum to the types module. That woud have the drawback of requiring a binary distribution on Windows platforms but i'm about used at that (even if i'm not a w32 user anymore - i moved to Gentoo a few months ago - however i have some winbox handy to build them) Daniele |
From: Barry W. <ba...@py...> - 2006-07-13 12:35:27
|
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Jul 12, 2006, at 11:16 PM, Edward Loper wrote: > On Jul 10, 2006, at 3:12 PM, Barry Warsaw wrote: >> It appears that epydoc cannot handle class attributes >> defined in extension modules with PyGetSetDef. We define almost all >> of our attributes this way and all I get are things like >> >> getset_descriptor | alias_limit = <attribute 'alias_limit' of '...' >> >> This even though alias_limit's PyGetSetDef structure contains a >> docstring and in fact you can get the __doc__ of that descriptor just >> fine. > > Thanks to Daniele for providing a quick patch to address this. One > question that came up in that patch, though, is what the best way is > to get at the getset_descriptor type. I suggested the following > (which I found via google): > >>>> print type(types.FunctionType.__dict__.get('__dict__')) > <type 'getset_descriptor'> > > But this seems to be an implementation detail of FunctionType, that's > subject to change in the future. It doesn't look like the > getset_descriptor type is accessible via the types module. So any > suggestions on what the best way to get at this type is? See http://mail.python.org/pipermail/python-dev/2006-July/067219.html for a similar thread I've started on python-dev. While I ended up using type(types.FrameType.f_locals) I think again, that's an implementation detail that's subject to change. Worse, there are also member descriptors (see my previous post) and for that, there really is no good candidate (the situation is worse for Python's types module but could probably work for epydoc). So my pre-coffee thought this morning is the same as yours: Python really needs a _types module that provides those C types in a way that's guaranteed not to change. I plan on throwing something together for Python 2.5, but it's becoming less likely that I'd be allowed to backport that to Python 2.4 (or earlier, I don't know what the minimum Python version epydoc will support). Still, I see no reason why we couldn't collaborate on such a built-in module. OTOH, if you want a pure-Python solution, for member descriptors, use type(datetime.timedelta.days) - -Barry -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.3 (Darwin) iQCVAwUBRLY+BXEjvBPtnXfVAQKmSwP+MzmLiXaf4yAipJeQRAgTugSIUsIHbXCL nON/1v5m8wCOUr+CnNn63s/L+CarYO2NXqpsqQxkP/nTJRBJTOUH9sArcCdqPymH cJgNP7CXGYPAEyqEYgYW4ZuncwQeo6GGZw67ia5N7HZ/CSZh1IGJhlhGEJP45dwa rLqKagJp2Xk= =Jeft -----END PGP SIGNATURE----- |