In the documentation for Python 2.X at:

http://docs.python.org/2/extending/extending.html#a-simple-example

it says:

"""
The self argument points to the module object for module-level functions; for a method it would point to the object instance.
"""

In respect of module-level functions this is misleading or arguably wrong.

If one uses Py_InitModule() or Py_InitModule3(), then self is actually passed through as NULL for module-level functions in Python 2.

There is a caveat on use of Py_InitModule4() which used to be mentioned in documentation for Python 2.6 at:

http://docs.python.org/release/2.6.7/c-api/structures.html#METH_VARARGS

where it says:

"""
This is the typical calling convention, where the methods have the type PyCFunction. The function expects two PyObject* values. The first one is the self object for methods; for module functions, it has the value given to Py_InitModule4() (or NULL if Py_InitModule() was used).
"""

Although one can supply a special argument to Py_InitModule4() which will be supplied as self, this still isn't the module object and in fact the module object for the module will not even exist at the point Py_InitModule4() is called so it is not possible to pass it in. Plus within the init function of an extension, the module object is not that which would end up being used in a specific interpreter due to how the init function is only called once and a copy then made of the module for each interpreter.

This actual page in the documentation was changed in Python 2.7 and now in:

http://docs.python.org/2/c-api/structures.html#METH_VARARGS

says:

"""
The function expects two PyObject* values. The first one is the self object for methods; for module functions, it is the module object.
"""

So the reference to Py_InitModule4() was removed and simply says that module object is supplied, which isn't actually the case.

Now, that NULL is always passed for Py_InitModule() and Py_InitModule3() is the case with Python 2. In Python 3 at some point, the code in Python internals was changed so the module object is actually passed as documented.

So, maybe the intent was that when in Python 3 the code was changed to pass the module object to module-level functions that it be back ported to Python 2.7 and the documentation so changed, but looks like that back porting was never done, or if it was, it has been broken somewhere along the way.

Code used to verify this is all attached.

If compiled and installed for Python 3 one gets:

>>> import mymodule._extension
>>> id(mymodule._extension)
4480540328
>>> mymodule._extension.function()
<module 'mymodule._extension' from '/Users/graham/Projects/python-c-extension-template/lib/python3.3/site-packages/mymodule/_extension.so'>
>>> id(mymodule._extension.function())
4480540328

If compiled and installed for Python 2.7 one gets:

>>> import mymodule._extension
>>> id(mymodule._extension)
4554745960
>>> mymodule._extension.function()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: no module supplied for self

The function in the extension module was doing:

static PyObject *extension_function(PyObject *self, PyObject *args)
{
    if (!self) {
        PyErr_SetString(PyExc_TypeError, "no module supplied for self");
        return NULL;
    }

    Py_INCREF(self);
    return self;
}

At this stage is this something that we'd want to back port or fix in 2.7 or would a doc change suffice?

New changeset 59fe0ff02c90 by Georg Brandl in branch '2.7':
Closes #19071: "self" argument is not the module for module functions in 2.x.
https://hg.python.org/cpython/rev/59fe0ff02c90