Skip to main content

Expose class interfaces from the main GUI Thread in another QThread in Qt for Python

Project description

Pqthreads

Pqthreads exposes class interfaces from the main GUI Thread in another QThread in Qt for Python (PySide). In doing so, it facilitates communication between the main (GUI) thread and a dedicated QThreads as offered by Qt for Python.

Installation

Pqthreads comes as a package in the Python Package Index (PyPi) and can be installed using pip:

pip install pqthreads

Usage

In order to use pqhreads, you'll first need a GUI implementation (in Qt for Python (PySide)) whose interface you'd like to expose. Then you need to have a corresponding class that exposes (chosen) methods and attributes in another thread.

GUI implementation

The GUI implementation would be a class that derives from QWidget, e.g. QMainWindow. A very basic example class called FigureWindow can be found in window.py.

Worker class

In a class that inherits from containers.WorkerItem you then choose which methods and attributes are exposed. An examples of this is the class FigureWorker as found in worker.py.

Putting it all together

Using the GUI implementation FigureWindow and worker class FigureWorker the utilities from decorator.py can be used to create a custom decorator:

from pqthreads import decorator

DecoratorCore = decorator.DecoratorCore
DecoratorCore.add_agent('figure', window.FigureWindow, FigureWorker)
decorator_example = decorator.Decorator(DecoratorCore)

Any decorated function will run in the worker thread, while all GUI elements run in the (main) GUI thread.

To simplify access to worker class interfaces, a helper function is useful. This also illustrates how to create and access new GUI elements:

from pqthreads import refs

def figure(*args, **kwargs):
    """ Create, raise or modify FigureWorker objects """
    container = refs.worker.get('figure')
    if not args:
        return container.create(**kwargs)
    figure_worker = args[0]
    container.current = figure_worker
    return figure_worker

This can finally be used to to expose GUI implementation in an existing python program that will run in another worker thread.

from pqthreads.examples import worker

@decorator_example
def main():
    fig = worker.figure(title='Initial title')
    fig.change_title(title='Another title')
    fig.close()

Pittfalls

As illustrated in the previous section, worker class interfaces are accessed through the so-called worker references (as is provided in the module refs). All interfaces are provided as weak references. As soon as the decorated function is exited, the weak references will invalidate and can't be used anymore. Therefore, it's recommended to decorate the function that encapsulates the whole python program in question. This assures that different parts of your own program run in different threads.

The module refs also comes with an object called gui references that stores weak references to the GUI objects. These also will invalidate when the decorated function is exited.

Finally, one should not access the worker references from the (main) GUI thread and also not access gui references from the worker thread. This can lead to trace errors and all sorts of undefined behavior. You have been warned!

Design

Pqthreads separates the GUI elements from all programming elements in QThreads. Since Qt demands that the main thread is used for GUI elements, all other programming functionalities are moved into a dedicated QThread. This shall be called the worker threads.

The following schematic depicts this design.

Pqthreads design

Communication between the GUI and worker threads is solely done using Signal/Slot connections. This is facilitated by the GUIAgents and WorkerAgents.

The interface of a GUI Object is exposed by means of a Worker Object in the Worker Thread.

It is possible expose the interface of multiple types of GUI Objects (in the shown schematic FigureWindow and GraphWindow), which requires multiple Worker- and GUIAgents. These are held the GUIAgency and WorkerAgency respectively.

For each type of GUI/Worker object pair, it's also possible to instantiate multiple objects (of the same type). GUI and Worker objects are held in the GUIItemContainer and WorkerItemContainer respectively.

License

An MIT style license applies for pqthreads, see the LICENSE file for more details.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pqthreads-0.4.1.tar.gz (14.1 kB view details)

Uploaded Source

Built Distribution

pqthreads-0.4.1-py3-none-any.whl (15.6 kB view details)

Uploaded Python 3

File details

Details for the file pqthreads-0.4.1.tar.gz.

File metadata

  • Download URL: pqthreads-0.4.1.tar.gz
  • Upload date:
  • Size: 14.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for pqthreads-0.4.1.tar.gz
Algorithm Hash digest
SHA256 6cff92092701fcda509613df3c2e67df5e4f8adf94ebd77ce9d02c09a283ff08
MD5 e003176a3853f3f83cd05980037b96ec
BLAKE2b-256 9ebba0dbc745015bbf93a601abc6d6801ec3a11e368d8ffa749e0a7078049a27

See more details on using hashes here.

Provenance

The following attestation bundles were made for pqthreads-0.4.1.tar.gz:

Publisher: push.yaml on swvanbuuren/pqthreads

Attestations:

File details

Details for the file pqthreads-0.4.1-py3-none-any.whl.

File metadata

  • Download URL: pqthreads-0.4.1-py3-none-any.whl
  • Upload date:
  • Size: 15.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for pqthreads-0.4.1-py3-none-any.whl
Algorithm Hash digest
SHA256 967a53df928fb962b1de60396d048ffbf68a6c3fa7021ef2fe2175a1f0be9214
MD5 e0921397459bba83b2af55085cc7652a
BLAKE2b-256 6d3b8993a15cc65a60a66f819e01d01d083beccd3c3c8d19a0adb68926b795da

See more details on using hashes here.

Provenance

The following attestation bundles were made for pqthreads-0.4.1-py3-none-any.whl:

Publisher: push.yaml on swvanbuuren/pqthreads

Attestations:

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page