https://github.com/jacobwilliams/qonsole
Embed a Python interpreter in PySide/PyQt applications
https://github.com/jacobwilliams/qonsole
ipython pygments pyqt6 pyside6 python qt terminal
Last synced: about 1 month ago
JSON representation
Embed a Python interpreter in PySide/PyQt applications
- Host: GitHub
- URL: https://github.com/jacobwilliams/qonsole
- Owner: jacobwilliams
- License: other
- Created: 2026-04-05T17:16:56.000Z (about 2 months ago)
- Default Branch: master
- Last Pushed: 2026-04-17T04:03:32.000Z (about 1 month ago)
- Last Synced: 2026-04-17T05:32:54.605Z (about 1 month ago)
- Topics: ipython, pygments, pyqt6, pyside6, python, qt, terminal
- Language: Python
- Homepage: https://jacobwilliams.github.io/qonsole
- Size: 655 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://github.com/pyqtconsole/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.
```python
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](pygments) library.
Simply pass the Pygments style string to the ``PythonConsole`` constructer like so:
```python
console = PythonConsole(pygments_style='github-dark')
```
### Magic commands
Commands that start with `%` are magic commands.
This features provides IPython-like [magic commands](https://ipython.readthedocs.io/en/stable/interactive/magics.html) 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:
```python
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:
```python
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:
```python
# 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](https://github.com/spyder-ide/qtpy) which provides a compatibility layer for
Qt. The console is tested under both Qt5 and Qt6.
## Development
* [Repository at GitHub](https://github.com/jacobwilliams/vibehdf5)
* To generate coverage information for the unit tests, run `pixi run "coverage run -m pytest tests/ && coverage report -m && coverage html"`