[Python-bugs-list] [ python-Bugs-542984 ] allow use of descriptors for __doc_ attr

noreply@sourceforge.net noreply@sourceforge.net
Sun, 14 Apr 2002 17:31:28 -0700


Bugs item #542984, was opened at 2002-04-12 09:18
You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=105470&aid=542984&group_id=5470

Category: Type/class unification
Group: None
Status: Open
Resolution: None
Priority: 5
Submitted By: James Henstridge (jhenstridge)
>Assigned to: Guido van Rossum (gvanrossum)
Summary: allow use of descriptors for __doc_ attr

Initial Comment:
In bug #504343, I proposed a patch that made the
__doc__ attribute of new style types to things other
than strings.  That bug was about unicode doc strings,
but my main aim was to use a descriptor for __doc__
(the original bug I submitted was #507394, which got
marked as a dup).

The patch I proposed in that bug turned out to cause
some problems for pydoc in another bit of code, as
documented in bug #530070 (specifically, getting the
help for __builtin__.property).

The patch on that bug broke things again, so that my
classes (which were non heap type classes defined in
extension modules) started returning None when trying
to get the documentation, because their tp_doc slot was
NULL (they had a __doc__ in the type dict though).

Additionally, for heap type classes, it appears that it
won't call the tp_descr_get slot of the __doc__ object
found in the module dictionary, so you end up getting
the descriptor itself :(

The sample program attached to bug #507394 (my first
one on this topic) demonstrates part of the problem. 
With the current 2.2.1 candidate, for NewClass.__doc__,
it returns the descriptor object itself.

A translation of the type and descriptor to a C
extension would demonstrate the problem in the non heap
type case (I haven't written this test case yet).  The
development releases of pygtk can act as a test case
though (running "import gtk; print gtk.Widget.__doc__").

Maybe the best fix would be to get pydoc to handle non
string __doc__ by running str() on it, and ignoring the
docstring if an exception occurs during the conversion.
 This would allow display of some unicode docstrings
provided they could be represented in the system
codeset (if you are using a utf8 system encoding, all
unicode strings should be representable).

I would like to see this working okay for python 2.2.1,
but if the change is too big, maybe it could be moved
out to python 2.3.  I would like to see this issue
considered.

----------------------------------------------------------------------

>Comment By: Guido van Rossum (gvanrossum)
Date: 2002-04-14 20:31

Message:
Logged In: YES 
user_id=6380

James, can you please explain the problem again, but without
referring to other existing patches?  With all the
references to pydoc, inspect, properties, descriptors, other
patches and SF bug reports I have completely lost the trail,
and I don't think it's productive for me to try and gather
all the separate bits together.

----------------------------------------------------------------------

Comment By: Martin v. Löwis (loewis)
Date: 2002-04-12 11:29

Message:
Logged In: YES 
user_id=21627

This is not (primarily) a pydoc issue: with your change,
property.__doc__ gets changed. pydoc could ignore the object
returned, but then property would have no documentation at
all - even though there is a tp_doc in it. So I don't see
any easy solution. If you do, please attach a patch for the
current CVS (we can then decide whether to backport it to
2.2.2).

----------------------------------------------------------------------

Comment By: James Henstridge (jhenstridge)
Date: 2002-04-12 11:06

Message:
Logged In: YES 
user_id=146903

Maybe getting pydoc to ignore any __doc__ attributes (that
is, what gets returned by getattr) that weren't strings or
unicode would work.

As for using a different metatype, a reason for getting this
into the the standard metatype is that it is also an
inconsistency between how new and old style classes act, and
is fairly easy to reconcile (granted descriptors didn't
exist in python < 2.2, but everytime new style classes act a
bit differently, people seem to start submitting pygtk bug
reports).


----------------------------------------------------------------------

Comment By: Martin v. Löwis (loewis)
Date: 2002-04-12 10:33

Message:
Logged In: YES 
user_id=21627

Also, if you want to have types with computed doc strings,
couldn't you use a different metatype?

----------------------------------------------------------------------

Comment By: Martin v. Löwis (loewis)
Date: 2002-04-12 10:23

Message:
Logged In: YES 
user_id=21627

Invoking str() on all doc strings has been considered and
rejected; it is desirable that Unicode doc strings come out
as-is.

I'm not sure what kind of patch you are suggesting; if I
merely revert typeobject.c 2.130 (i.e. removing the
type.__doc__ getter), then property.__doc__ will not be the
doc string of property, but the __doc__ member. This is
undesirable.

----------------------------------------------------------------------

Comment By: James Henstridge (jhenstridge)
Date: 2002-04-12 09:39

Message:
Logged In: YES 
user_id=146903

damn.  I was on the plane back from GUADEC then and am still
catching up with things :(  Sorry about that.

----------------------------------------------------------------------

Comment By: James Henstridge (jhenstridge)
Date: 2002-04-12 09:37

Message:
Logged In: YES 
user_id=146903

Here is a patch for inspect.py that fixes the bug reported
in #530070 without breaking the use of descriptors for
__doc__.  I think this patch would be a good candidate for
2.2.1 (along with backing out the patch on #530070).

I am sorry that I didn't bring this up earlier -- I hadn't
realised there was any other patches to the __doc__ handling
in the 2.2 maintenance branch.

----------------------------------------------------------------------

Comment By: Michael Hudson (mwh)
Date: 2002-04-12 09:35

Message:
Logged In: YES 
user_id=6656

James, Python 2.2.1 was released two days ago.  Nothing can
change that now...

----------------------------------------------------------------------

You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=105470&aid=542984&group_id=5470