UpscalerSession

upscaler.UpscalerSession

Bases: QObject

Manage an upscaling instance.

The session handles configuration loading, target window acquisition, Qt event loop ownership, pipeline creation and cleanup.

Qt modes

• Script mode (session owns the Qt event loop):

  from upscaler import UpscalerSession
  from upscaler.acquisition import find_window_by_title
  
  win = find_window_by_title(contains="A Game")
  with UpscalerSession(window=win) as session:
      session.run()
  

• Embedded mode (host already has a Qt event loop):

  from upscaler import UpscalerSession
  from upscaler.acquisition import find_window_by_title
  
  win = find_window_by_title(contains="A Game")
  session = UpscalerSession(window=win, enable_hotkeys=False)
  
  # Connect signals before starting
  session.finished.connect(lambda: session.close())
  session.error.connect(print)
  
  session.start()
  # The host event loop keeps running, while the session runs in the background
  

Errors

All errors derive from UpscalerError:

• WindowNotFound: target window could not be found/acquired.
• ConfigError: configuration loading/validation failed.
• SessionAlreadyRunning: start() called twice.
• EventLoopError: run() called from the wrong thread or while another Qt event loop is active.

Example with error handling:

from upscaler import UpscalerSession
from upscaler.acquisition import find_window_by_title
from upscaler.exceptions import UpscalerError, WindowNotFound

try:
    win = find_window_by_title(contains="A Game")
    with UpscalerSession(window=win) as session:
        session.run()
except WindowNotFound:
    print("Window not found")
except UpscalerError as e:
    print(f"Upscaler error: {e}")

Signals

• finished: emitted when the pipeline stops (normally or by error).
• error(str): emitted when a fatal error occurs.
• window_changed(WindowInfo): emitted when the target window changes (follow focus mode).
• daemon_match(WindowInfo): emitted when daemon mode finds a new window.

config property

The active configuration object.

profile_name property

Name of the currently applied profile, if any.

profiles property

Loaded profile definitions.

running property

True if the session is currently running.

window_info property

The current target window, or None if daemon waiting.

__init__(window=None, *, config=None, config_path=None, profile_name=None, overrides=None, enable_hotkeys=True, enable_daemon=None, enable_follow_focus=None, auto_profile_match=True)

Initialize the session and prepare the configuration.

Parameters:

Name	Type	Description	Default
window	Optional[WindowInfo]	Target window to upscale. If None and daemon mode is enabled, the session will wait for a window matching a profile.	None
config	Optional[Config]	A validated :class:upscaler.Config object. If provided, it is used as the base configuration (still subject to overrides). Loading from config_path is then skipped.	None
config_path	Optional[str]	Path to a YAML configuration file. Defaults to the user configuration directory.	None
profile_name	Optional[str]	Name of an explicit profile to apply.	None
overrides	Optional[Dict[str, Any]]	Additional key/value overrides, taking precedence over everything else.	None
enable_hotkeys	bool	If True, global hotkeys are registered. Defaults to True for script mode, but could be set to False when embedding to avoid conflicts.	True
enable_daemon	Optional[bool]	Override the daemon flag in the final config.	None
enable_follow_focus	Optional[bool]	Override the follow_focus flag.	None
auto_profile_match	bool	If True, automatically apply a matching profile for the target window after acquisition.	True

Raises:

Type	Description
ConfigError	If configuration cannot be loaded or validated.
WindowNotFound	If a window is required but not provided and daemon mode is not enabled.

close()

Stop the pipeline and release all resources.

This method is idempotent and safe to call multiple times.

run()

Enter the Qt event loop and block until the session finishes.

This method is intended for script mode, where the session owns the Qt event loop. It must be called from the main thread.

Returns:

Type	Description
int	Exit code (0 on normal termination).

Raises:

Type	Description
UpscalerError	If the session has not been started.
EventLoopError	If no QApplication is available, or if an event loop is already running (use :meth:wait instead).

start()

Create the pipeline session and start background threads.

This method does not enter the Qt event loop. It will create a QApplication if none exists, but it is the caller's responsibility to later run the event loop (e.g., via :meth:run or by already having one in the host application).

Raises:

Type	Description
SessionAlreadyRunning	If the session is already running.
UpscalerError	If pipeline creation fails.

wait(timeout=None)

Block until the session finishes or the timeout expires.

This method uses a local QEventLoop, so it is safe to call even if the host application already has a running event loop. It is useful in embedded mode.

Parameters:

Name	Type	Description	Default
timeout	Optional[float]	Maximum time to wait in seconds. None means wait indefinitely.	None

Returns:

Type	Description
bool	True if the session finished within the timeout, False if the timeout was reached.