SourceForge.net Logo
PythonQt
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  ProfilingCallbackState { Enter = 1, Leave = 2 }
 enum for profiling callback More...
enum  ObjectType {
  Class, Function, Variable, Module,
  Anything, CallOverloads
}
 defines the object types for introspection More...
typedef void ProfilingCB (ProfilingCallbackState state, const char *className, const char *methodName)

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

Standard input handling
void setRedirectStdInCallback (PythonQtInputChangedCB *callback, void *callbackData=0)
void setRedirectStdInCallbackEnabled (bool enabled)
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
QStringList introspectObject (PyObject *object, ObjectType type)
 read vars etc. in scope of the given object
QStringList introspectType (const QString &typeName, ObjectType type)
PythonQtObjectPtr lookupCallable (PyObject *object, const QString &name)
QString getReturnTypeOfWrappedMethod (PyObject *module, const QString &objectname)
 returns the return type of the method of a wrapped c++ object referenced by objectname
QString getReturnTypeOfWrappedMethod (const QString &typeName, const QString &methodName)
 returns the return type of the method methodName of a wrapped c++ type referenced by typeName
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)
void addWrapperFactory (PythonQtForeignWrapperFactory *factory)
 add the given factory to PythonQt (ownership stays with caller)
void removeWrapperFactory (PythonQtCppWrapperFactory *factory)
 remove the wrapper factory
void removeWrapperFactory (PythonQtForeignWrapperFactory *factory)
 remove the wrapper factory

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 clearNotFoundCachedMembers ()
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)
void setProfilingCallback (ProfilingCB *cb)
 sets a callback that is called before and after function calls for profiling

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 101 of file PythonQt.h.


Member Typedef Documentation

typedef void PythonQt::ProfilingCB(ProfilingCallbackState state, const char *className, const char *methodName)

callback for profiling. className and methodName are only passed when state == Enter, otherwise they are NULL.

Definition at line 159 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 108 of file PythonQt.h.

defines the object types for introspection

Enumerator:
Class 
Function 
Variable 
Module 
Anything 
CallOverloads 

Definition at line 179 of file PythonQt.h.

enum for profiling callback

Enumerator:
Enter 
Leave 

Definition at line 152 of file PythonQt.h.

                              {
    Enter = 1,
    Leave = 2
  };

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 116 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)

void PythonQt::addWrapperFactory ( PythonQtForeignWrapperFactory factory)

add the given factory to PythonQt (ownership stays with caller)

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

QVariant PythonQt::call ( PyObject callable,
const QVariantList &  args = QVariantList() 
)

call the given python 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

void PythonQt::clearNotFoundCachedMembers ( )

clear all NotFound entries on all class infos, to ensure that newly loaded wrappers can add methods even when the object was wrapped by PythonQt before the wrapper was loaded

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

QString PythonQt::getReturnTypeOfWrappedMethod ( PyObject module,
const QString &  objectname 
)

returns the return type of the method of a wrapped c++ object referenced by objectname

QString PythonQt::getReturnTypeOfWrappedMethod ( const QString &  typeName,
const QString &  methodName 
)

returns the return type of the method methodName of a wrapped c++ type referenced by typeName

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 456 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

QStringList PythonQt::introspectObject ( PyObject object,
ObjectType  type 
)

read vars etc. in scope of the given object

QStringList PythonQt::introspectType ( const QString &  typeName,
ObjectType  type 
)

read vars etc. in scope of the type object called typename. First the typename of the form module.type is split into module and type. Then the module is looked up in sys.modules. If the module or type is not found there, then the type is looked up in the __builtin__ module.

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 474 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

void PythonQt::removeWrapperFactory ( PythonQtCppWrapperFactory factory)

remove the wrapper factory

void PythonQt::removeWrapperFactory ( PythonQtForeignWrapperFactory factory)

remove the wrapper factory

static PythonQt* PythonQt::self ( ) [static]

get the singleton instance

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::setProfilingCallback ( ProfilingCB cb)

sets a callback that is called before and after function calls for profiling

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

void PythonQt::setRedirectStdInCallback ( PythonQtInputChangedCB callback,
void *  callbackData = 0 
)

Overwrite default handling of stdin using a custom callback. It internally backup the original 'sys.stdin' into 'sys.pythonqt_original_stdin'

void PythonQt::setRedirectStdInCallbackEnabled ( bool  enabled)

Enable or disable stdin custom callback. It resets 'sys.stdin' using either 'sys.pythonqt_stdin' or 'sys.pythonqt_original_stdin'


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