SourceForge.net Logo
Public Types | Signals

PythonQt Class Reference

The main interface to the Python Qt binding, realized as a singleton. More...

#include <PythonQt.h>

List of all members.

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
PyObjectcallAndReturnPyObject (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 PythonQtself ()
 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 PythonQtPrivatepriv ()
 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
PyObjecthelpCalled (PythonQtClassInfo *info)
 called by internal help methods
PythonQtObjectPtr lookupObject (PyObject *module, const QString &name)

Detailed Description

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.


Member Enumeration Documentation

flags that can be passed to PythonQt::init()

Enumerator:
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.

defines the object types for introspection

Enumerator:
Class 
Function 
Variable 
Module 
Anything 
CallOverloads 

Definition at line 164 of file PythonQt.h.

                  {
    Class,
    Function,
    Variable,
    Module,
    Anything,
    CallOverloads
  };

flags that tell PythonQt which operators to expect on the registered type

Enumerator:
Type_Add 
Type_Subtract 
Type_Multiply 
Type_Divide 
Type_Mod 
Type_And 
Type_Or 
Type_Xor 
Type_LShift 
Type_RShift 
Type_InplaceAdd 
Type_InplaceSubtract 
Type_InplaceMultiply 
Type_InplaceDivide 
Type_InplaceMod 
Type_InplaceAnd 
Type_InplaceOr 
Type_InplaceXor 
Type_InplaceLShift 
Type_InplaceRShift 
Type_Invert 
Type_RichCompare 
Type_NonZero 

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,

  };


Member Function Documentation

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:

  • SomeClass* new_SomeClass(...)
  • QVariant new_SomeClass(...)
  • void delete_SomeClass(SomeClass*)
  • ... static_SomeClass_someName(...)

This will add:

  • a constructor
  • a constructor which generates a QVariant
  • a destructor (only useful for CPP objects)
  • a static decorator slot which will be available on the MetaObject (visible in PythonQt module)
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

QVariant PythonQt::evalCode ( PyObject object,
PyObject pycode 
)

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

Returns:
new reference
PythonQtObjectPtr PythonQt::lookupObject ( PyObject module,
const QString &  name 
)

returns the found object or NULL

Returns:
new reference
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]

get the singleton instance

Definition at line 159 of file PythonQt.h.

{ return _self; }

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


The documentation for this class was generated from the following file: