qonsole 3.2.1

Light-weight python interpreter, easy to embed into Qt applications

About

Qonsole is a lightweight Python console for Qt applications. It's made to be easy to embed in other PySide/PyQt applications and comes with some examples that show how this can be done. The interpreter can run in a separate thread, in the UI main thread or in a gevent task. Qonsole is a fork of pyqtconsole. The two diverged at pyqtconsole v1.3.0, and it is not quite a drop-in replacement, but does implement new features and has various improvements.

Simple usage

The following snippet shows how to create a console that will execute user input in a separate thread. Be aware that long running tasks will still block the main thread due to the GIL. See the examples directory for more examples.

import sys
from threading import Thread
from PyQt5.QtWidgets import QApplication

from qonsole import PythonConsole

app = QApplication([])
console = PythonConsole()
console.show()
console.eval_in_thread()

sys.exit(app.exec_())

Embedding

• Separate thread - Runs the interpreter in a separate thread, see the example threaded.py. Running the interpreter in a separate thread obviously limits the interaction with the Qt application. The parts of Qt that needs to be called from the main thread will not work properly, but is excellent way for having a 'plain' python console in your Qt app.

• main thread - Runs the interpreter in the main thread, see the example inuithread.py. Makes full interaction with Qt possible, lenghty operations will of course freeze the UI (as any lenghty operation that is called from the main thread). This is a great alternative for people who does not want to use the gevent based approach but still wants full interactivity with Qt.

• gevent - Runs the interpreter in a gevent task, see the example _gevent.py. Allows for full interactivity with Qt without special consideration (at least to some extent) for longer running processes. The best method if you want to use pyQtgraph, Matplotlib, PyMca or similar.

Features

Syntax highlighting

Syntax highlighting is provided by the https://pygments.org library. Simply pass the Pygments style string to the PythonConsole constructer like so:

console = PythonConsole(pygments_style='github-dark')

Magic commands

Commands that start with % are magic commands. This features provides IPython-like magic commands such as:

• %pwd -- Print current working directory
• %cd -- Change directory
• %ls -- List directory contents
• %who -- List variable names in the current namespace
• %whos -- Display detailed variable information
• %timeit -- Time the execution of a Python statement
• %run -- Execute a Python script file
• %clear -- Clear the console display
• %export -- Export console session as Python script (.py) or Jupyter notebook (.ipynb)
• %help -- Display help message for magic commands

In addition, custom magic commands can be defined by using the add_magic_command() method. Example:

def version(args=None):
    return '3.2.1'

console = PythonConsole()
console.add_magic_command("version", version)

Which can be used like so:

   IN [0]: %version
           3.2.1

Clear console

A local method, named clear(), is available to clear the input screen and reset the line numbering. Enable it by pushing the method into the available namespace in the console:

   console.interpreter.locals["clear"] = console.clear

Shell commands

Commands entered in the console that start with ! will be executed as shell commands. The output of the command will be printed in the console. For example, on a Linux or macOS system, entering !ls -l will list the files in the current directory. Example:

   IN [0]: !ls -l
   OUT[0]: total 16546
           -rw-r--r-- 1 user user      18741 Fen  6  2026  file1.txt
           -rw-r--r-- 1 user user      18741 Feb  6  2026  file2.txt

Prompt String

By default IN [n]: and OUT [n]: are displayed before each input and output line. You can customize this through constructor arguments:

# Including the line numbers:
console = PythonConsole(inprompt="%d >", outprompt="%d <")
# Or just static:
console = PythonConsole(inprompt=">>>", outprompt="<<<")

Right-click menu

The console's right-click menu includes several useful items:

• "Copy"
• "Paste"
• "Select All"
• "Clear Console" (same as the %clear magic command)
• "Export Session" (same as the %export magic command)
• "Toggle Word Wrap"

Credits

This module depends on QtPy which provides a compatibility layer for Qt. The console is tested under both Qt5 and Qt6.

Development

• Repository at GitHub
• To generate coverage information for the unit tests, run pixi run "coverage run -m pytest tests/ && coverage report -m && coverage html"