remove PyEval functions

pythoncapi · Jul 31, 2018 · ad08248 · ad08248
1 parent 2e2a3cf
commit ad08248
Show file tree

Hide file tree

Showing 2 changed files with 37 additions and 7 deletions.
diff --git a/doc/bad_api.rst b/doc/bad_api.rst
@@ -65,6 +65,11 @@ Macros
 * ``PyTuple_GET_ITEM()``: access directly ``PyTupleObject.ob_item``
 * ``PyWeakref_GET_OBJECT()``: access directly ``PyWeakReference.wr_object``
 
+Borrowed references: PyEval_GetFuncName()
+=========================================
+
+* ``PyEval_GetFuncName()`` returns the internal ``const char*`` inside a
+   borrowed reference to a function ``__name__``.
 
 Array of pointers to Python objects (``PyObject**``)
 ====================================================

diff --git a/doc/remove_functions.rst b/doc/remove_functions.rst
@@ -14,20 +14,45 @@ C extensions should call abstract functions like ``PyObject_GetItem()``.
 
 See :ref:`Bad C API <bad-c-api>`.
 
-Good: abstract functions
-========================
+Only keep abstract functions
+============================
 
-Examples:
+Good: abstract functions. Examples:
 
 * ``PyObject_GetItem()``, ``PySequence_GetItem()``
 
-Bad? implementations
-====================
-
-Examples:
+Bad? implementations for concrete types. Examples:
 
 * ``PyObject_GetItem()``, ``PySequence_GetItem()``:
 
   * ``PyList_GetItem()``
   * ``PyTuple_GetItem()``
   * ``PyDict_GetItem()``
+
+Implementations for concrete types don't *have to* be part of the C API.
+Moreover, using directly them introduce bugs when the caller pass a subtype.
+For example, PyDict_GetItem() **must not** be used on a dict subtype, since
+``__getitem__()`` be be overriden for good reasons.
+
+
+Functions to call functions
+===========================
+
+
+* ``PyEval_CallFunction()``: a comment says *"PyEval_CallFunction is exact copy
+  of PyObject_CallFunction. This function is kept for backward compatibility."*
+* ``PyEval_CallMethod()``: a comment says *"PyEval_CallMethod is exact copy of
+  PyObject_CallMethod. This function is kept for backward compatibility."*
+
+Open questions
+==============
+
+Functions to call functions
+---------------------------
+
+Should we remove the following functions to make the C API smaller?
+
+* ``PyEval_CallObjectWithKeywords()``: almost duplicate ``PyObject_Call()``,
+  except that *args* (tuple of positional arguments) can be ``NULL``
+* ``PyObject_CallObject()``: almost duplicate ``PyObject_Call()``,
+  except that *args* (tuple of positional arguments) can be ``NULL``