[Python-Dev] deprecating APIs

[Guido van Rossum]

> Are we still planning to provide a mechanism to declare APIs, etc as
> deprecated?

I think this is a neat idea.

> I have this code added to pyport.h which works for gcc:
> 
>     /* Py_DEPRECATED(version)
>      * Declare a macro or function deprecated.
>      * Usage:
>      *    extern int old_var Py_DEPRECATED(2.3);
>      *    typedef int T1 Py_DEPRECATED(2.4);
>      *    extern int x() Py_DEPRECATED(2.5);
>      */
>     #if defined(__GNUC__) && (__GNUC__ == 3) && (__GNUC_MINOR__ >= 1)
>     #define Py_DEPRECATED(VERSION_UNUSED) __attribute__((__deprecated__))
>     #else
>     #define Py_DEPRECATED(VERSION_UNUSED) 
>     #endif
> 
> The version number is not necessary.  It is only for documentation.
> I don't know how to support other compilers.

What does this do under GCC?  I suppose it issues a warning when you
use the deprecated API?

> We could add Py_USE_DEPRECATED and/or Py_HIDE_DEPRECATED for
> providing/hiding access to deprecated features.
> 
>     #ifdef Py_USE_DEPRECATED
>     #define Py_SOME_DEPRECATED_MACRO
>     #endif
> 
> or
> 
>     #ifndef Py_HIDE_DEPRECATED
>     #define Py_SOME_DEPRECATED_MACRO
>     #endif
> 
> Unfortunately, the Py_DEPRECATED macro doesn't work with macros, so we
> would have to use Py_USE_DEPRECATED/Py_HIDE_DEPRECATED around
> deprecated macros.

That's OK.  Just the fact that when reading the .h files one sees the
DEPRECATED keyword should be a big hint...

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