[Python-3000] how should we handle changes to the C API?

[Brett Cannon]

I know it has been said that extension modules will, at minimum, need
to recompile.  But what about changes to the API that are semantic?

What I am thinking of in general is getting rid of deprecated
functions and replacing them with their *Ex equilvalents (e.g.,
replace PyErr_Warn() with PyErr_WarnEx() and thus only having one
warning function).  Do we want a PEP specific of what C functions are
going to change and for what reason?

My specific need is that PyErr_GivenExceptionMatches() does not have
an exception return value.  This sucks for me in 2.6 for deprecating
catching string exceptions, but it sucks more in 3.0 since only
subclasses of BaseException can be raised.  But not allowing -1 to
represent that an error occurred is a pain for anyone who wants to
properly use the function.

This means that in 3.0 I want to change the meaning of
PyErr_GivenExceptionMatches(), but obviously this single change does
not need its own PEP.  Then again, there are a bunch of *Ex() modules
that could stand to be renamed and ditch the old way.

Should I just toss all of this into PEP 3100 (and add a C API
section), or should I start a new PEP that lists all general C API
changes (assuming that people are willing to rename C functions)?

-Brett