[docs] [issue19071] Documentation on what self is for module-level functions is misleading/wrong.

[Graham Dumpleton]

New submission from Graham Dumpleton:

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

----------
assignee: docs at python
components: Documentation
files: example.tar
messages: 198265
nosy: docs at python, grahamd
priority: normal
severity: normal
status: open
title: Documentation on what self is for module-level functions is misleading/wrong.
type: behavior
versions: Python 2.7
Added file: http://bugs.python.org/file31841/example.tar

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue19071>
_______________________________________