PyKrita::Python Class Reference

#include <utilities.h>

Public Member Functions
PyObject *	functionCall (const char *functionName, const char *moduleName, PyObject *arguments)
bool	functionCall (const char *functionName, const char *moduleName=PYKRITA_ENGINE)
PyObject *	itemString (const char *item, const char *moduleName=PYKRITA_ENGINE)
PyObject *	itemString (const char *item, PyObject *dict)
bool	itemStringDel (const char *item, const char *moduleName=PYKRITA_ENGINE)
bool	itemStringSet (const char *item, PyObject *value, const char *moduleName=PYKRITA_ENGINE)
QString	lastTraceback (void) const
PyObject *	moduleActions (const char *moduleName)
PyObject *	moduleConfigPages (const char *moduleName)
PyObject *	moduleDict (const char *moduleName=PYKRITA_ENGINE)
QString	moduleHelp (const char *moduleName)
PyObject *	moduleImport (const char *moduleName)
bool	prependPythonPaths (const QString &path)
bool	prependPythonPaths (const QStringList &paths)
bool	prependStringToList (PyObject *list, const QString &value)
	Prepend a QString to a list as a Python unicode object.
	Python ()
void	traceback (const QString &description)
	~Python ()

Static Public Member Functions
static void	ensureInitialized ()
static bool	isUnicode (PyObject *string)
	Test if a Python object is compatible with a QString.
static bool	libraryLoad ()
static void	libraryUnload ()
static void	maybeFinalize ()
static bool	setPath (const QStringList &scriptPaths)
static PyObject *	unicode (const QString &string)
	Convert a QString to a Python unicode object.
static QString	unicode (PyObject *string)
	Convert a Python unicode object to a QString.

Static Public Attributes
static const char *	PYKRITA_ENGINE = "pykrita"

Private Member Functions
PyObject *	kritaHandler (const char *moduleName, const char *handler)
bool	prependPythonPaths (const QString &, PyObject *)

Private Attributes
PyGILState_STATE	m_state
QString	m_traceback

Detailed Description

Instantiate this class on the stack to automatically get and release the GIL.

Also, making all the utility functions members of this class means that in many cases the compiler tells us where the class in needed. In the remaining cases (i.e. bare calls to the Python C API), inspection is used to needed to add the requisite Python() object. To prevent this object being optimised away in these cases due to lack of use, all instances have the form of an assignment, e.g.:

 Python py = Python()

This adds a little overhead, but this is a small price for consistency.

Definition at line 72 of file utilities.h.

Constructor & Destructor Documentation

Python()

PyKrita::Python::Python

(

)

Definition at line 123 of file utilities.cpp.

{
#if THREADED
    m_state = PyGILState_Ensure();
#endif
}

References m_state.

~Python()

PyKrita::Python::~Python

(

)

Definition at line 130 of file utilities.cpp.

{
#if THREADED
    PyGILState_Release(m_state);
#endif
}

References m_state.

Member Function Documentation

ensureInitialized()

void PyKrita::Python::ensureInitialized ( )

static

Make sure the Python interpreter is initialized. Ideally should be only called once.

Definition at line 434 of file utilities.cpp.

{
    if (Py_IsInitialized()) {
        warnScript << "Python interpreter is already initialized, not initializing again";
    } else {
        dbgScript << "Initializing Python interpreter";
        Py_InitializeEx(0);
        if (!Py_IsInitialized()) {
            errScript << "Could not initialize Python interpreter";
        }
#if THREADED
        s_pythonThreadState = PyGILState_GetThisThreadState();
        PyEval_ReleaseThread(s_pythonThreadState);
#endif
    }
}

References dbgScript, errScript, and warnScript.

functionCall() [1/2]

PyObject * PyKrita::Python::functionCall	(	const char *	functionName,
		const char *	moduleName,
		PyObject *	arguments )

Definition at line 157 of file utilities.cpp.

{
    if (!arguments) {
        errScript << "Missing arguments for" << moduleName << functionName;
        return nullptr;
    }
    PyObject* const func = itemString(functionName, moduleName);
    if (!func) {
        errScript << "Failed to resolve" << moduleName << functionName;
        return nullptr;
    }
    if (!PyCallable_Check(func)) {
        traceback(QString("Not callable %1.%2").arg(moduleName).arg(functionName));
        return nullptr;
    }
    PyObject* const result = PyObject_CallObject(func, arguments);
    if (!result)
        traceback(QString("No result from %1.%2").arg(moduleName).arg(functionName));
 
    return result;
}

References errScript, itemString(), and traceback().

functionCall() [2/2]

bool PyKrita::Python::functionCall	(	const char *	functionName,
		const char *	moduleName = PYKRITA_ENGINE )

Call the named module's named entry point.

Definition at line 147 of file utilities.cpp.

{
    auto arguments = PyTuple_New(0);
    PyObject* const result = functionCall(functionName, moduleName, arguments);
    Py_DECREF(arguments);
    if (result)
        Py_DECREF(result);
    return bool(result);
}

References functionCall().

isUnicode()

bool PyKrita::Python::isUnicode ( PyObject * string )

static

Test if a Python object is compatible with a QString.

Definition at line 612 of file utilities.cpp.

{
    return PyUnicode_Check(string);
}

itemString() [1/2]

PyObject * PyKrita::Python::itemString	(	const char *	item,
		const char *	moduleName = PYKRITA_ENGINE )

Get the item from the named module's dictionary.

Returns

0 or a borrowed reference to the item.

Definition at line 192 of file utilities.cpp.

{
    if (PyObject* const value = itemString(item, moduleDict(moduleName)))
        return value;
 
    errScript << "Could not get item string" << moduleName << item;
    return 0;
}

References errScript, itemString(), moduleDict(), and value().

itemString() [2/2]

PyObject * PyKrita::Python::itemString	(	const char *	item,
		PyObject *	dict )

Get the item from the given dictionary.

Returns

0 or a borrowed reference to the item.

Definition at line 201 of file utilities.cpp.

{
    if (dict)
        if (PyObject* const value = PyDict_GetItemString(dict, item))
            return value;
    traceback(QString("Could not get item string %1").arg(item));
    return 0;
}

References traceback(), and value().

itemStringDel()

bool PyKrita::Python::itemStringDel	(	const char *	item,
		const char *	moduleName = PYKRITA_ENGINE )

Delete the item from the named module's dictionary.

Definition at line 183 of file utilities.cpp.

{
    PyObject* const dict = moduleDict(moduleName);
    const bool result = dict && PyDict_DelItemString(dict, item);
    if (!result)
        traceback(QString("Could not delete item string %1.%2").arg(moduleName).arg(item));
    return result;
}

References moduleDict(), and traceback().

itemStringSet()

bool PyKrita::Python::itemStringSet	(	const char *	item,
		PyObject *	value,
		const char *	moduleName = PYKRITA_ENGINE )

Set the item in the named module's dictionary.

Definition at line 210 of file utilities.cpp.

{
    PyObject* const dict = moduleDict(moduleName);
    const bool result = dict && !PyDict_SetItemString(dict, item, value);
    if (!result)
        traceback(QString("Could not set item string %1.%2").arg(moduleName).arg(item));
    return result;
}

References moduleDict(), traceback(), and value().

kritaHandler()

PyObject * PyKrita::Python::kritaHandler ( const char * moduleName, const char * handler )

private

Run a handler function supplied by the krita module on another module.

Returns

0 or a new reference to the result.

Definition at line 219 of file utilities.cpp.

{
    if (PyObject* const module = moduleImport(moduleName)) {
        PyObject* args = Py_BuildValue("(O)", module);
        PyObject* ret = functionCall(handler, "krita", args);
        Py_DECREF(args);
        return ret;
    }
    return 0;
}

References functionCall(), and moduleImport().

lastTraceback()

QString PyKrita::Python::lastTraceback

(

void

)

const

Store the last traceback we handled using traceback().

Definition at line 230 of file utilities.cpp.

{
    QString result;
    result.swap(m_traceback);
    return result;
}

References m_traceback.

libraryLoad()

bool PyKrita::Python::libraryLoad ( )

static

Load the Python shared library. This does nothing on Windows.

Definition at line 237 of file utilities.cpp.

{
    // no-op on Windows
#if defined(Q_OS_UNIX) && !defined(Q_OS_MAC)
    if (!s_pythonLibrary) {
 
        QFileInfo fi(PYKRITA_PYTHON_LIBRARY);
        // get the filename of the configured Python library, without the .so suffix
        const QString libraryName = fi.completeBaseName();
        // 1.0 is the SONAME of the shared Python library
        s_pythonLibrary = new QLibrary(libraryName, "1.0");
        s_pythonLibrary->setLoadHints(QLibrary::ExportExternalSymbolsHint);
        if (!s_pythonLibrary->load()) {
            dbgScript << QString("Could not load %1 -- Reason: %2").arg(s_pythonLibrary->fileName()).arg(s_pythonLibrary->errorString());
            delete s_pythonLibrary;
            s_pythonLibrary = 0;
            return false;
        }
        dbgScript << QString("Loaded %1").arg(s_pythonLibrary->fileName());
    }
#endif
    return true;
}

References dbgScript.

libraryUnload()

void PyKrita::Python::libraryUnload ( )

static

Unload the Python shared library. This does nothing on Windows.

Definition at line 463 of file utilities.cpp.

{
    // no-op on Windows
#ifndef Q_OS_WIN
    if (s_pythonLibrary) {
        // Shut the interpreter down if it has been started.
        if (s_pythonLibrary->isLoaded()) {
            s_pythonLibrary->unload();
        }
        delete s_pythonLibrary;
        s_pythonLibrary = 0;
    }
#endif
}

maybeFinalize()

void PyKrita::Python::maybeFinalize ( )

static

Finalize the Python interpreter. Not guaranteed to work.

Definition at line 451 of file utilities.cpp.

{
    if (!Py_IsInitialized()) {
        warnScript << "Python interpreter not initialized, no need to finalize";
    } else {
#if THREADED
        PyEval_AcquireThread(s_pythonThreadState);
#endif
        Py_Finalize();
    }
}

References warnScript.

moduleActions()

PyObject * PyKrita::Python::moduleActions

(

const char *

moduleName

)

Get the Actions defined by a module. The returned object is [ { function, ( text, icon, shortcut, menu ) }... ] for each module function decorated with action.

Returns

0 or a new reference to the result.

Definition at line 478 of file utilities.cpp.

{
    return kritaHandler(moduleName, "moduleGetActions");
}

References kritaHandler().

moduleConfigPages()

PyObject * PyKrita::Python::moduleConfigPages

(

const char *

moduleName

)

Get the ConfigPages defined by a module. The returned object is [ { function, callable, ( name, fullName, icon ) }... ] for each module function decorated with configPage.

Returns

0 or a new reference to the result.

Definition at line 483 of file utilities.cpp.

{
    return kritaHandler(moduleName, "moduleGetConfigPages");
}

References kritaHandler().

moduleDict()

PyObject * PyKrita::Python::moduleDict

(

const char *

moduleName = PYKRITA_ENGINE

)

Get the named module's dictionary.

Returns

0 or a borrowed reference to the dictionary.

Definition at line 499 of file utilities.cpp.

{
    PyObject* const module = moduleImport(moduleName);
    if (module)
        if (PyObject* const dictionary = PyModule_GetDict(module))
            return dictionary;
 
    traceback(QString("Could not get dict %1").arg(moduleName));
    return 0;
}

References traceback().

moduleHelp()

QString PyKrita::Python::moduleHelp

(

const char *

moduleName

)

Get the help text defined by a module.

Definition at line 488 of file utilities.cpp.

{
    QString r;
    PyObject* const result = kritaHandler(moduleName, "moduleGetHelp");
    if (result) {
        r = unicode(result);
        Py_DECREF(result);
    }
    return r;
}

References kritaHandler(), and unicode().

moduleImport()

PyObject * PyKrita::Python::moduleImport

(

const char *

moduleName

)

Import the named module.

Returns

0 or a borrowed reference to the module.

Definition at line 510 of file utilities.cpp.

{
    PyObject* const module = PyImport_ImportModule(moduleName);
    if (module)
        return module;
 
    traceback(QString("Could not import %1").arg(moduleName));
    return 0;
}

References traceback().

prependPythonPaths() [1/3]

bool PyKrita::Python::prependPythonPaths ( const QString & path, PyObject * sys_path )

private

Definition at line 644 of file utilities.cpp.

{
    Q_ASSERT("Dir entry expected to be valid" && sys_path);
    return bool(prependStringToList(sys_path, path));
}

References prependStringToList().

prependPythonPaths() [2/3]

bool PyKrita::Python::prependPythonPaths

(

const QString &

path

)

Add a given path to to the front of PYTHONPATH

Parameters

path	A string (path) to be added

Returns

true on success, false otherwise.

Definition at line 617 of file utilities.cpp.

{
    PyObject* sys_path = itemString("path", "sys");
    return bool(sys_path) && prependPythonPaths(path, sys_path);
}

References itemString(), and prependPythonPaths().

prependPythonPaths() [3/3]

bool PyKrita::Python::prependPythonPaths

(

const QStringList &

paths

)

Add listed paths to to the front of PYTHONPATH

Parameters

paths

A string list (paths) to be added

Returns

true on success, false otherwise.

Todo

Heh, boosts' range adaptors would be good here!

Definition at line 623 of file utilities.cpp.

{
    PyObject* sys_path = itemString("path", "sys");
    if (!sys_path)
        return false;
 
    QStringList reversed_paths;
    std::reverse_copy(
        paths.begin()
        , paths.end()
        , std::back_inserter(reversed_paths)
    );
 
    Q_FOREACH(const QString & path, reversed_paths)
    if (!prependPythonPaths(path, sys_path))
        return false;
 
    return true;
}

References itemString(), and prependPythonPaths().

prependStringToList()

bool PyKrita::Python::prependStringToList	(	PyObject *	list,
		const QString &	value )

Prepend a QString to a list as a Python unicode object.

Definition at line 137 of file utilities.cpp.

{
    PyObject* const u = unicode(value);
    bool result = !PyList_Insert(list, 0, u);
    Py_DECREF(u);
    if (!result)
        traceback(QString("Failed to prepend %1").arg(value));
    return result;
}

References traceback(), u, unicode(), and value().

setPath()

bool PyKrita::Python::setPath ( const QStringList & scriptPaths )

static

Set the Python paths by calling Py_SetPath. This should be called before initialization to ensure the proper libraries get loaded.

Definition at line 296 of file utilities.cpp.

{
 
    KIS_SAFE_ASSERT_RECOVER_RETURN_VALUE(!Py_IsInitialized(), false);
    KIS_SAFE_ASSERT_RECOVER_RETURN_VALUE(!isPythonPathSet, false);
 
//    qDebug() << ">>>>>>>>>>>" << qgetenv("APPDIR")
//             << KoResourcePaths::getApplicationRoot()
//             << (!qgetenv("APPDIR").isNull() && KoResourcePaths::getApplicationRoot().contains(qgetenv("APPDIR")));
 
 
#if defined Q_OS_WIN
    bool runningInBundle = false;
#elif defined Q_OS_MAC
    bool runningInBundle = KoResourcePaths::getApplicationRoot().toLower().contains("krita.app");
#else
    bool runningInBundle = (!qgetenv("APPDIR").isNull() &&
                             KoResourcePaths::getApplicationRoot().contains(qgetenv("APPDIR")));
#endif
    dbgScript << "Python::setPath. Script paths:" << scriptPaths << runningInBundle;
 
#ifdef Q_OS_WIN
    constexpr char pathSeparator = ';';
#else
    constexpr char pathSeparator = ':';
#endif
 
    QString originalPath;
    // Start with the script paths
    QStringList paths(scriptPaths);
 
    // Append the Krita libraries path
    QString pythonLibsPath = findKritaPythonLibsPath("krita-python-libs");
    dbgScript << "pythonLibsPath (krita-python-libs)" << pythonLibsPath;
    if (pythonLibsPath.isEmpty()) {
        dbgScript << "Cannot find krita-python-libs";
        return false;
    }
    dbgScript << "Found krita-python-libs at" << pythonLibsPath;
    paths.append(pythonLibsPath);
 
#ifndef Q_OS_WIN
    // Append the sip libraries path
    pythonLibsPath = findKritaPythonLibsPath("sip");
    dbgScript << "pythonLibsPath (sip)" << pythonLibsPath;
    if (!pythonLibsPath.isEmpty()) {
        dbgScript << "Found sip at" << pythonLibsPath;
        paths.append(pythonLibsPath);
    }
#endif
 
#ifdef Q_OS_WIN
    // Find embeddable Python at <root>/python
    QDir pythonDir(KoResourcePaths::getApplicationRoot());
    if (pythonDir.cd("python")) {
        const QString pythonHome = pythonDir.absolutePath();
        dbgScript << "Found bundled Python at" << pythonHome;
        // The default paths for Windows embeddable Python is
        // ./python[0-9][0-9]+.zip;./
        // Ordinarily, Python would find its own bundle here.
        // But because we set sys.path manually afterwards,
        // the prefix gets zeroed out. See
        // https://docs.python.org/3/c-api/init.html#c.Py_SetPath
        paths.append(pythonDir.absoluteFilePath(QStringLiteral("python%1%2.zip")
                                                    .arg(PY_MAJOR_VERSION)
                                                    .arg(PY_MINOR_VERSION)));
        paths.append(pythonDir.absolutePath());
    } else {
        errScript << "Bundled Python not found, cannot set Python library paths";
        return false;
    }
 
    // Add stock Python libs folder at <root>/lib/site-packages
    QString distToolsPath = findKritaPythonLibsPath("site-packages");
    dbgScript << "distToolsPath (site-packages)" << distToolsPath;
    if (distToolsPath.isEmpty()) {
        dbgScript << "Cannot find site-packages";
        return false;
    }
    dbgScript << "Found site-packages at" << distToolsPath;
    paths.append(distToolsPath);
#else
    // If using a system Python install, respect the current PYTHONPATH
    if (runningInBundle) {
        // We're running from an appimage, so we need our local python
        QString p = QFileInfo(PYKRITA_PYTHON_LIBRARY).fileName();
#ifdef Q_OS_MAC
        QString p2 = p.remove("lib").remove("m.dy").remove(".dy");
#else
        QString p2 = p.remove("lib").remove("m.so").remove(".so");
#endif
        dbgScript << "\t" << p << p2;
        originalPath = findKritaPythonLibsPath(p);
#ifdef Q_OS_MAC
        // Are we running with a system Python library instead?
        if (originalPath.isEmpty()) {
            // Keep the original Python search path.
            originalPath = QString::fromWCharArray(Py_GetPath());
            QString d = QFileInfo(PYKRITA_PYTHON_LIBRARY).absolutePath();
 
            paths.append(d + "/" + p2 + "/site-packages");
#if QT_VERSION >= QT_VERSION_CHECK(6, 0, 0)
            paths.append(d + "/" + p2 + "/site-packages/PyQt6");
#else
            paths.append(d + "/" + p2 + "/site-packages/PyQt5");
#endif
            
        }
        else {
#endif
            paths.append(originalPath + "/lib-dynload");
            paths.append(originalPath + "/site-packages");
#if QT_VERSION >= QT_VERSION_CHECK(6, 0, 0)
            paths.append(originalPath + "/site-packages/PyQt6");
#else
            paths.append(originalPath + "/site-packages/PyQt5");
#endif
#ifdef Q_OS_MAC
        }
#endif
    }
    else {
        // Use the system path
        originalPath = QString::fromLocal8Bit(qgetenv("PYTHONPATH"));
    }
#endif
 
    QString joinedPaths = paths.join(pathSeparator);
    if (!originalPath.isEmpty()) {
        joinedPaths = joinedPaths + pathSeparator + originalPath;
    }
    dbgScript << "Setting python paths:" << joinedPaths;
    qputenv("PYTHONPATH", joinedPaths.toLocal8Bit());
 
    isPythonPathSet = true;
    return true;
}

References dbgScript, errScript, KoResourcePaths::getApplicationRoot(), KIS_SAFE_ASSERT_RECOVER_RETURN_VALUE, p, and p2.

traceback()

void PyKrita::Python::traceback

(

const QString &

description

)

Print and save (see lastTraceback()) the current traceback in a form approximating what Python would print:

* Traceback (most recent call last):
*   File "/home/shahhaqu/.kde/share/apps/krita/pykrita/pluginmgr.py", line 13, in <module>
*     import kdeui
* ImportError: No module named kdeui
* Could not import pluginmgr.
* 

Todo

How about to show it somewhere else than "console output"?

Definition at line 521 of file utilities.cpp.

{
    m_traceback.clear();
    if (!PyErr_Occurred())
        // Return an empty string on no error.
        // NOTE "Return a string?" really??
        return;
 
    PyObject* exc_typ;
    PyObject* exc_val;
    PyObject* exc_tb;
    PyErr_Fetch(&exc_typ, &exc_val, &exc_tb);
    PyErr_NormalizeException(&exc_typ, &exc_val, &exc_tb);
 
    // Include the traceback.
    if (exc_tb) {
        m_traceback = "Traceback (most recent call last):\n";
        PyObject* const arguments = PyTuple_New(1);
        PyTuple_SetItem(arguments, 0, exc_tb);
        PyObject* const result = functionCall("format_tb", "traceback", arguments);
        Py_DECREF(arguments);
        if (result) {
            for (int i = 0, j = PyList_Size(result); i < j; i++) {
                PyObject* const tt = PyList_GetItem(result, i);
                PyObject* const t = Py_BuildValue("(O)", tt);
                char* buffer;
                if (!PyArg_ParseTuple(t, "s", &buffer))
                    break;
                m_traceback += buffer;
            }
            Py_DECREF(result);
        }
        Py_DECREF(exc_tb);
    }
 
    // Include the exception type and value.
    if (exc_typ) {
        PyObject* const temp = PyObject_GetAttrString(exc_typ, "__name__");
        if (temp) {
            m_traceback += unicode(temp);
            m_traceback += ": ";
        }
        Py_DECREF(exc_typ);
    }
 
    if (exc_val) {
        PyObject* const temp = PyObject_Str(exc_val);
        if (temp) {
            m_traceback += unicode(temp);
            m_traceback += "\n";
        }
        Py_DECREF(exc_val);
    }
    m_traceback += description;
 
    QStringList l = m_traceback.split("\n");
    Q_FOREACH(const QString &s, l) {
        errScript << s;
    }
}

References errScript, functionCall(), m_traceback, and unicode().

unicode() [1/2]

PyObject * PyKrita::Python::unicode ( const QString & string )

static

Convert a QString to a Python unicode object.

Definition at line 583 of file utilities.cpp.

{
    return PyUnicode_FromKindAndData(PyUnicode_2BYTE_KIND,
                                     string.constData(),
                                     string.length());
}

References length().

unicode() [2/2]

QString PyKrita::Python::unicode ( PyObject * string )

static

Convert a Python unicode object to a QString.

Definition at line 590 of file utilities.cpp.

{
    if (!PyUnicode_Check(string))
        return QString();
 
    const int unichars = PyUnicode_GetLength(string);
    if (0 != PyUnicode_READY(string))
        return QString();
 
    switch (PyUnicode_KIND(string)) {
    case PyUnicode_1BYTE_KIND:
        return QString::fromLatin1((const char*)PyUnicode_1BYTE_DATA(string), unichars);
    case PyUnicode_2BYTE_KIND:
        return QString::fromUtf16(PyUnicode_2BYTE_DATA(string), unichars);
    case PyUnicode_4BYTE_KIND:
        return QString::fromUcs4(PyUnicode_4BYTE_DATA(string), unichars);
    default:
        break;
    }
    return QString();
}

Member Data Documentation

m_state

PyGILState_STATE PyKrita::Python::m_state

private

Definition at line 224 of file utilities.h.

m_traceback

QString PyKrita::Python::m_traceback

mutableprivate

Definition at line 225 of file utilities.h.

PYKRITA_ENGINE

const char * PyKrita::Python::PYKRITA_ENGINE = "pykrita"

static

Definition at line 219 of file utilities.h.

---

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

• plugins/extensions/pykrita/plugin/utilities.h
• plugins/extensions/pykrita/plugin/utilities.cpp