Python script launcher with logging and progress support. More...

#include <python_runner.h>

Signals
void	lineReceived (int channel, const QString &line)
void	progressUpdated (float pct, const QString &msg)
void	finished (const UTILSLIB::PythonRunnerResult &result)

Public Member Functions
	PythonRunner (QObject *pParent=nullptr)
	PythonRunner (const PythonRunnerConfig &config, QObject *pParent=nullptr)
void	setConfig (const PythonRunnerConfig &config)
const PythonRunnerConfig &	config () const
void	setLineCallback (PythonLineCallback cb)
void	setProgressCallback (PythonProgressCallback cb)
PythonRunnerResult	run (const QString &scriptPath, const QStringList &args={})
PythonRunnerResult	runCode (const QString &code, const QStringList &args={})
bool	isPythonAvailable () const
QString	pythonVersion () const
bool	isPackageAvailable (const QString &packageName) const
PythonRunnerResult	ensureVenv ()
PythonRunnerResult	runInVenv (const QString &scriptPath, const QStringList &args={})
QString	venvPythonPath () const

Detailed Description

Python script launcher with logging and progress support.

Standardized interface for launching Python scripts from C++.

Features:

Auto-discovers Python via PATH or explicit config.
Runs scripts with -u (unbuffered) by default for real-time output.
Streams stdout/stderr line-by-line through optional callbacks.
Parses a simple progress protocol: lines matching [progress] <float>% or [progress] <float>% <message>.
Integrates with MNE-CPP's logging (qDebug/qWarning).
Supports timeout, environment injection, and working directory.

No Python embedding or linkage is required.

Definition at line 131 of file python_runner.h.

Inheritance diagram for UTILSLIB::PythonRunner:

Constructor & Destructor Documentation

◆ PythonRunner() [1/2]

PythonRunner::PythonRunner ( QObject * pParent = nullptr )

explicit

Construct a PythonRunner with default configuration.

Parameters

[in] pParent Parent QObject (optional).

Definition at line 63 of file python_runner.cpp.

◆ PythonRunner() [2/2]

PythonRunner::PythonRunner	(	const PythonRunnerConfig &	config,
		QObject *	pParent = nullptr )

explicit

Construct a PythonRunner with explicit configuration.

Parameters

[in]	config	Execution configuration.
[in]	pParent	Parent QObject (optional).

Definition at line 70 of file python_runner.cpp.

Member Function Documentation

◆ config()

const PythonRunnerConfig & PythonRunner::config ( ) const

Get the current configuration.

Returns: Current configuration.

Definition at line 85 of file python_runner.cpp.

◆ ensureVenv()

PythonRunnerResult PythonRunner::ensureVenv ( )

Ensure a virtual environment exists, is up-to-date, and has all required packages installed.

Workflow:

If config().venvDir is empty, returns immediately (no-op).
Creates the venv if it doesn't exist yet (python -m venv ...).
Installs dependencies:
- If config().packageDir is set (contains pyproject.toml): runs pip install <packageDir> inside the venv.
- Else if config().requirementsFile is set: runs pip install -r <file> inside the venv.
On success, updates the internal config so that subsequent run()/runCode() calls use the venv's Python interpreter.

Returns: PythonRunnerResult describing the venv setup outcome.

Definition at line 197 of file python_runner.cpp.

◆ finished

void UTILSLIB::PythonRunner::finished ( const UTILSLIB::PythonRunnerResult & result )

signal

Emitted when the script finishes.

Parameters

[in] result Execution result.

◆ isPackageAvailable()

bool PythonRunner::isPackageAvailable ( const QString & packageName ) const

Check whether a Python package is importable.

Parameters

[in] packageName Package name (e.g. "torch", "mne").

Returns: True if the import succeeds.

Definition at line 163 of file python_runner.cpp.

◆ isPythonAvailable()

bool PythonRunner::isPythonAvailable ( ) const

Check that the configured Python interpreter is reachable.

Returns: True if python --version succeeds.

Definition at line 135 of file python_runner.cpp.

◆ lineReceived

void UTILSLIB::PythonRunner::lineReceived	(	int	channel,
		const QString &	line )

signal

Emitted for every stdout/stderr line (mirrors the line callback).

Parameters

[in]	channel	0 = stdout, 1 = stderr.
[in]	line	Text line.

◆ progressUpdated

void UTILSLIB::PythonRunner::progressUpdated	(	float	pct,
		const QString &	msg )

signal

Emitted when a progress line is parsed (mirrors the progress callback).

Parameters

[in]	pct	Progress 0–100.
[in]	msg	Optional message.

◆ pythonVersion()

QString PythonRunner::pythonVersion ( ) const

Query the version string of the configured Python interpreter.

Returns: Version string (e.g. "3.11.5"), or empty if unavailable.

Definition at line 146 of file python_runner.cpp.

◆ run()

PythonRunnerResult PythonRunner::run	(	const QString &	scriptPath,
		const QStringList &	args = {} )

Run a Python script synchronously.

Parameters

[in]	scriptPath	Path to the .py file.
[in]	args	Arguments forwarded to the script.

Returns: PythonRunnerResult with exit code, output, and progress.

Definition at line 106 of file python_runner.cpp.

◆ runCode()

PythonRunnerResult PythonRunner::runCode	(	const QString &	code,
		const QStringList &	args = {} )

Run a Python one-liner synchronously (python -c "...").

Parameters

[in]	code	Python code string.
[in]	args	Extra arguments appended after -c code.

Returns: PythonRunnerResult.

Definition at line 120 of file python_runner.cpp.

◆ runInVenv()

PythonRunnerResult PythonRunner::runInVenv	(	const QString &	scriptPath,
		const QStringList &	args = {} )

Convenience: ensure venv, then run a script inside it.

Equivalent to calling ensureVenv() + run(), but returns early with an error result if venv setup fails.

Parameters

[in]	scriptPath	Path to the .py file.
[in]	args	Arguments forwarded to the script.

Returns: PythonRunnerResult.

Definition at line 321 of file python_runner.cpp.

◆ setConfig()

void PythonRunner::setConfig ( const PythonRunnerConfig & config )

Set the configuration.

Parameters

[in] config Execution configuration.

Definition at line 78 of file python_runner.cpp.

◆ setLineCallback()

void PythonRunner::setLineCallback ( PythonLineCallback cb )

Set a callback invoked for every stdout/stderr line.

Parameters

[in] cb Line callback (channel, line).

Definition at line 92 of file python_runner.cpp.

◆ setProgressCallback()

void PythonRunner::setProgressCallback ( PythonProgressCallback cb )

Set a callback invoked when a progress line is detected.

Progress protocol: the script prints lines matching: [progress] 42.5% [progress] 42.5% Training epoch 10/50

Parameters

[in] cb Progress callback (pct, msg).

Definition at line 99 of file python_runner.cpp.

◆ venvPythonPath()

QString PythonRunner::venvPythonPath ( ) const

Get the Python interpreter path inside the configured venv.

Returns: Absolute path to venv python, or empty if no venv configured.

Definition at line 183 of file python_runner.cpp.

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

src/libraries/utils/python_runner.h
src/libraries/utils/python_runner.cpp

Signals

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ PythonRunner() [1/2]

◆ PythonRunner() [2/2]

Member Function Documentation

◆ config()

◆ ensureVenv()

◆ finished

◆ isPackageAvailable()

◆ isPythonAvailable()

◆ lineReceived

◆ progressUpdated

◆ pythonVersion()

◆ run()

◆ runCode()

◆ runInVenv()

◆ setConfig()

◆ setLineCallback()

◆ setProgressCallback()

◆ venvPythonPath()