[Python-Dev] Support for PyGetSetDefs in pydoc

[Barry Warsaw]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


On Jul 13, 2006, at 12:12 PM, Barry Warsaw wrote:

> I've updated SF patch #1520294 and assigned it back to Georg for  
> another quick review.

Neal commented in the patch that it might help to explain the  
implementation a bit.  I'd like to do that and also explain why I  
think this patch should go in 2.5.  OTOH, I suspect most people just  
don't care, which is why I've gotten almost no comments on the patch  
(other than one or two mild nods of approval).

As a reminder, this patch is really about providing useful help() at  
the interactive prompt for two specific types of C implemented  
descriptors, getset and member descriptors.  Both objects can be  
given docstrings in the C code, but currently nothing in the tool  
chain pulls out and displays those docstrings, so help() on such  
objects is not very useful.  While certainly a minor point, I think  
it improves the user experience to be able to display any existing  
docstrings for these types of objects.  Of course, I'm scratching my  
own itch here because our app is deeply embedded and we have a lot of  
getset and member descriptors with docstrings.  I'd like for our  
users to be able to type "help(someobj.member)" at our interactive  
prompt and get our docstring printed back at them.

The implementation is fairly straightforward  I add two new constants  
to types.py, a couple of is*() methods to inspect.py, and a bit of  
extra support to pydoc.py.  Where it gets complicated is that I added  
a _types builtin module to provide a getset and member descriptor  
that could be turned into *Type constants in the types.py module.

Why did I do this instead of trying to hunt down some existing getset  
or member descriptor?  For one thing, there really aren't very good  
candidates for such objects in the built-in modules.  You can't use  
objects like datetime.timedelta.days in types.py because datetime is  
not importable early enough for types.py to use it. Even if there  
were likely candidates, they would be accidents of implementation and  
it doesn't seem like a good idea to force force some future datetime  
maintainer to have to fix types.py when she decides that  
datetime.timedelta.days should be implemented in some other way.

A 3rd party extension module doesn't work either because you really  
need the tie-in from types.py, inspect.py, and pydoc.py.  You  
certainly don't want to go poking new values into types.py from the  
outside, and besides inspect.py and pydoc.py also need to learn about  
these fundamental built-in Python types.

ISTM the most straightforward approach is to provide these types in a  
built-in C module, linked into the interpreter so types.py can get  
access to it as early as it needs to.  Also, because the type that  
these descriptors are attached to cannot be instantiated from Python,  
they should be quite benign, existing only in order to give type()  
something to query.

Neal also questions the reliance on the types.py module and whether  
we're moving away from it.  My own feeling is that certainly for  
common types available as type constructors in the built-in namespace  
(e.g. list, set, dict, etc.), no, we certainly don't need types.py.   
But there are enough other tools in Pythonland that need to  
introspect about types that aren't readily available, and I see no  
reason why types.py shouldn't continue to fulfill those needs.  How  
else would you find the type of frames or generators in a simple,  
documented, consistent way?

Neal also asks about other implementations.  I believe that I've  
patched types.py, inspect.py, and pydoc.py in such a way that if the  
implementation did not have these types available, those modules  
would not break.  For example, GetSetDescriptorType and  
MemberDescriptorType are not defined if _types can't be imported.  If  
those types aren't defined, the appropriate inspect.py is() methods  
will always return False.  Thus, other implementations can do hasattr 
() tests on types.py or better yet, inspect.isgetsetdescriptor() and  
get an answer it can deal with.

Further, by providing a _types built-in module, other  
implementations /could/ expose those types, if they were meaningful.   
I believe that an _types module provides a good place for those  
alternative implementations to hide types of their own should the  
need arise (e.g. if Jython had some implementation-specific  
JavaSpecialUnicornType, the object would live in Jython's _types.java  
and be exposed via a type(_type.javaspecialunicorn) in types.py).

Could this wait until Python 2.6?  Well, it /could/ but IMO it  
shouldn't.  Improving the user experience by providing useful help()  
shouldn't be postponed when we have the opportunity to do so now,  
with low risk of breakage.  Probably the biggest risk is whether I  
can modify the Windows build to DTRT with _types.c.  I've been  
building enough Windows s/w lately that I think I can handle it, and  
if not, I'll just buy the Timbot lunch as payment for his help.  I  
know what he likes to eat.

  So anyway, that's probably more text than the patch combined. :)  I  
hope it helps.
- -Barry

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (Darwin)

iQCVAwUBRL/ZL3EjvBPtnXfVAQKEvgQAktmdjKnq5uf1+m5Wc5F1ZFY/LhdM1vQQ
A2v6zgXTxdQteqTNds15BktGAUwRNKKB2pU/U2wTcfLx/4rfjvkFG3cRbhEY8jI0
wa8wzPrGs17VTp8Z/LI65F9DC8aMEa9RBr2fXeuhewXlAheiZT9doelds8b5y0T/
Ed9Yl4MJ0es=
=Fh1P
-----END PGP SIGNATURE-----