Module

The Python/C API has functions for working with module objects and importing them, as described in the following sections.

Module objects

PyModuleObject structures have the type PyModule_Type, and PyModule_Check(PyObject *o) returns 1 if the object o is a module.

PyModule_New(char *name) returns a new reference to a new module object and creates the module's namespace dictionary. The module's_name_member is set to name, and its_doc_member is set to an empty string. Before letting other parts of the program use the new module, you should at least set its_file_member.

PyModule_GetDict(PyObject *m) returns a borrowed reference to the module's dictionary (_dict_). PyModule_GetName(PyObject *m) returns a char pointer to the value of the module's_name_member, and

PyModule_GetFilename(PyObject *m) returns a char pointer to the value of its _file_member.

PyModule_AddObject(PyObject *m, char *name, PyObject *value) adds the object value to the module m. This function steals a reference to value.

PyModule_AddIntConstant(PyObject *m, char *name, int value) is a utility function that creates an integer object with the given value and adds it to the module. PyModule_AddStringConstant(PyObject *m, char *name, char *value) does the same for a string variable.

Importing modules

PyImport_ImportModule(char *name) loads the requested module and returns a new reference to it. Internally, PyImport_ImportModule calls PylmportjImportModuleEx (char*name, PyObject*globals, PyObject *locals, PyObject *fromlist), which loads a module with the given global and local dictionaries, which may be NULL. Python's_import_function calls

PylmportjImportModuleEx.

PyImport_Import(PyObject *name) also loads a module, but it uses the current import hooks to do the loading.

PylmportjReloadModule (PyObject *m) reloads the given module (just like the Python reload() function) and returns a new reference to it.

PyImport_AddModule(char *name) returns a borrowed reference to a module called name, creating an empty module object if necessary.

PyImport_GetModuleDict() returns a borrowed reference to the module dictionary (stored in sys.modules).

PyImport_ExecCodeModule(char *name, PyObject *co) returns a new reference to a module object. The module is created and imported using co, which is a code object (obtained from a call to compile or read in from a .pyc file). If the module already exists, it is reloaded using the given code object.

PyImport_GetMagicNumber() returns a C long containing the little-endian, 4-byte magic number at the start of all .pyc and .pyo files.

Before a call to PyjInitialize, you can add your module to the list of built-in modules by calling PyImport_Appendlnittab(char *name, void (*initfunc) (void)) , passing in the module name and initialization function to call. To add

New \ * The following functions were introduced in Python 2.0.

Chapter 35 shows you how to override importing behavior using import hooks.

several modules, call PyImport_ExtendInittab(struct_inittab *newtab), where newtab is an array of entries for each module, with an extra entry on the end with a NULL name to denote the end of the list. The _inittab structure has the following format:

struct _inittab { char *name;

PyImport_ImportFrozenModule(char *name) loads a frozen module (created with the Freeze utility). This function only loads the module; you still need to call

PyImport_ImportModule to import it.

Occasionally, it's necessary to pass a C object (well, a pointer) from a function through Python code and back into C again. The PyCObject structure is the Python/C API equivalent of a void pointer for just this purpose. Your code can call PyCObject_Check(PyObject *o) to determine whether an object is of this type.

To create a PyCObject, call PyCObject_FromVoidPtr (void* cobj, void (*destr)(void*)), which returns a new reference to the object. destr is a function that will be called when Python is about to destroy the object. If you don't need to do any cleanup, this argument can be NULL.

PyCObjects can also contain some extra information called a description. Call PyCObject_FromVoidPtrAndDesc (void* cobj, void*desc, void (*destr)(void*, void*)) to create an object with a description. Note that the destructor function receives both the object and its description when called.

PyCObject_GetDesc(PyObject *o) returns a pointer to the description data, and PyCObjcet_AsVoidPtr(PyObject*o) returns the original C pointer used to create the PyCObject.

0 0

Post a comment