You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
225 lines
8.3 KiB
225 lines
8.3 KiB
14 years ago
|
<!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>
|
||
|
|
|