diff options
Diffstat (limited to 'python/pykde/doc/libpythonize.html')
| -rw-r--r-- | python/pykde/doc/libpythonize.html | 224 |
1 files changed, 224 insertions, 0 deletions
diff --git a/python/pykde/doc/libpythonize.html b/python/pykde/doc/libpythonize.html new file mode 100644 index 00000000..58a3d124 --- /dev/null +++ b/python/pykde/doc/libpythonize.html @@ -0,0 +1,224 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> +<title>Pythonize class and libpythonize</title> +</head> +<body> +<div class="NAVHEADER"> +<table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0"> +<TR> +<TH COLSPAN="3" ALIGN="center">Python Bindings for KDE (PyKDE-3.16.0)</TH> +</TR> +<tr> +<td width="33%" align="left" valign="bottom"> +<a href="panapp5.html" accesskey="P" >Prev</a> +</td> +<td width="34%" align="center" valign="bottom"></td> +<td width="33%" align="right" valign="bottom"></td> +</tr> +</table> +</div> +<hr align="LEFT" width="100%"> +<div align="center"><h1>Pythonize Class and libpythonize</h1></div> +<p> +libPythonize and the Pythonize class simplify embedding, loading and communicating with the Python +interpreter. Pythonize is a class with methods for handling the interpreter and is included in libpythonize. +Also in libpythonize is a C wrapper for the C++ Pythonize class. There is also a standalone C library +libpythonizec, written completely in C. All 3 versions (C++, C and C wrapper) use the same methods/functions +and the same args - the only major difference is in initialization and finalization. +</p> +<p> +The method descriptions here apply to both C and C++ versions unless noted. +</p> +<p> +Although libpythonize is used with (and installed with) PyKDE, it has no dependencies itself on +PyKDE/KDE, PyQt/Qt or sip. It does require qmake from TrollTech (part of Qt) to build. +</p> + +<h2>Initialization and Finalization</h2> +In C++, the interpreter is loaded and initialized using the Pythonize () constructor, which takes +no arguments. In C, the initialize() function call accomplishes the same thing. + +The interpreter is finalized in C++ using the destructor ~Pythonize (). In C, the finalize() function +accomplishes the same thing. + +<h2>Threading and Locking</h2> +<p> +Pythonize obtains the Python global interpreter lock when it initializes Python. It is currently the +programmer's responsibility to release the lock when C++ accesses to the interpreter are complete. If +the lock is not released, access will be denied to Python code relying on the interpreter (for example +bindings like PyQt or PyKDE). +</p> +<p> +If a second instance of Pythonize is created (within the same parent process), that instance will acquire +the lock automatically. In order to allow a second (and third or more) instance of Pythonize to be +created and obtain the lock, it's necessary to have a related thread state (PyThreadState). This thread +state is created by a call to PyThreadState_Get when the first instance of Pythonize is created. The +thread state is stored in a global variable (declared in the cpp file) that is used by all subsequent +instances of Pythonize. This means that applications using libpythonize are mormally single-threaded, +at least in relation to the libpythonize interpreter instance. This is important for utilization with +sip-based bindings like PyKDE and PyQt. +</p> +<p> +The global thread state is accessible via the getThreadState/setThreadState methods. +</p> +<h2>Methods/Functions</h2> +<p> +Methods are either called directly in C or as class members in C++. In C, int variables/values are +used instead of bool. +</p> +<table border="0" bgcolor="#E0E0E0" width="100%"> +<tr> +<td> +<pre CLASS="PROGRAMLISTING"> +C++: + Pythonize *pyize = Pythonize (); + ... + bool result = pyize->appendToSysPath ("/usr/local/foo"); + +C: + initialize (); + ... + int result = appendToSysPath ("/usr/local/foo"); +</pre> +</td> +</tr> +</table> +<hr> +<h3>Pythonize () [C++] or initialize () [C]</h3> +<p> +Constructor/initializer - loads and initializaes the interpreter and acquires the global interpreter lock. +Sets the value of pythonInit to <b>true</b> on success or <b>false</b> if construction/initialization fails +Initializes the global thread state (first instance) or restores the global thread state (second and later +instances). It is the programmer's resposibility to release the global interpreter lock to enable other +code to access the interpreter. The lock and thread state are automatically acquired when any Pythonize +instance is created.. +</p> +<hr> +<h3>bool getPythonInit ()</h3> +<p> +Returns the result of initializing/constructing the interpreter object. If the +return value is <strong>true</strong>, the interpreter should be usable. +If it returns <strong>false</strong>, an error occurred and the interpreter +will not be useful. Most methods/functions check the value of pythonInit +and won't run if it's <strong>false</strong> +</p> +<hr> +<h3>~Pythonize () [C++] or finalize () [C]</h3> +<p> +Destructor/finalizer - shuts down the interpreter and destroys the class Sets pythonInit to <b>false</b>. +</p> +<hr> +<h3>bool appendToSysPath (const char* newPath);</h3> +<p> +Appends newPath to sys.path +</p> +<hr> +<h3>PyObject *importModule (char *moduleName);</h3> +<p> +Imports a module into the interpreter. Same as "import <moduleName>" in Python. moduleName +must exist somewhere on sys.path. Returns a reference to the module imported. Returns <b>NULL</b> on failure. +</p> +<hr> +<h3>PyObject *getNewObjectRef (PyObject *module, char *object)</h3> +<p> +Returns a reference to an object in an already loaded module (use importModule to load +the module or get a reference to it) Returns <b>NULL</b> on failure. +</p> +<hr> +<h3>PyObject *getSysModule ()</h3> +<p> +Returns a reference to the Python sys module. Returns <b>NULL</b> on failure. +</p> +<hr> +<h3>PyObject *getMainModule ()</h3> +<p> +Returns a reference to the Python main module. Returns <b>NULL</b> on failure. +</p> +<hr> +<h3>[internal] void *setMainModule ()</h3> +<p> +Sets internal value of main module +</p> +<hr> +<h3>void decref (PyObject *object)</h3> +<p> +Uses Py_XDECREF to decrement the reference count of an object +</p> +<hr> +<h3>bool runScript (char *scriptPath);</h3> +<p> +Runs an arbitrary script in the interpreter and returns Python's result. +</p> +<hr> +<h3>bool runString (char *str);</h3> +<p> +Runs an arbitrary string in the interpreter (indentation required for mulit-line +strings) and returns Python's result. +</p> +<hr> +<h3>PyObject *runFunction (PyObject *object, PyObject *args);</h3> +<p> +If <em>object</em> is callable, runs <em>object</em> with <em>args</em> and +returns the results of the function call as a PyObject. Returns <b>NULL</b> on failure. +</p> +<hr> +<h3>void releaseLock ()</h3> +<p> +Releases the global interpreter lock using PyEval_SaveThread. Saves the global thread state. +</p> +<hr> +<h3>void acquireLock ()</h3> +<p> +Acquires the global interpreter lock using PyEval_RestoreThread. Restores the global thread state. +</p> +<hr> +<h3>PyThreadState *getThreadState ()</h3> +<p> +Retrieves the current value of the global thread state. Does not affect the global interpreter lock. +</p> +<hr> +<h3>PyThreadState *setThreadState (PyThreadState *tstate)</h3> +<p> +Sets the global thread state to <i>tstate</i> and returns the previous global thread state. Does +not affect the global interpreter lock. +</p> +<hr> +<h2>Using libpythonize in an application</h2> +<p> +Include the pythonize.h header file (requires Python.h) and link to libpythonize.so - that's pretty much it. There are unit tests +in both C and C++ in the pythonize/tests/ subdirectory. An example of libpythonize usage is in pykpanelapplet.cpp in the +PyKDE distribution (pykpanelapplet/ directory). +</p> +<h2>Obtaining and building libpythonize</h2> +<p> +At present only the C++/C wrapper versions are available, and they're distributed with PyKDE. +</p> +<p> +The build process for libpythonize uses TrollTech's qmake (available as part of Qt), but is simple enough +to be included in most make files. See the pythonize.pro file for more information - most of the additional +libs required are required by libpython, and may vary by platform. +</p> +<p> +You can contact me at this address: <a href="mailto:jbublitz@nwinternet.com">Jim Bublitz <jbublitz@nwinternet.com></a> +</p> +<table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr> +<td width="33%" align="left" valign="top"> +<a href="panapp5.html" accesskey="P" >Prev</a> +</td> +<td width="34%" align="center" valign="top"> +<a href="index.html" accesskey="H">Home</a> +</td> +<td width="33%" align="right" valign="top"></td> +</tr> +<tr> +<td width="33%" align="left" valign="top">Applet Installer</td> +<td width="34%" align="center" valign="top"> </td> +<td width="33%" align="right" valign="top"></td> +</tr> +</table> +</div> +</body> +</html> + |