[Python-Dev] Re: C new-style classes and GC

[Jim Fulton]

Moore, Paul wrote:
> From: Jim Fulton [mailto:jim@zope.com]
> 
>>You can read the documentation for it here:
> 
> 
>>http://www.python.org/dev/doc/devel/ext/defining-new-types.html
> 
> 
> Just looking at this, I note the "Note" at the top. The way
> this reads, it implies that details of how things used to work
> has been removed. I don't know if this is true, but I'd prefer
> if it wasn't.

The section has been rewritten. The examples are quire different
than they used to be. There's no way to document the old and new
ways together without:

- Making this a lot more confusing, and

- violating the "one way to do it" in Python rule.


> People upgrading their extensions would find the older
> information useful (actually, an "Upgrading from the older API"
> section would be even nicer, but that involves more work...)
> Having to refer to an older copy of the documentation (which they
> may not even have installed) could tip the balance between "lets
> keep up to date" and "if it works, don't fix it".

In general, I'd say that if the old extensions aren't broke, don't
fix them.  If someone *is* going to go through the trouble to update
them, then I think they can manage to get the old docs.

Further, if you have written an old extension, you probably already
know the old way to define types, so you don't need the old docs.

> Heck, I still have some code I wrote for the 1.4 API which still
> works. I've never got round to upgrading it, on the basis that
> someone might be using it with 1.5 still. But when I do, I'd
> dump pre-2.2 support, so *I* have no use for "older" documentation
> except to find out what all that old code meant... :-)
> 
> If the old information is still there, maybe it's just the tone
> of the note that should be changed.

The old information is not still there.  I'm not gonna add it back,
because it would make the document far more confusing.

Jim

-- 
Jim Fulton           mailto:jim@zope.com       Python Powered!
CTO                  (703) 361-1714            http://www.python.org
Zope Corporation     http://www.zope.com       http://www.zope.org