Add deprecate.rst

pythoncapi · Dec 18, 2018 · 0d809de · 0d809de
1 parent f97fed7
commit 0d809de
Show file tree

Hide file tree

Showing 2 changed files with 24 additions and 0 deletions.
diff --git a/doc/deprecate.rst b/doc/deprecate.rst
@@ -0,0 +1,23 @@
+++++++++++++++++++
+Deprecate old APIs
+++++++++++++++++++
+
+CPython is old, the code evolved. Some functions became useless and so should
+be removed. But backward compatibility matters in Python, so we need a
+transition period with a deprecation process.
+
+The deprecation can be:
+
+* Emitted at runtime: ``DeprecationWarning``
+* At the compilation: ``Py_DEPRECATED()``
+* In the documentation
+
+Functions that should deprecated:
+
+* Unicode functions using ``Py_UNICODE`` type
+* Py_VA_COPY: see `email <https://mail.python.org/pipermail/python-dev/2016-September/146537.html>`_
+
+See:
+
+* https://bugs.python.org/issue19569
+*
diff --git a/doc/index.rst b/doc/index.rst
@@ -100,4 +100,5 @@ Table of Contents
    performance
    split_include
    pyhandle
+   deprecate