The main interface to the Python Qt binding, realized as a singleton. More...
#include <PythonQt.h>
Public Types | |
enum | InitFlags { RedirectStdOut = 1, IgnoreSiteModule = 2, ExternalHelp = 4, PythonAlreadyInitialized = 8 } |
flags that can be passed to PythonQt::init() More... | |
enum | TypeSlots { Type_Add = 1, Type_Subtract = 1 << 1, Type_Multiply = 1 << 2, Type_Divide = 1 << 3, Type_Mod = 1 << 4, Type_And = 1 << 5, Type_Or = 1 << 6, Type_Xor = 1 << 7, Type_LShift = 1 << 8, Type_RShift = 1 << 9, Type_InplaceAdd = 1 << 10, Type_InplaceSubtract = 1 << 11, Type_InplaceMultiply = 1 << 12, Type_InplaceDivide = 1 << 13, Type_InplaceMod = 1 << 14, Type_InplaceAnd = 1 << 15, Type_InplaceOr = 1 << 16, Type_InplaceXor = 1 << 17, Type_InplaceLShift = 1 << 18, Type_InplaceRShift = 1 << 19, Type_Invert = 1 << 29, Type_RichCompare = 1 << 30, Type_NonZero = 1 << 31 } |
flags that tell PythonQt which operators to expect on the registered type More... | |
enum | ObjectType { Class, Function, Variable, Module, Anything, CallOverloads } |
defines the object types for introspection More... | |
Signals | |
void | pythonStdOut (const QString &str) |
emitted when python outputs something to stdout (and redirection is turned on) | |
void | pythonStdErr (const QString &str) |
emitted when python outputs something to stderr (and redirection is turned on) | |
void | pythonHelpRequest (const QByteArray &cppClassName) |
emitted when help() is called on a PythonQt object and ExternalHelp is enabled | |
Public Member Functions | |
Modules | |
PythonQtObjectPtr | getMainModule () |
get the __main__ module of python | |
PythonQtObjectPtr | importModule (const QString &name) |
PythonQtObjectPtr | createModuleFromFile (const QString &name, const QString &filename) |
PythonQtObjectPtr | createModuleFromScript (const QString &name, const QString &script=QString()) |
PythonQtObjectPtr | createUniqueModule () |
Importing/Paths | |
void | overwriteSysPath (const QStringList &paths) |
overwrite the python sys path (call this directly after PythonQt::init() if you want to change the std python sys path) | |
void | addSysPath (const QString &path) |
prepend a path to sys.path to allow importing from it | |
void | setModuleImportPath (PyObject *module, const QStringList &paths) |
sets the __path__ list of a module to the given list (important for local imports) | |
Registering Classes | |
void | registerClass (const QMetaObject *metaobject, const char *package=NULL, PythonQtQObjectCreatorFunctionCB *wrapperCreator=NULL, PythonQtShellSetInstanceWrapperCB *shell=NULL) |
registers a QObject derived class to PythonQt (this is implicitly called by addObject as well) | |
void | registerCPPClass (const char *typeName, const char *parentTypeName=NULL, const char *package=NULL, PythonQtQObjectCreatorFunctionCB *wrapperCreator=NULL, PythonQtShellSetInstanceWrapperCB *shell=NULL) |
void | registerQObjectClassNames (const QStringList &names) |
bool | addParentClass (const char *typeName, const char *parentTypeName, int upcastingOffset=0) |
void | addPolymorphicHandler (const char *typeName, PythonQtPolymorphicHandlerCB *cb) |
add a handler for polymorphic downcasting | |
Script Parsing and Evaluation | |
PythonQtObjectPtr | parseFile (const QString &filename) |
parses the given file and returns the python code object, this can then be used to call evalCode() | |
QVariant | evalCode (PyObject *object, PyObject *pycode) |
QVariant | evalScript (PyObject *object, const QString &script, int start=Py_file_input) |
evaluates the given script code and returns the result value | |
void | evalFile (PyObject *object, const QString &filename) |
evaluates the given script code from file | |
Signal Handlers | |
bool | addSignalHandler (QObject *obj, const char *signal, PyObject *module, const QString &objectname) |
add a signal handler to the given signal of obj and connect it to a callable objectname in module | |
bool | removeSignalHandler (QObject *obj, const char *signal, PyObject *module, const QString &objectname) |
remove a signal handler from the given signal of obj | |
bool | addSignalHandler (QObject *obj, const char *signal, PyObject *receiver) |
add a signal handler to the given signal of obj and connect it to a callable receiver | |
bool | removeSignalHandler (QObject *obj, const char *signal, PyObject *receiver) |
remove a signal handler from the given signal of obj | |
Variable access | |
void | addObject (PyObject *object, const QString &name, QObject *qObject) |
add the given qObject to the python object as a variable with name (it can be removed via clearVariable) | |
void | addVariable (PyObject *object, const QString &name, const QVariant &v) |
add the given variable to the object | |
void | removeVariable (PyObject *module, const QString &name) |
remove the given variable | |
QVariant | getVariable (PyObject *object, const QString &name) |
get the variable with the name of the object , returns an invalid QVariant on error | |
QStringList | introspection (PyObject *object, const QString &objectname, ObjectType type) |
read vars etc. in scope of an object , optional looking inside of an object objectname | |
PythonQtObjectPtr | lookupCallable (PyObject *object, const QString &name) |
Calling Python Objects | |
QVariant | call (PyObject *object, const QString &callable, const QVariantList &args=QVariantList()) |
call the given python callable in the scope of object, returns the result converted to a QVariant | |
QVariant | call (PyObject *callable, const QVariantList &args=QVariantList()) |
call the given python object, returns the result converted to a QVariant | |
PyObject * | callAndReturnPyObject (PyObject *callable, const QVariantList &args=QVariantList()) |
call the given python object, returns the result as new PyObject | |
Decorations, Constructors, Wrappers... | |
void | addInstanceDecorators (QObject *o) |
void | addClassDecorators (QObject *o) |
void | addDecorators (QObject *o) |
this will add the object both as class and instance decorator (ownership is passed to PythonQt) | |
void | addWrapperFactory (PythonQtCppWrapperFactory *factory) |
add the given factory to PythonQt (ownership stays with caller) | |
Static Public Member Functions | |
Singleton Initialization | |
static void | init (int flags=IgnoreSiteModule|RedirectStdOut, const QByteArray &pythonQtModuleName=QByteArray()) |
static void | cleanup () |
cleanup of the singleton | |
static PythonQt * | self () |
get the singleton instance | |
Custom Importer | |
| |
static PythonQtImportFileInterface * | importInterface () |
get access to the file importer (if set) | |
void | setImporter (PythonQtImportFileInterface *importInterface) |
void | installDefaultImporter () |
void | setImporterIgnorePaths (const QStringList &paths) |
set paths that the importer should ignore | |
const QStringList & | getImporterIgnorePaths () |
get paths that the importer should ignore | |
Other Stuff | |
| |
static PythonQtPrivate * | priv () |
get access to internal data (should not be used on the public API, but is used by some C functions) | |
static void | qObjectNoLongerWrappedCB (QObject *o) |
call the callback if it is set | |
bool | handleError () |
void | setQObjectWrappedCallback (PythonQtQObjectWrappedCB *cb) |
set a callback that is called when a QObject with parent == NULL is wrapped by pythonqt | |
void | setQObjectNoLongerWrappedCallback (PythonQtQObjectNoLongerWrappedCB *cb) |
set a callback that is called when a QObject with parent == NULL is no longer wrapped by pythonqt | |
PyObject * | helpCalled (PythonQtClassInfo *info) |
called by internal help methods | |
PythonQtObjectPtr | lookupObject (PyObject *module, const QString &name) |
The main interface to the Python Qt binding, realized as a singleton.
Use PythonQt::init() to initialize the singleton and PythonQt::self() to access it. While there can be only one PythonQt instance, you can have any number of Python context to do scripting in. One possibility is to use createModuleFromFile(), createModuleFromScript() or createUniqueModule() to get a context that is separated from the other contexts. Alternatively you can use Python dicts as contexts for script evaluation, but you will need to populate the dict with the __builtins__ instance to have all Pythons available when running code in the scope of a dict.
Definition at line 96 of file PythonQt.h.
enum PythonQt::InitFlags |
flags that can be passed to PythonQt::init()
RedirectStdOut |
< sets if the std out/err is redirected to pythonStdOut() and pythonStdErr() signals |
IgnoreSiteModule |
< sets if Python should ignore the site module |
ExternalHelp |
< sets if help() calls on PythonQt modules are forwarded to the pythonHelpRequest() signal |
PythonAlreadyInitialized |
< sets that PythonQt should not can PyInitialize, since it is already done |
Definition at line 103 of file PythonQt.h.
{ RedirectStdOut = 1, IgnoreSiteModule = 2, ExternalHelp = 4, PythonAlreadyInitialized = 8 };
enum PythonQt::ObjectType |
defines the object types for introspection
Definition at line 164 of file PythonQt.h.
{ Class, Function, Variable, Module, Anything, CallOverloads };
enum PythonQt::TypeSlots |
flags that tell PythonQt which operators to expect on the registered type
Definition at line 111 of file PythonQt.h.
{ Type_Add = 1, Type_Subtract = 1 << 1, Type_Multiply = 1 << 2, Type_Divide = 1 << 3, Type_Mod = 1 << 4, Type_And = 1 << 5, Type_Or = 1 << 6, Type_Xor = 1 << 7, Type_LShift = 1 << 8, Type_RShift = 1 << 9, Type_InplaceAdd = 1 << 10, Type_InplaceSubtract = 1 << 11, Type_InplaceMultiply = 1 << 12, Type_InplaceDivide = 1 << 13, Type_InplaceMod = 1 << 14, Type_InplaceAnd = 1 << 15, Type_InplaceOr = 1 << 16, Type_InplaceXor = 1 << 17, Type_InplaceLShift = 1 << 18, Type_InplaceRShift = 1 << 19, // Not yet needed/nicely mappable/generated... //Type_Positive = 1 << 29, //Type_Negative = 1 << 29, //Type_Abs = 1 << 29, //Type_Hash = 1 << 29, Type_Invert = 1 << 29, Type_RichCompare = 1 << 30, Type_NonZero = 1 << 31, };
void PythonQt::addClassDecorators | ( | QObject * | o | ) |
add an object whose slots will be used as decorator slots for class objects (ownership is passed to PythonQt)
The slots need to follow the following convention:
This will add:
void PythonQt::addDecorators | ( | QObject * | o | ) |
this will add the object both as class and instance decorator (ownership is passed to PythonQt)
void PythonQt::addInstanceDecorators | ( | QObject * | o | ) |
add an object whose slots will be used as decorator slots for other QObjects or CPP classes. The slots need to follow the convention that the first argument is a pointer to the wrapped object. (ownership is passed to PythonQt)
Example:
A slot with the signature
bool doSomething(QWidget* w, int a)
will extend QWidget instances (and derived classes) with a "bool doSomething(int a)" slot that will be called with the concrete instance as first argument. So in Python you can now e.g. call
someWidget.doSomething(12)
without QWidget really having this method. This allows to easily make normal methods of Qt classes callable by forwarding them with such decorator slots or to make CPP classes (which are not derived from QObject) callable from Python.
void PythonQt::addObject | ( | PyObject * | object, | |
const QString & | name, | |||
QObject * | qObject | |||
) |
add the given qObject
to the python object
as a variable with name
(it can be removed via clearVariable)
bool PythonQt::addParentClass | ( | const char * | typeName, | |
const char * | parentTypeName, | |||
int | upcastingOffset = 0 | |||
) |
add a parent class relation to the given
typeName, the upcastingOffset is needed for multiple inheritance and can be calculated using PythonQtUpcastingOffset<type,parentType>(), which also verifies that type is really derived from parentType. Returns false if the typeName was not yet registered.
void PythonQt::addPolymorphicHandler | ( | const char * | typeName, | |
PythonQtPolymorphicHandlerCB * | cb | |||
) |
add a handler for polymorphic downcasting
bool PythonQt::addSignalHandler | ( | QObject * | obj, | |
const char * | signal, | |||
PyObject * | module, | |||
const QString & | objectname | |||
) |
add a signal handler to the given signal
of obj
and connect it to a callable objectname
in module
bool PythonQt::addSignalHandler | ( | QObject * | obj, | |
const char * | signal, | |||
PyObject * | receiver | |||
) |
add a signal handler to the given signal
of obj
and connect it to a callable receiver
void PythonQt::addSysPath | ( | const QString & | path | ) |
prepend a path to sys.path to allow importing from it
void PythonQt::addVariable | ( | PyObject * | object, | |
const QString & | name, | |||
const QVariant & | v | |||
) |
add the given variable to the object
void PythonQt::addWrapperFactory | ( | PythonQtCppWrapperFactory * | factory | ) |
add the given factory to PythonQt (ownership stays with caller)
QVariant PythonQt::call | ( | PyObject * | callable, | |
const QVariantList & | args = QVariantList() | |||
) |
call the given python object, returns the result converted to a QVariant
QVariant PythonQt::call | ( | PyObject * | object, | |
const QString & | callable, | |||
const QVariantList & | args = QVariantList() | |||
) |
call the given python callable
in the scope of object, returns the result converted to a QVariant
PyObject* PythonQt::callAndReturnPyObject | ( | PyObject * | callable, | |
const QVariantList & | args = QVariantList() | |||
) |
call the given python object, returns the result as new PyObject
static void PythonQt::cleanup | ( | ) | [static] |
cleanup of the singleton
PythonQtObjectPtr PythonQt::createModuleFromFile | ( | const QString & | name, | |
const QString & | filename | |||
) |
creates the new module name
and evaluates the given file in the context of that module If the script
is empty, the module contains no initial code. You can use evalScript/evalCode to add code to a module later on. The user needs to make sure that the name
is unique in the python module dictionary.
PythonQtObjectPtr PythonQt::createModuleFromScript | ( | const QString & | name, | |
const QString & | script = QString() | |||
) |
creates the new module name
and evaluates the given script in the context of that module. If the script
is empty, the module contains no initial code. You can use evalScript/evalCode to add code to a module later on. The user needs to make sure that the name
is unique in the python module dictionary.
PythonQtObjectPtr PythonQt::createUniqueModule | ( | ) |
create a uniquely named module, you can use evalFile or evalScript to populate the module with script code
evaluates the given code and returns the result value (use Py_Compile etc. to create pycode from string) If pycode is NULL, a python error is printed.
void PythonQt::evalFile | ( | PyObject * | object, | |
const QString & | filename | |||
) |
evaluates the given script code from file
QVariant PythonQt::evalScript | ( | PyObject * | object, | |
const QString & | script, | |||
int | start = Py_file_input | |||
) |
evaluates the given script code and returns the result value
const QStringList& PythonQt::getImporterIgnorePaths | ( | ) |
get paths that the importer should ignore
PythonQtObjectPtr PythonQt::getMainModule | ( | ) |
get the __main__ module of python
QVariant PythonQt::getVariable | ( | PyObject * | object, | |
const QString & | name | |||
) |
get the variable with the name
of the object
, returns an invalid QVariant on error
bool PythonQt::handleError | ( | ) |
handle a python error, call this when a python function fails. If no error occurred, it returns false. The error is currently just output to the python stderr, future version might implement better trace printing
PyObject* PythonQt::helpCalled | ( | PythonQtClassInfo * | info | ) |
called by internal help methods
static PythonQtImportFileInterface* PythonQt::importInterface | ( | ) | [static] |
get access to the file importer (if set)
PythonQtObjectPtr PythonQt::importModule | ( | const QString & | name | ) |
import the given module and return a reference to it (useful to import e.g. "sys" and call something on it) If a module is already imported, this returns the already imported module.
static void PythonQt::init | ( | int | flags = IgnoreSiteModule|RedirectStdOut , |
|
const QByteArray & | pythonQtModuleName = QByteArray() | |||
) | [static] |
initialize the python qt binding (flags are a or combination of PythonQt::InitFlags), if pythonQtModuleName
is given it defines the name of the python module that PythonQt will add, otherwise "PythonQt" is used. This can be used to e.g. pass in PySide or PyQt4 to make it more compatible.
void PythonQt::installDefaultImporter | ( | ) | [inline] |
this installs the default QFile importer (which effectively does a setImporter(NULL)) (without calling setImporter or installDefaultImporter at least once, the default python import mechanism is in place) the default importer allows to import files from anywhere QFile can read from, including the Qt resource system using ":". Keep in mind that you need to extend "sys.path" with ":" to be able to import from the Qt resources.
Definition at line 406 of file PythonQt.h.
{ setImporter(NULL); }
QStringList PythonQt::introspection | ( | PyObject * | object, | |
const QString & | objectname, | |||
ObjectType | type | |||
) |
read vars etc. in scope of an object
, optional looking inside of an object objectname
PythonQtObjectPtr PythonQt::lookupCallable | ( | PyObject * | object, | |
const QString & | name | |||
) |
returns the found callable object or NULL
PythonQtObjectPtr PythonQt::lookupObject | ( | PyObject * | module, | |
const QString & | name | |||
) |
returns the found object or NULL
void PythonQt::overwriteSysPath | ( | const QStringList & | paths | ) |
overwrite the python sys path (call this directly after PythonQt::init() if you want to change the std python sys path)
PythonQtObjectPtr PythonQt::parseFile | ( | const QString & | filename | ) |
parses the given file and returns the python code object, this can then be used to call evalCode()
static PythonQtPrivate* PythonQt::priv | ( | ) | [inline, static] |
get access to internal data (should not be used on the public API, but is used by some C functions)
Definition at line 424 of file PythonQt.h.
{ return _self->_p; }
void PythonQt::pythonHelpRequest | ( | const QByteArray & | cppClassName | ) | [signal] |
emitted when help() is called on a PythonQt object and ExternalHelp
is enabled
void PythonQt::pythonStdErr | ( | const QString & | str | ) | [signal] |
emitted when python outputs something to stderr (and redirection is turned on)
void PythonQt::pythonStdOut | ( | const QString & | str | ) | [signal] |
emitted when python outputs something to stdout (and redirection is turned on)
static void PythonQt::qObjectNoLongerWrappedCB | ( | QObject * | o | ) | [static] |
call the callback if it is set
void PythonQt::registerClass | ( | const QMetaObject * | metaobject, | |
const char * | package = NULL , |
|||
PythonQtQObjectCreatorFunctionCB * | wrapperCreator = NULL , |
|||
PythonQtShellSetInstanceWrapperCB * | shell = NULL | |||
) |
registers a QObject derived class to PythonQt (this is implicitly called by addObject as well)
void PythonQt::registerCPPClass | ( | const char * | typeName, | |
const char * | parentTypeName = NULL , |
|||
const char * | package = NULL , |
|||
PythonQtQObjectCreatorFunctionCB * | wrapperCreator = NULL , |
|||
PythonQtShellSetInstanceWrapperCB * | shell = NULL | |||
) |
add a wrapper object for the given QMetaType typeName, also does an addClassDecorators() to add constructors for variants (ownership of wrapper is passed to PythonQt)
Make sure that you have done a qRegisterMetaType first, if typeName is a user type!
This will add a wrapper object that is used to make calls to the given classname typeName
. All slots that take a pointer to typeName as the first argument will be callable from Python on a variant object that contains such a type.
void PythonQt::registerQObjectClassNames | ( | const QStringList & | names | ) |
as an alternative to registerClass, you can tell PythonQt the names of QObject derived classes and it will register the classes when it first sees a pointer to such a derived class
bool PythonQt::removeSignalHandler | ( | QObject * | obj, | |
const char * | signal, | |||
PyObject * | module, | |||
const QString & | objectname | |||
) |
remove a signal handler from the given signal
of obj
bool PythonQt::removeSignalHandler | ( | QObject * | obj, | |
const char * | signal, | |||
PyObject * | receiver | |||
) |
remove a signal handler from the given signal
of obj
void PythonQt::removeVariable | ( | PyObject * | module, | |
const QString & | name | |||
) |
remove the given variable
static PythonQt* PythonQt::self | ( | ) | [inline, static] |
void PythonQt::setImporter | ( | PythonQtImportFileInterface * | importInterface | ) |
replace the internal import implementation and use the supplied interface to load files (both py and pyc files) (this method should be called directly after initialization of init() and before calling overwriteSysPath(). On the first call to this method, it will install a generic PythonQt importer in Pythons "path_hooks". This is not reversible, so even setting setImporter(NULL) afterwards will keep the custom PythonQt importer with a QFile default import interface. Subsequent python import calls will make use of the passed importInterface which forwards all import calls to the given importInterface
. Passing NULL will install a default QFile importer. (importInterface
ownership stays with caller)
void PythonQt::setImporterIgnorePaths | ( | const QStringList & | paths | ) |
set paths that the importer should ignore
void PythonQt::setModuleImportPath | ( | PyObject * | module, | |
const QStringList & | paths | |||
) |
sets the __path__ list of a module to the given list (important for local imports)
void PythonQt::setQObjectNoLongerWrappedCallback | ( | PythonQtQObjectNoLongerWrappedCB * | cb | ) |
set a callback that is called when a QObject with parent == NULL is no longer wrapped by pythonqt
void PythonQt::setQObjectWrappedCallback | ( | PythonQtQObjectWrappedCB * | cb | ) |
set a callback that is called when a QObject with parent == NULL is wrapped by pythonqt