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.

I think it's fine to include it in 2.7.

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.

Whoops, forgot to attach.  *Here's* the patch.

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.

Attached is r2 of the patch, incorporating Nick's suggestions.  Base revision hasn't changed.

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 regrtest.py.

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 ;-)

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.

New changeset d0af22b65889 by Larry Hastings in branch '2.7':
Issue #13053: Added section on migrating from CObject to Capsule
http://hg.python.org/cpython/rev/d0af22b65889

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".)

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.)
http://hg.python.org/cpython/rev/28849d00a41e

New changeset c316e8a4a5e2 by Larry Hastings in branch 'default':
Merge: Propagate changes for issues #13053 and #13086 from 2.7 to 3.2.
http://hg.python.org/cpython/rev/c316e8a4a5e2

Now checked in to 2.7, 3.2, and default.  Thanks everyone!

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.