simvx.core.assets.handle

Load handles: observable progress + completion for one or many loads.

A :class:Handle represents a single in-flight load. Consumers can:

  • poll handle.state / handle.progress / handle.is_done

  • read handle.error (without raising) if a failure has occurred

  • call handle.result(timeout=...) to block until done (raises on failure)

  • connect to handle.completed (a Signal) to observe finish on the main thread, ≤1 frame after the worker actually finished

A :class:BatchHandle aggregates many handles, exposing combined progress, an item_completed signal per child, and a single completed signal when all children are done.

Module Contents

Classes

Handle

Observable handle for a single asset load.

BatchHandle

Aggregate of multiple :class:Handle objects.

Data

__all__

PENDING

LOADING

LOADED

FAILED

CANCELLED

API

simvx.core.assets.handle.__all__

[‘Handle’, ‘BatchHandle’, ‘PENDING’, ‘LOADING’, ‘LOADED’, ‘FAILED’, ‘CANCELLED’]

simvx.core.assets.handle.PENDING: Final

‘pending’

simvx.core.assets.handle.LOADING: Final

‘loading’

simvx.core.assets.handle.LOADED: Final

‘loaded’

simvx.core.assets.handle.FAILED: Final

‘failed’

simvx.core.assets.handle.CANCELLED: Final

‘cancelled’

class simvx.core.assets.handle.Handle(uri: str)[source]

Observable handle for a single asset load.

Created by :meth:AssetServer.load. Most fields are written by the worker thread and the server’s main-thread flush; user code reads them via the documented properties.

Initialization

property state: str[source]

One of "pending" | "loading" | "loaded" | "failed" | "cancelled".

property progress: float[source]

0.0–1.0. Real for HTTP loads; 0→1 in one tick for pkg/file/mem.

property error: BaseException | None[source]

The exception that caused failure, if any. Never raises.

property is_done: bool[source]

True once the handle has reached a terminal state.

cancel() → None[source]

Request cancellation. The worker stops on its next progress check.

result(timeout: float | None = None) → Any[source]

Block until done; return the loaded value or re-raise on failure.

Note: blocking on a load whose completion is dispatched via the SceneTree’s per-frame flush requires the flush to happen on another thread. In a synchronous test, prefer waiting via the completed Signal or by running the server’s flush manually.

__repr__() → str[source]
class simvx.core.assets.handle.BatchHandle(handles: list[simvx.core.assets.handle.Handle])[source]

Aggregate of multiple :class:Handle objects.

Emits :attr:item_completed once per child as it finishes (any terminal state) and :attr:completed once when all children are done. Drives a loading-screen progress bar via :attr:progress.

Initialization

property total: int[source]
property completed_count: int[source]
property failed_count: int[source]
property cancelled_count: int[source]
property progress: float[source]

Sum of per-handle progress / total. Partial credit for in-flight HTTP.

property is_done: bool[source]
cancel() → None[source]

Cancel every child that has not yet finished.

results(timeout: float | None = None) → dict[str, Any][source]

Block until all children done; return {uri: value}.

Raises the first child’s error if any failed.

__repr__() → str[source]