Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 7b5649c

Browse files
larryhastingslarryhastings
committed
Merge: Propagate changes for issues #13053 and #13086 from 2.7 to 3.2.
(Doc only.)
2 parents 3692453 + 62417a0 commit 7b5649c

2 files changed

Lines changed: 219 additions & 26 deletions

File tree

‎Doc/howto/cporting.rst‎

Lines changed: 85 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -2,27 +2,28 @@
22

33
.. _cporting-howto:
44

5-
********************************
6-
Porting Extension Modules to 3.0
7-
********************************
5+
*************************************
6+
Porting Extension Modules to Python 3
7+
*************************************
88

99
:author: Benjamin Peterson
1010

1111

1212
.. topic:: Abstract
1313

14-
Although changing the C-API was not one of Python 3.0's objectives, the many
15-
Python level changes made leaving 2.x's API intact impossible. In fact, some
16-
changes such as :func:`int` and :func:`long` unification are more obvious on
17-
the C level. This document endeavors to document incompatibilities and how
18-
they can be worked around.
14+
Although changing the C-API was not one of Python 3's objectives,
15+
the many Python-level changes made leaving Python 2's API intact
16+
impossible. In fact, some changes such as :func:`int` and
17+
:func:`long` unification are more obvious on the C level. This
18+
document endeavors to document incompatibilities and how they can
19+
be worked around.
1920

2021

2122
Conditional compilation
2223
=======================
2324

24-
The easiest way to compile only some code for 3.0 is to check if
25-
:c:macro:`PY_MAJOR_VERSION` is greater than or equal to 3. ::
25+
The easiest way to compile only some code for Python 3 is to check
26+
if :c:macro:`PY_MAJOR_VERSION` is greater than or equal to 3. ::
2627

2728
#if PY_MAJOR_VERSION >= 3
2829
#define IS_PY3K
@@ -35,22 +36,22 @@ conditional blocks.
3536
Changes to Object APIs
3637
======================
3738

38-
Python 3.0 merged together some types with similar functions while cleanly
39+
Python 3 merged together some types with similar functions while cleanly
3940
separating others.
4041

4142

4243
str/unicode Unification
4344
-----------------------
4445

4546

46-
Python 3.0's :func:`str` (``PyString_*`` functions in C) type is equivalent to
47-
2.x's :func:`unicode` (``PyUnicode_*``). The old 8-bit string type has become
48-
:func:`bytes`. Python 2.6 and later provide a compatibility header,
47+
Python 3's :func:`str` (``PyString_*`` functions in C) type is equivalent to
48+
Python 2's :func:`unicode` (``PyUnicode_*``). The old 8-bit string type has
49+
become :func:`bytes`. Python 2.6 and later provide a compatibility header,
4950
:file:`bytesobject.h`, mapping ``PyBytes`` names to ``PyString`` ones. For best
50-
compatibility with 3.0, :c:type:`PyUnicode` should be used for textual data and
51+
compatibility with Python 3, :c:type:`PyUnicode` should be used for textual data and
5152
:c:type:`PyBytes` for binary data. It's also important to remember that
52-
:c:type:`PyBytes` and :c:type:`PyUnicode` in 3.0 are not interchangeable like
53-
:c:type:`PyString` and :c:type:`PyUnicode` are in 2.x. The following example
53+
:c:type:`PyBytes` and :c:type:`PyUnicode` in Python 3 are not interchangeable like
54+
:c:type:`PyString` and :c:type:`PyUnicode` are in Python 2. The following example
5455
shows best practices with regards to :c:type:`PyUnicode`, :c:type:`PyString`,
5556
and :c:type:`PyBytes`. ::
5657

@@ -94,10 +95,12 @@ and :c:type:`PyBytes`. ::
9495
long/int Unification
9596
--------------------
9697

97-
In Python 3.0, there is only one integer type. It is called :func:`int` on the
98-
Python level, but actually corresponds to 2.x's :func:`long` type. In the
99-
C-API, ``PyInt_*`` functions are replaced by their ``PyLong_*`` neighbors. The
100-
best course of action here is using the ``PyInt_*`` functions aliased to
98+
Python 3 has only one integer type, :func:`int`. But it actually
99+
corresponds to Python 2's :func:`long` type--the :func:`int` type
100+
used in Python 2 was removed. In the C-API, ``PyInt_*`` functions
101+
are replaced by their ``PyLong_*`` equivalents.
102+
103+
The best course of action here is using the ``PyInt_*`` functions aliased to
101104
``PyLong_*`` found in :file:`intobject.h`. The abstract ``PyNumber_*`` APIs
102105
can also be used in some cases. ::
103106

@@ -120,10 +123,11 @@ can also be used in some cases. ::
120123
Module initialization and state
121124
===============================
122125

123-
Python 3.0 has a revamped extension module initialization system. (See
124-
:pep:`3121`.) Instead of storing module state in globals, they should be stored
125-
in an interpreter specific structure. Creating modules that act correctly in
126-
both 2.x and 3.0 is tricky. The following simple example demonstrates how. ::
126+
Python 3 has a revamped extension module initialization system. (See
127+
:pep:`3121`.) Instead of storing module state in globals, they should
128+
be stored in an interpreter specific structure. Creating modules that
129+
act correctly in both Python 2 and Python 3 is tricky. The following
130+
simple example demonstrates how. ::
127131

128132
#include "Python.h"
129133

@@ -209,10 +213,65 @@ both 2.x and 3.0 is tricky. The following simple example demonstrates how. ::
209213
}
210214

211215

216+
CObject replaced with Capsule
217+
=============================
218+
219+
The :c:type:`Capsule` object was introduced in Python 3.1 and 2.7 to replace
220+
:c:type:`CObject`. CObjects were useful,
221+
but the :c:type:`CObject` API was problematic: it didn't permit distinguishing
222+
between valid CObjects, which allowed mismatched CObjects to crash the
223+
interpreter, and some of its APIs relied on undefined behavior in C.
224+
(For further reading on the rationale behind Capsules, please see :issue:`5630`.)
225+
226+
If you're currently using CObjects, and you want to migrate to 3.1 or newer,
227+
you'll need to switch to Capsules.
228+
:c:type:`CObject` was deprecated in 3.1 and 2.7 and completely removed in
229+
Python 3.2. If you only support 2.7, or 3.1 and above, you
230+
can simply switch to :c:type:`Capsule`. If you need to support Python 3.0,
231+
or versions of Python earlier than 2.7,
232+
you'll have to support both CObjects and Capsules.
233+
(Note that Python 3.0 is no longer supported, and it is not recommended
234+
for production use.)
235+
236+
The following example header file :file:`capsulethunk.h` may
237+
solve the problem for you. Simply write your code against the
238+
:c:type:`Capsule` API and include this header file after
239+
:file:`Python.h`. Your code will automatically use Capsules
240+
in versions of Python with Capsules, and switch to CObjects
241+
when Capsules are unavailable.
242+
243+
:file:`capsulethunk.h` simulates Capsules using CObjects. However,
244+
:c:type:`CObject` provides no place to store the capsule's "name". As a
245+
result the simulated :c:type:`Capsule` objects created by :file:`capsulethunk.h`
246+
behave slightly differently from real Capsules. Specifically:
247+
248+
* The name parameter passed in to :c:func:`PyCapsule_New` is ignored.
249+
250+
* The name parameter passed in to :c:func:`PyCapsule_IsValid` and
251+
:c:func:`PyCapsule_GetPointer` is ignored, and no error checking
252+
of the name is performed.
253+
254+
* :c:func:`PyCapsule_GetName` always returns NULL.
255+
256+
* :c:func:`PyCapsule_SetName` always throws an exception and
257+
returns failure. (Since there's no way to store a name
258+
in a CObject, noisy failure of :c:func:`PyCapsule_SetName`
259+
was deemed preferable to silent failure here. If this is
260+
inconveient, feel free to modify your local
261+
copy as you see fit.)
262+
263+
You can find :file:`capsulethunk.h` in the Python source distribution
264+
in the :file:`Doc/includes` directory. We also include it here for
265+
your reference; here is :file:`capsulethunk.h`:
266+
267+
.. literalinclude:: ../includes/capsulethunk.h
268+
269+
270+
212271
Other options
213272
=============
214273

215274
If you are writing a new extension module, you might consider `Cython
216275
<http://www.cython.org>`_. It translates a Python-like language to C. The
217-
extension modules it creates are compatible with Python 3.x and 2.x.
276+
extension modules it creates are compatible with Python 3 and Python 2.
218277

‎Doc/includes/capsulethunk.h‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
#ifndef __CAPSULETHUNK_H
2+
#define __CAPSULETHUNK_H
3+
4+
#if ( (PY_VERSION_HEX < 0x02070000) \
5+
|| ((PY_VERSION_HEX >= 0x03000000) \
6+
&& (PY_VERSION_HEX < 0x03010000)) )
7+
8+
#define __PyCapsule_GetField(capsule, field, default_value) \
9+
( PyCapsule_CheckExact(capsule) \
10+
? (((PyCObject *)capsule)->field) \
11+
: (default_value) \
12+
) \
13+
14+
#define __PyCapsule_SetField(capsule, field, value) \
15+
( PyCapsule_CheckExact(capsule) \
16+
? (((PyCObject *)capsule)->field = value), 1 \
17+
: 0 \
18+
) \
19+
20+
21+
#define PyCapsule_Type PyCObject_Type
22+
23+
#define PyCapsule_CheckExact(capsule) (PyCObject_Check(capsule))
24+
#define PyCapsule_IsValid(capsule, name) (PyCObject_Check(capsule))
25+
26+
27+
#define PyCapsule_New(pointer, name, destructor) \
28+
(PyCObject_FromVoidPtr(pointer, destructor))
29+
30+
31+
#define PyCapsule_GetPointer(capsule, name) \
32+
(PyCObject_AsVoidPtr(capsule))
33+
34+
/* Don't call PyCObject_SetPointer here, it fails if there's a destructor */
35+
#define PyCapsule_SetPointer(capsule, pointer) \
36+
__PyCapsule_SetField(capsule, cobject, pointer)
37+
38+
39+
#define PyCapsule_GetDestructor(capsule) \
40+
__PyCapsule_GetField(capsule, destructor)
41+
42+
#define PyCapsule_SetDestructor(capsule, dtor) \
43+
__PyCapsule_SetField(capsule, destructor, dtor)
44+
45+
46+
/*
47+
* Sorry, there's simply no place
48+
* to store a Capsule "name" in a CObject.
49+
*/
50+
#define PyCapsule_GetName(capsule) NULL
51+
52+
static int
53+
PyCapsule_SetName(PyObject *capsule, const char *unused)
54+
{
55+
unused = unused;
56+
PyErr_SetString(PyExc_NotImplementedError,
57+
"can't use PyCapsule_SetName with CObjects");
58+
return 1;
59+
}
60+
61+
62+
63+
#define PyCapsule_GetContext(capsule) \
64+
__PyCapsule_GetField(capsule, descr)
65+
66+
#define PyCapsule_SetContext(capsule, context) \
67+
__PyCapsule_SetField(capsule, descr, context)
68+
69+
70+
static void *
71+
PyCapsule_Import(const char *name, int no_block)
72+
{
73+
PyObject *object = NULL;
74+
void *return_value = NULL;
75+
char *trace;
76+
size_t name_length = (strlen(name) + 1) * sizeof(char);
77+
char *name_dup = (char *)PyMem_MALLOC(name_length);
78+
79+
if (!name_dup) {
80+
return NULL;
81+
}
82+
83+
memcpy(name_dup, name, name_length);
84+
85+
trace = name_dup;
86+
while (trace) {
87+
char *dot = strchr(trace, '.');
88+
if (dot) {
89+
*dot++ = '\0';
90+
}
91+
92+
if (object == NULL) {
93+
if (no_block) {
94+
object = PyImport_ImportModuleNoBlock(trace);
95+
} else {
96+
object = PyImport_ImportModule(trace);
97+
if (!object) {
98+
PyErr_Format(PyExc_ImportError,
99+
"PyCapsule_Import could not "
100+
"import module \"%s\"", trace);
101+
}
102+
}
103+
} else {
104+
PyObject *object2 = PyObject_GetAttrString(object, trace);
105+
Py_DECREF(object);
106+
object = object2;
107+
}
108+
if (!object) {
109+
goto EXIT;
110+
}
111+
112+
trace = dot;
113+
}
114+
115+
if (PyCObject_Check(object)) {
116+
PyCObject *cobject = (PyCObject *)object;
117+
return_value = cobject->cobject;
118+
} else {
119+
PyErr_Format(PyExc_AttributeError,
120+
"PyCapsule_Import \"%s\" is not valid",
121+
name);
122+
}
123+
124+
EXIT:
125+
Py_XDECREF(object);
126+
if (name_dup) {
127+
PyMem_FREE(name_dup);
128+
}
129+
return return_value;
130+
}
131+
132+
#endif /* #if PY_VERSION_HEX < 0x02070000 */
133+
134+
#endif /* __CAPSULETHUNK_H */

0 commit comments

Comments
 (0)