8000 removed functions · adamtheturtle/pythoncapi@a5d309b · GitHub
[go: up one dir, main page]
Skip to content

Commit a5d309b

Browse files
vstinnervstinner
committed
removed functions
1 parent 343fd88 commit a5d309b

File tree

5 files changed

+93
-77
lines changed

5 files changed

+93
-77
lines changed

‎doc/bad_api.rst

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,13 @@ The first step to change the Python C API is to define what is a good and a bad
88
C API. The goal is to hide :ref:`implementation details <impl-details>`. The
99
:ref:`new C API <new-c-api>` must not leak implementation details anymore.
1010

11-
See also :ref:`Remove functions <remove-funcs>`.
11+
The Python C API is just too big. For performance reasons, CPython calls
12+
internally directly the implementation of a function instead of using the
13+
abstract API. For example, ``PyDict_GetItem()`` is preferred over
14+
``PyObject_GetItem()``. Inside, CPython, such optimization is fine. But
15+
exposing so many functions is an issue: CPython has to keep backward
16+
compatibility, PyPy has to implement all these functions, etc. Third party
17+
C extensions should call abstract functions like ``PyObject_GetItem()``.
1218

1319
.. _borrowed-ref:
1420

@@ -147,6 +153,45 @@ See the discussion on capi-sig: `Open questions about borrowed reference.
147153
(Sept 2018).
148154

149155

156+
Duplicated functions
157+
====================
158+
159+
* ``PyEval_CallObjectWithKeywords()``: almost duplicate ``PyObject_Call()``,
160+
except that *args* (tuple of positional arguments) can be ``NULL``
161+
* ``PyObject_CallObject()``: almost duplicate ``PyObject_Call()``,
162+
except that *args* (tuple of positional arguments) can be ``NULL``
163+
164+
165+
Only keep abstract functions?
166+
=============================
167+
168+
Good: abstract functions. Examples:
169+
170+
* ``PyObject_GetItem()``, ``PySequence_GetItem()``
171+
172+
Bad? implementations for concrete types. Examples:
173+
174+
* ``PyObject_GetItem()``, ``PySequence_GetItem()``:
175+
176+
* ``PyList_GetItem()``
177+
* ``PyTuple_GetItem()``
178+
* ``PyDict_GetItem()``
179+
180+
Implementations for concrete types don't *have to* be part of the C API.
181+
Moreover, using directly them introduce bugs when the caller pass a subtype.
182+
For example, PyDict_GetItem() **must not** be used on a dict subtype, since
183+
``__getitem__()`` be be overriden for good reasons.
184+
185+
186+
Functions kept for backward compatibility
187+
=========================================
188+
189+
* ``PyEval_CallFunction()``: a comment says *"PyEval_CallFunction is exact copy
190+
of PyObject_CallFunction. This function is kept for backward compatibility."*
191+
* ``PyEval_CallMethod()``: a comment says *"PyEval_CallMethod is exact copy of
192+
PyObject_CallMethod. This function is kept for backward compatibility."*
193+
194+
150195
No public C functions if it can't be done in Python
151196
===================================================
152197

‎doc/cython.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
.. _cython:
22

3-
++++++++++++++++++++++++++++++++++
4-
The Cython C-Extensions for Python
5-
++++++++++++++++++++++++++++++++++
3+
++++++
4+
Cython
5+
++++++
66

77
An alternative to using the C API directly is to rewrite a C extension using
88
`Cython <http://cython.org/>`__ which generates C code using the C API.

‎doc/index.rst

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Pages
3131
=====
3232

3333
.. toctree::
34-
:maxdepth: 2
34+
:maxdepth: 1
3535

3636
rationale
3737
roadmap
@@ -62,3 +62,31 @@ Links
6262
(this documentation can be found in the ``doc/`` subdirectory).
6363
* `capi-sig mailing list
6464
<https://mail.python.org/mm3/mailman3/lists/capi-sig.python.org/>`_
65+
66+
Table of Contents
67+
=================
68+
69+
.. toctree::
70+
:maxdepth: 2
71+
72+
rationale
73+
roadmap
74+
bad_api
75+
new_api
76+
runtimes
77+
old_c_api
78+
type_object
79+
remove_functions
80+
optimization_ideas
81+
backward_compatibility
82+
os_vendors
83+
calling_conventions
84+
stable_abi
85+
consumers
86+
cpyext
87+
cython
88+
cffi
89+
remove_c_api
90+
performance
91+
split_include
92+

‎doc/new_api.rst

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,27 @@ Design goals
1515
question remains if it will be possible to replace ``Py_INCREF()`` and
1616
``Py_DECREF()`` with function calls without killing performances.
1717
* Reduce the size of the C API to reduce the maintenance burden of :ref:`Python
18-
implementations other than CPython <other-python-impl>`: :ref:`Remove
19-
functions <remove-funcs>`.
18+
implementations other than CPython <other-python-impl>`: remove functions.
2019
* Reduce the size of the ABI, especially export less symbols.
2120

2221
The :ref:`backward compatibility <back-compat>` issue is partially solved by
2322
keeping the existing :ref:`old C API <old-c-api>` available as an opt-in option:
2423
see the :ref:`Regular runtime <regular-runtime>`.
2524

25+
.. _remove-funcs:
26+
27+
Remove functions and macros
28+
===========================
29+
30+
Removed functions and macros because they use :ref:`borrowed references
31+
<borrowed-ref>`:
32+
33+
* ``Py_TYPE()``
34+
* ``PyTuple_GET_ITEM()``
35+
* ``PyTuple_GetItem()``
36+
* ``PyTuple_SetItem()``
37+
* ``PyTuple_SET_ITEM()``
38+
2639
New functions
2740
=============
2841

‎doc/remove_functions.rst

Lines changed: 0 additions & 70 deletions
This file was deleted.

0 commit comments

Comments
 (0)
0