diff options
Diffstat (limited to 'python/pykde/doc/libpythonize.html')
| -rw-r--r-- | python/pykde/doc/libpythonize.html | 224 |
1 files changed, 0 insertions, 224 deletions
diff --git a/python/pykde/doc/libpythonize.html b/python/pykde/doc/libpythonize.html deleted file mode 100644 index 58a3d124..00000000 --- a/python/pykde/doc/libpythonize.html +++ /dev/null @@ -1,224 +0,0 @@ -<!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> - |