[Python-Dev] Deprecating C APIs (Use of PyArg_NoArgs())

[Neal Norwitz]

"M.-A. Lemburg" wrote:

> I think we should come up with a better way to deprecate C level
> APIs. NEWS is not as effective as one might wish; any deprecation
> or removal of an API should also include upgrade information
> for the C extension writer so that upgrading their modules
> does not require diving into the new style C API code every
> time.
> 
> I'd suggest to have a PEP which documents all C API changes
> or deprecations together with a short decsription of how to
> update old code.

I think a PEP will be ignored just as easily as NEWS.

Perhaps, we could wrap all deprecated functions/macros in:

#ifdef Py_DEPRECATED
#endif

So if an extension wants to use deprecated functions, they
would need to #define Py_DEPRECATED.  We could also use 
another macro Py_OBSOLETE.  In this way functions/macros 
would move into Py_DEPRECATED, then Py_OBSOLETE, then removed.

The functions would still be in a library.  And when a function
is used a warning would be produced since there is no prototype.
Not sure how to handle macros, should they remain undefined
and create errors?

If we wanted to be more heavy handed, we could create errors that
would force extensions to be compiled w/Py_DEPRECATED by doing:

#ifdef Py_DEPRECATED
#define Py_MACRO(a) do_something(a)
int Py_prototype(...);
#else
/* Create a syntax error unless Py_DEPRECATED is defined */
#define Py_MACRO(a) ===
#define Py_prototype ===
#endif

> Another aspect which we ought to consider is that C extension
> writers may have a different view of when to leave backward
> compatibility path in favour of a new Python version. IMHO,
> there should always be a way to emulate old behaviour so that
> extensions can continue to support Python 1.5.2 if they need to.

Perhaps, we could put the deprecated functions into 
a libpythoncompat.a.  It would probably be best to move the
functions out of the code they are in and into a new compat.c module.

I'm not sure how workable this idea is.

Neal