classification
Title: Multiple problems in getters & setters in capsulethunk.h
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: berker.peksag, docs@python, larry, ncoghlan, petr.viktorin
Priority: normal Keywords: patch

Created on 2015-08-25 16:41 by petr.viktorin, last changed 2018-08-05 00:35 by berker.peksag.

Files
File name Uploaded Description Edit
capsulethunk.patch petr.viktorin, 2015-08-25 16:41 review
capsulethunk-py3c.patch petr.viktorin, 2015-09-08 11:19 review
Messages (8)
msg249138 - (view) Author: Petr Viktorin (petr.viktorin) * (Python committer) Date: 2015-08-25 16:41
In https://docs.python.org/3/howto/cporting.html#cobject-replaced-with-capsule (added in issue13053):

1) __PyCapsule_GetField is defined as::

    #define __PyCapsule_GetField(capsule, field, default_value) ...

but called as::

    __PyCapsule_GetField(capsule, field)


2) __PyCapsule_SetField returns the wrong value (1 for success, 0 for failure).

3) Both the getter and setter don't set the exception on failure, leading to "SystemError: error return without exception set".

Here's a patch.
msg249139 - (view) Author: Petr Viktorin (petr.viktorin) * (Python committer) Date: 2015-08-25 16:58
Note:
I'm including a tested (+fixed, now) copy of capsulethunk.h in my set of Python3 C extension porting helpers, http://py3c.readthedocs.org

Unfortunately the tests can't be added to CPython, because they need to run on Python 2.6 to be useful. That makes me think an external project might make a better home for this piece of code.
If you agree, I can take over maintainership of capsulethunk, and make py3c the canonical home for it.
msg249140 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2015-08-25 17:11
Given that capsulethunk is only needed for 2.6 (and previous), and those versions are no longer maintained by the Python core community, yes I'd be happy for you to take over maintainership and host it externally.  I'm sure we could change the documentation in 2.7, 3.4, and 3.5 to reflect this.
msg249156 - (view) Author: Petr Viktorin (petr.viktorin) * (Python committer) Date: 2015-08-25 19:21
Thanks! I'll take good care of it :)
Give me a few days to prepare the docs change; this isn't very high priority.
msg250181 - (view) Author: Petr Viktorin (petr.viktorin) * (Python committer) Date: 2015-09-08 11:19
This patch removes capsulethunk.h from the docs, and directs the kind reader to the py3c project, which carries a fixed and tested version of it, along with the docs.


Larry, would you be OK with releasing capsulethunk.h under the MIT license? The PSF license is not suitable for external projects, and mixing licenses is somewhat awkward.
msg250191 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2015-09-08 12:32
I'm the author of capsulethunk.h, and I am happy to relicense it under MIT.

How would you feel about leaving capsulethunk.h there, for posterity's sakes, but adding "for updates please see py3c"?  We could even update the capsulethunk.h there.  I'm not saying "we have to do it this way", I'm asking whether the users would be better served by leaving the example around vs removing it and forcing them to go looking on an external web site.
msg250198 - (view) Author: Petr Viktorin (petr.viktorin) * (Python committer) Date: 2015-09-08 13:37
Thank you for the license.

I mentioned my project mainly as a place where this code can be *tested*. I have no problem with keeping capsulethunk.h in the Python docs, and synchronizing the two projects if changes are made on either side. In other words, feel free to use the first patch :)

Regarding users – in my opinion, including a whole header directly in the docs is questionable (to me it smells of untested copy-paste code), and the link goes to hg.python.org – an external site from the users' point of view.
Also, if someone needs to port CObject, their extension is very likely to be complicated enough to need much more material than the HOWTO provides.
See py3c's `modernization docs`_ for several things the HOWTO doesn't address.
So, in my obviously biased opinion, linking to py3c will help users.
(Perhaps a link to py3c should be at the top of the HOWTO, but that's not for this issue. I'm working to get to a point where I'm comfortable suggesting that.)

There's obviously the question of whether I should be improving the HOWTO rather than starting my own thing. I have three reasons: testability, the fact that py3c docs are already way too long for a HOWTO, and the fact that py3c is quite opinionated. (The more opinionated, the more more in-depth the solutions can be. I've been toning it down lately, though.)


_ modernization docs: http://py3c.readthedocs.org/en/latest/guide-modernization.html
msg323125 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2018-08-05 00:35
It would be nice to remove PyCObject_* entries from Doc/data/refcounts.dat.

+.. _documentation: http://py3c.readthedocs.org/en/latest/capsulethunk.html

Nit: We could the HTTPS link.
History
Date User Action Args
2018-08-05 00:35:56berker.peksagsetversions: + Python 3.7, Python 3.8, - Python 2.7, Python 3.2, Python 3.5
nosy: + berker.peksag

messages: + msg323125

type: enhancement
stage: patch review
2015-09-08 13:37:29petr.viktorinsetmessages: + msg250198
2015-09-08 12:32:21larrysetmessages: + msg250191
2015-09-08 11:19:39petr.viktorinsetfiles: + capsulethunk-py3c.patch

messages: + msg250181
versions: - Python 3.3, Python 3.4
2015-08-25 19:21:07petr.viktorinsetmessages: + msg249156
2015-08-25 17:11:50larrysetmessages: + msg249140
2015-08-25 16:58:50petr.viktorinsetmessages: + msg249139
2015-08-25 16:41:32petr.viktorincreate