Building a Python 3.0 Extension the missing PyModule^?_* functions

These functions (PyModule^?_*) are not included in the Python 3.0 documentation but their use can be derived from Python's source code. See http://bugs.python.org/issue4614 which indicates this has been fixed and will be included in future releases.

PyObject^?* PyModule^?_Create(struct PyModuleDef^?*);

Allocates and returns a Python module object for the supplied PyModuleDef^? struct: static struct PyModuleDef^? example_Module = { PyModuleDef^?_HEAD_INIT, "example", /*m_name*/ "Example's PyDoc^?", /*m_doc*/ -1, /*m_size*/ example_Methods, /*m_methods*/ NULL, /*m_reload*/ NULL, /*m_traverse*/ NULL, /*m_clear*/ NULL /*m_free*/ };

NULL will be returned when an exception was raised (ie, out of memory).

int PyModule^?_AddObject(PyObject^?*, const char*, PyObject^?*);

First argument is the module object (from PyModule^?_Create), Second argument is the name of the new object in the module's namespace, Third argument is a pointer to a PyTypeObject^? (cast as a PyObject^?*) of the new object. Returns 0 on success, -1 on failure (result of initfunc).

int PyModule^?_AddIntConstant(PyObject^?*, const char*, long);

As PyModule^?_AddObject but the 3rd argument is the value of a new int object.

int PyModule^?_AddStringConstant(PyObject^?*, const char*, const char*);

As PyModule^?_AddObject but the 3rd argument is the value of a new str object. Building a Python 3.0 Extension bookmarks you will need

object members http://docs.python.org/3.0/c-api/structures.html#PyMemberDef Link object struct members directly to object attributes.

argument and keyword parsing http://docs.python.org/3.0/c-api/arg.html These are extremely convenient functions which parse arguments and/or keywords, test their type and value limits, and convert them into C types (char*, short, long, etc).

standard exceptions http://docs.python.org/3.0/c-api/exceptions.html#standard-exceptions Reference this table whenever you need to raise an builtin exception

glib reference manual http://library.gnome.org/devel/glib/unstable/ Not Python-specific, Glib is an invaluable cross-platform “swiss army knife” library you'll find yourself using in every C-based project. Especially useful for threaded extensions!

handy macros you'll use everywhere

Returning None This replaces “Py_INCREF(Py_None); return Py_None;” everywhere you need to return None. Py_RETURN_NONE

Returning True/False Same as above but for Py_True and Py_False Py_RETURN_TRUE Py_RETURN_FALSE

Returning Special Floats Same as above but for Py_NAN and Py_HUGE_VAL Py_RETURN_NAN Py_RETURN_INF(sign)

Release and Reacquire the GIL (Global Interpreter Lock) Working with the GIL can be a pain, but this macro pair makes it a little simpler: Py_BEGIN_ALLOW_THREADS (nogil code here) Py_END_ALLOW_THREADS

-- TedRoche - 26 Jan 2009