Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(5695)

Side by Side Diff: Doc/howto/cporting.rst

Issue 24937: Multiple problems in getters & setters in capsulethunk.h
Patch Set: Created 3 years, 8 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 .. highlightlang:: c 1 .. highlightlang:: c
2 2
3 .. _cporting-howto: 3 .. _cporting-howto:
4 4
5 ************************************* 5 *************************************
6 Porting Extension Modules to Python 3 6 Porting Extension Modules to Python 3
7 ************************************* 7 *************************************
8 8
9 :author: Benjamin Peterson 9 :author: Benjamin Peterson
10 10
(...skipping 189 matching lines...) Expand 10 before | Expand all | Expand 10 after
200 :c:type:`CObject`. CObjects were useful, 200 :c:type:`CObject`. CObjects were useful,
201 but the :c:type:`CObject` API was problematic: it didn't permit distinguishing 201 but the :c:type:`CObject` API was problematic: it didn't permit distinguishing
202 between valid CObjects, which allowed mismatched CObjects to crash the 202 between valid CObjects, which allowed mismatched CObjects to crash the
203 interpreter, and some of its APIs relied on undefined behavior in C. 203 interpreter, and some of its APIs relied on undefined behavior in C.
204 (For further reading on the rationale behind Capsules, please see :issue:`5630`. ) 204 (For further reading on the rationale behind Capsules, please see :issue:`5630`. )
205 205
206 If you're currently using CObjects, and you want to migrate to 3.1 or newer, 206 If you're currently using CObjects, and you want to migrate to 3.1 or newer,
207 you'll need to switch to Capsules. 207 you'll need to switch to Capsules.
208 :c:type:`CObject` was deprecated in 3.1 and 2.7 and completely removed in 208 :c:type:`CObject` was deprecated in 3.1 and 2.7 and completely removed in
209 Python 3.2. If you only support 2.7, or 3.1 and above, you 209 Python 3.2. If you only support 2.7, or 3.1 and above, you
210 can simply switch to :c:type:`Capsule`. If you need to support Python 3.0, 210 can simply switch to :c:type:`Capsule`.
211 or versions of Python earlier than 2.7, 211
212 If you need to support versions of Python earlier than 2.7, or Python 3.0,
212 you'll have to support both CObjects and Capsules. 213 you'll have to support both CObjects and Capsules.
213 (Note that Python 3.0 is no longer supported, and it is not recommended 214 (Note that Python 3.0 is no longer supported, and it is not recommended
214 for production use.) 215 for production use.)
215 216
216 The following example header file :file:`capsulethunk.h` may 217 The ``py3c`` project maintains an example header file ``capsulethunk.h``
217 solve the problem for you. Simply write your code against the 218 that can may solve the problem for you. It implements the Capsule API in terms
218 :c:type:`Capsule` API and include this header file after 219 of CObject. Simply write your code against the :c:type:`Capsule` API (with
219 :file:`Python.h`. Your code will automatically use Capsules 220 some limitations) and include this header file after :file:`Python.h`.
220 in versions of Python with Capsules, and switch to CObjects 221 Your code will automatically use Capsules in versions of Python with Capsules,
221 when Capsules are unavailable. 222 and switch to CObjects when Capsules are unavailable.
222 223
223 :file:`capsulethunk.h` simulates Capsules using CObjects. However, 224 You can find the `capsulethunk.h file`_ and its `documentation`_ in the
224 :c:type:`CObject` provides no place to store the capsule's "name". As a 225 ``py3c`` project.
225 result the simulated :c:type:`Capsule` objects created by :file:`capsulethunk.h`
226 behave slightly differently from real Capsules. Specifically:
227 226
228 * The name parameter passed in to :c:func:`PyCapsule_New` is ignored. 227 .. _capsulethunk.h file: https://github.com/encukou/py3c/blob/master/include/py3 c/capsulethunk.h
229 228 .. _documentation: http://py3c.readthedocs.org/en/latest/capsulethunk.html
230 * The name parameter passed in to :c:func:`PyCapsule_IsValid` and
231 :c:func:`PyCapsule_GetPointer` is ignored, and no error checking
232 of the name is performed.
233
234 * :c:func:`PyCapsule_GetName` always returns NULL.
235
236 * :c:func:`PyCapsule_SetName` always raises an exception and
237 returns failure. (Since there's no way to store a name
238 in a CObject, noisy failure of :c:func:`PyCapsule_SetName`
239 was deemed preferable to silent failure here. If this is
240 inconvenient, feel free to modify your local
241 copy as you see fit.)
242
243 You can find :file:`capsulethunk.h` in the Python source distribution
244 as :source:`Doc/includes/capsulethunk.h`. We also include it here for
245 your convenience:
246
247 .. literalinclude:: ../includes/capsulethunk.h
248
249 229
250 230
251 Other options 231 Other options
252 ============= 232 =============
253 233
254 If you are writing a new extension module, you might consider `Cython 234 If you are writing a new extension module, you might consider `Cython
255 <http://cython.org/>`_. It translates a Python-like language to C. The 235 <http://cython.org/>`_. It translates a Python-like language to C. The
256 extension modules it creates are compatible with Python 3 and Python 2. 236 extension modules it creates are compatible with Python 3 and Python 2.
257 237
OLDNEW
« no previous file with comments | « no previous file | no next file » | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+