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

[Tim Peters]

[Moore, Paul, on
 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.
>
> People upgrading their extensions would find the older
> information useful

I'm not sure how.  If their extensions work now, there's a very high degree
of compatibility, and they should continue to work.  If they want to make
life simpler by exploiting new API features, then they need the new docs,
and the old docs say nothing useful about that (since they were written
before the newer API gimmicks were even ideas).

> (actually, an "Upgrading from the older API" section would be even
> nicer, but that involves more work...)

Except that the old API still functions.  Even major abusers <wink> like
ExtensionClass still work under 2.3.

There's one sometimes-expressed need that isn't being met:  people who need
their extensions to run under many versions of Python.  The canonical
examples of extensions are in the Python core, and of course those only need
to run with the current Python release, so staring at them doesn't yield any
clues.  I'm not sure we (the developers) give it much thought, either (e.g.,
I know I don't -- the # of things I can worry about at once decreases as I
grow older <0.3 wink>).

Micheal Hudson made a nice start in that direction, with 2.3's

    Misc/pymemcompat.h

If you write your code to 2.3's simpler memory API, and #include that file,
it will translate 2.3's spellings (via macros) into older spellings back
through 1.5.2, keying off PY_VERSION_HEX to choose the right renamings.

Jim is doing something related by hand in these docs, via the unnecessary

    #ifndef PyMODINIT_FUNC	/* declarations for DLL import/export */
    #define PyMODINIT_FUNC void
    #endif

blocks.  That is, PyMODINIT_FUNC is defined (via Python.h) in 2.3, so the
development docs shouldn't encourage pretending it may not be.  It would be
a good idea to add suitable redefinitions of PyMODINIT_FUNC to pymemcompat.h
too, but whether someone will volunteer to do so is an open question.

> 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".
>
> Heck, I still have some code I wrote for the 1.4 API which still
> works.

It probably still does.

> 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... :-)

What remains unclear is what good the older documentation would do anyone.
You're going to migrate or you're not.  If you don't, you don't need the new
docs; if you do, you don't need the old docs; it's those who want to support
multiple Pythons simultaneously who need to know everything, and they really
need more help than throwing all releases' docs into one giant pile.