Title: Add Capsule migration documentation to "cporting"
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: larry Nosy List: ezio.melotti, larry, ncoghlan, petr.viktorin, python-dev, rhettinger
Priority: normal Keywords: patch

Created on 2011-09-28 15:37 by larry, last changed 2015-09-08 11:26 by petr.viktorin. This issue is now closed.

File name Uploaded Description Edit
larry.cporting.capsules.r1.diff larry, 2011-10-01 11:14 review
larry.cporting.capsules.r2.diff larry, 2011-10-02 23:23 revision 2 of my patch review
larry.cporting.capsules.r3.diff larry, 2011-10-04 23:01 review
Messages (14)
msg144567 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2011-09-28 15:37
After the great Capsule flame wars of 2011, it became clear that we need documentation on migrating from CObject to Capsules, as CObject is gone as of 3.2.  Nick made me promise to write the documentation, and Raymond steered me in the direction of "cporting.rst" (Porting Extension Modules To Python 3.0).

I already have a patch in reasonable shape.  However, I understand we're doing "forward-porting" (what Monotone calls "daggy fixes").  I think this would be valuable information for 2.7 users.  It includes no code changes (though it does include some sample code).  Would checking it in to the 2.7 head be appropriate?  Once we decide where the checkin should go, I'll produce a patch against that head that will hopefully garner your approval.
msg144581 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-09-29 00:12
I think it's fine to include it in 2.7.
msg144724 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2011-10-01 11:13
Attached is a patch against trunk branch "2.7" (rev dec00ae64ca8) adding documentation on how to migrate CObjects to Capsules.  Delta the inevitable formatting bikeshedding, this should be ready to go.  I've smoke-tested the "capsulethunk.h" locally and it works fine.

When accepted, I'll check this in to the 2.7 branch, then merge into the 3.1, 3.2, and trunk branches.
msg144725 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2011-10-01 11:14
Whoops, forgot to attach.  *Here's* the patch.
msg144786 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2011-10-02 22:31
Mostly looks good - couple of minor comments in Reitveld.

As far as the patch flow goes, the 2.x and 3.x branches are actually handled independently (they're too divergent for merging to make sense).

So 2.7 and 3.2 will be independent commits, then the changes will be merged into default from the 3.2 branch.
msg144793 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2011-10-02 23:23
Attached is r2 of the patch, incorporating Nick's suggestions.  Base revision hasn't changed.
msg144794 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2011-10-02 23:30
In case you're curious, here's how I tested "capsulethunk.h".  I added the file to Python 2.7 (hg head), 3.0.0 (tarball), and 3.1.0 (tarball).  For 2.7 ad 3.0.0 I quickly hacked four files to use the Capsule API instead of CObjects:
 * Python/compile.c
 * Python/getargs.c
 * Modules/_ctypes/callproc.c
 * Modules/_ctypes/cfield.c
(For 3.1 I simply included the file in those four files, as they already use the Capsule API.)  I then built and ran

While developing capsulethunk.h, I had a more thorough test suite; sadly that's on a laptop that is shut off, and I'm on vacation across the Atlantic and can't get at it.  But everything was working fine last I checked ;-)
msg144928 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2011-10-04 23:01
New patch based on comments from Ezio Melotti--thanks, Ezio!

* capsulethunk.h is now its own file in Doc/includes.
* Various minor formatting touchups.
* I added some rationale behind the thunked PyCapsule_SetName behavior.
msg145253 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-10-09 12:07
New changeset d0af22b65889 by Larry Hastings in branch '2.7':
Issue #13053: Added section on migrating from CObject to Capsule
msg154411 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2012-02-26 22:32
I have some more changes for cporting.rst (see #13086).  Once those are in, I'll manually merge the edits over to 3.2, then forward-port to trunk.  Does anyone want to see those as patches before I commit them?  (Your silence will be interpreted as "go ahead and commit, no patches necessary".)
msg154584 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-02-29 00:24
New changeset 28849d00a41e by Larry Hastings in branch '3.2':
Propagate changes for issues #13053 and #13086 from 2.7 to 3.2.  (Doc only.)
msg154586 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-02-29 00:30
New changeset c316e8a4a5e2 by Larry Hastings in branch 'default':
Merge: Propagate changes for issues #13053 and #13086 from 2.7 to 3.2.
msg154587 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2012-02-29 00:31
Now checked in to 2.7, 3.2, and default.  Thanks everyone!
msg250183 - (view) Author: Petr Viktorin (petr.viktorin) * (Python committer) Date: 2015-09-08 11:26
As capsulethunk.h is only needed for Python 2.6 and below, which are no longer maintained, in issue24937 we are discussing moving the header to an external project.
Date User Action Args
2015-09-08 11:26:48petr.viktorinsetnosy: + petr.viktorin
messages: + msg250183
2012-02-29 09:02:26ezio.melottisetstage: needs patch -> resolved
versions: + Python 2.7, Python 3.2
2012-02-29 00:31:58larrysetstatus: open -> closed
resolution: fixed
messages: + msg154587
2012-02-29 00:30:55python-devsetmessages: + msg154586
2012-02-29 00:24:09python-devsetmessages: + msg154584
2012-02-26 22:32:49larrysetmessages: + msg154411
2011-10-09 12:07:46python-devsetnosy: + python-dev
messages: + msg145253
2011-10-04 23:01:22larrysetfiles: + larry.cporting.capsules.r3.diff

messages: + msg144928
2011-10-02 23:30:05larrysetmessages: + msg144794
2011-10-02 23:23:54larrysetfiles: + larry.cporting.capsules.r2.diff

messages: + msg144793
2011-10-02 22:31:53ncoghlansetmessages: + msg144786
2011-10-01 11:14:36larrysetfiles: + larry.cporting.capsules.r1.diff
keywords: + patch
messages: + msg144725
2011-10-01 11:13:56larrysetmessages: + msg144724
2011-09-29 00:12:04ezio.melottisetnosy: + ezio.melotti
messages: + msg144581
2011-09-28 15:37:27larrycreate