[Doc-SIG] suggestions for a PEP

[Guido van Rossum]

> >>> def hello(there): return there
> ... 
> >>> hello.__doc__ = 'hello there'
> >>> hello.__doc__
> 'hello there'
> >>> class A:
> ... 	def hello(there): return there
> ... 
> >>> A.hello.__doc__ = 'hello there'
> Traceback (innermost last):
>   File "<stdin>", line 1, in ?
> TypeError: attribute-less object (assign or del)
> >>> A.hello.im_func.__doc__ = 'hello there'
> >>> A.hello.__doc__
> 'hello there'
> 
> It works for functions but not if they're hanging off the namespace of a
> class ?  The attribute shows up on the class method after I set it on
> the class method's im_func ?  This is wrong, obscene and ugly !

This is intentional.  We actually changed this in 2.1b1; in the alpha
version it *was* assignable.  It turns out there are some potential
future uses where assigning to attributes of class (or instance)
methods should only affect the method in that class, not in any base
classes; in particular, it was pointed out that this can be confusing:

    class C:
        def f(self): pass
        f.foo = 1

    class D(C):
        pass
    D.f.foo = 2       # Would also change value of C.f.foo!

Similarly,

    class C:
        def f(self): pass
        f.foo = 1

    x = C()
    x.f.foo = 2      # Would also change value of C.f.foo!

The ExtensionClass module in Zope actually implements class-like
objects that behave in such a way that at least the first example
(D.f.foo = 2) changes the f.foo value for class D but not for class
C.  So this is not just theoretical!

--Guido van Rossum (home page: http://www.python.org/~guido/)