Index: Doc/c-api/module.rst =================================================================== --- Doc/c-api/module.rst (Revision 68135) +++ Doc/c-api/module.rst (Arbeitskopie) @@ -73,6 +73,106 @@ raise :exc:`SystemError` and return *NULL*. +.. cfunction:: void* PyModule_GetState(PyObject *module) + + Return the "state" of the module, that is, a pointer to the block of memory + allocated at module creation time, or *NULL*. See + :cmember:`PyModuleDef.m_size`. + + +.. cfunction:: PyModuleDef* PyModule_GetDef(PyObject *module) + + Return a pointer to the :ctype:`PyModuleDef` struct from which the module was + created, or *NULL* if the module wasn't created with + :cfunc:`PyModule_Create`. + + +Initializing C modules +^^^^^^^^^^^^^^^^^^^^^^ + +These functions are usually used in the module initialization function. + +.. cfunction:: PyObject* PyModule_Create(PyModuleDef *module) + + Create a new module object, given the definition in *module*. This behaves + like :cfunc:`PyModule_Create2` with *module_api_version* set to + :const:`PYTHON_API_VERSION`. + + +.. cfunction:: PyObject* PyModule_Create2(PyModuleDef *module, int module_api_version) + + Create a new module object, given the definition in *module*, assuming the + API version *module_api_version*. If that version does not match the version + of the running interpreter, a :exc:`RuntimeWarning` is emitted. + + .. note:: + + Most uses of this function should be using :cfunc:`PyModule_Create` + instead; only use this if you are sure you need it. + + +.. ctype:: PyModuleDef + + This struct holds all information that is needed to create a module object. + There is usually only one static variable of that type for each module, which + is statically initialized and then passed to :cfunc:`PyModule_Create` in the + module initialization function. + + .. cmember:: PyModuleDef_Base m_base + + Always initialize this member to :const:`PyModuleDef_HEAD_INIT`. + + .. cmember:: char* m_name + + Name for the new module. + + .. cmember:: char* m_doc + + Docstring for the module; usually a docstring variable created with + :cfunc:`PyDoc_STRVAR` is used. + + .. cmember:: Py_ssize_t m_size + + If the module object needs additional memory, this should be set to the + number of bytes to allocate; a pointer to the block of memory can be + retrieved with :cfunc:`PyModule_GetState`. If no memory is needed, set + this to ``-1``. + + This memory should be used, rather than static globals, to hold per-module + state, since it is then safe for use in multiple sub-interpreters. + + .. note:: + + While the additional memory is allocated automatically, it is not freed + in a similar fashion; therefore you must use an appropriate + :cmember:`m_free` function if you want to free the memory as soon as + the module object is deallocated. + + .. cmember:: PyMethodDef* m_methods + + A pointer to a table of module-level functions, described by + :ctype:`PyMethodDef` values. Can be *NULL* if no functions are present. + + .. cmember:: inquiry m_reload + + Currently unused, should be *NULL*. + + .. cmember:: traverseproc m_traverse + + A traversal function to call during GC traversal of the module object, or + *NULL* if not needed. + + .. cmember:: inquiry m_clear + + A clear function to call during GC clearing of the module object, or + *NULL* if not needed. + + .. cmember:: freefunc m_free + + A function to call during deallocation of the module object, or *NULL* if + not needed. + + .. cfunction:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value) Add an object to *module* as *name*. This is a convenience function which can @@ -105,4 +205,3 @@ .. cfunction:: int PyModule_AddStringMacro(PyObject *module, macro) Add a string constant to *module*. - Index: Doc/c-api/allocation.rst =================================================================== --- Doc/c-api/allocation.rst (Revision 68135) +++ Doc/c-api/allocation.rst (Arbeitskopie) @@ -54,40 +54,15 @@ accessed after this call as the memory is no longer a valid Python object. -.. cfunction:: PyObject* Py_InitModule(char *name, PyMethodDef *methods) - - Create a new module object based on a name and table of functions, returning - the new module object; the *methods* argument can be *NULL* if no methods are - to be defined for the module. - - -.. cfunction:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc) - - Create a new module object based on a name and table of functions, returning - the new module object. The *methods* argument can be *NULL* if no methods - are to be defined for the module. If *doc* is non-*NULL*, it will be used to - define the docstring for the module. - - -.. cfunction:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver) - - Create a new module object based on a name and table of functions, returning - the new module object. The *methods* argument can be *NULL* if no methods - are to be defined for the module. If *doc* is non-*NULL*, it will be used to - define the docstring for the module. If *self* is non-*NULL*, it will passed - to the functions of the module as their (otherwise *NULL*) first parameter. - (This was added as an experimental feature, and there are no known uses in - the current version of Python.) For *apiver*, the only value which should be - passed is defined by the constant :const:`PYTHON_API_VERSION`. - - .. note:: - - Most uses of this function should probably be using the :cfunc:`Py_InitModule3` - instead; only use this if you are sure you need it. - - .. cvar:: PyObject _Py_NoneStruct Object which is visible in Python as ``None``. This should only be accessed using the :cmacro:`Py_None` macro, which evaluates to a pointer to this object. + + +.. seealso:: + + :cfunc:`PyModule_Create` + To allocate and create extension modules. +