simvx.core.resource_loader

Background resource loading – threaded loading with progress tracking.

Provides a Godot-style interface for background resource loading with status polling, suitable for loading screens and smooth level transitions.

Public API::

from simvx.core.resource_loader import ResourceLoader
from simvx.core import Resource

ResourceLoader.load_threaded_request(Resource("game.assets", "ship.png"))
ResourceLoader.load_threaded_request("textures/ship.png")
while True:
    status, progress = ResourceLoader.load_threaded_get_status()
    if status == "loaded":
        data = ResourceLoader.load_threaded_get()
        break
    update_loading_bar(progress)

The default loader reads any source (filesystem path, Resource, or Traversable) as raw bytes. Use :meth:register_loader to install custom type-dispatched loaders.

Module Contents

Classes

LoadStatus	Status of a background load request.
ResourceLoader	Singleton threaded resource loader with progress tracking.

Data

log
__all__
AssetSpec

API

simvx.core.resource_loader.log

‘getLogger(…)’

simvx.core.resource_loader.__all__

[‘ResourceLoader’, ‘LoadStatus’, ‘AssetSpec’]

simvx.core.resource_loader.AssetSpec

None

class simvx.core.resource_loader.LoadStatus

Bases: enum.StrEnum

Status of a background load request.

Initialization

Initialize self. See help(type(self)) for accurate signature.

IDLE

‘idle’

LOADING

‘loading’

LOADED

‘loaded’

ERROR

‘error’

CANCELLED

‘cancelled’

__new__(*values)

__add__()

__contains__()

__delattr__()

__dir__()

__eq__()

__format__()

__ge__()

__getattribute__()

__getitem__()

__getnewargs__()

__getstate__()

__gt__()

__hash__()

__iter__()

__le__()

__len__()

__lt__()

__mod__()

__mul__()

__ne__()

__reduce__()

__reduce_ex__()

__repr__()

__rmod__()

__rmul__()

__setattr__()

__sizeof__()

__str__()

__subclasshook__()

capitalize()

casefold()

center()

count()

encode()

endswith()

expandtabs()

find()

format()

format_map()

index()

isalnum()

isalpha()

isascii()

isdecimal()

isdigit()

isidentifier()

islower()

isnumeric()

isprintable()

isspace()

istitle()

isupper()

join()

ljust()

lower()

lstrip()

partition()

removeprefix()

removesuffix()

replace()

rfind()

rindex()

rjust()

rpartition()

rsplit()

rstrip()

split()

splitlines()

startswith()

strip()

swapcase()

title()

translate()

upper()

zfill()

__deepcopy__(memo)

__copy__()

name()

value()

class simvx.core.resource_loader.ResourceLoader

Singleton threaded resource loader with progress tracking.

Pool size and a default per-load timeout can be configured via

Meth:

configure before first use. Call :meth:reset first if the singleton has already been created.

Initialization

classmethod configure(*, max_workers: int = 2, default_timeout: float | None = None) → None

Set pool size and default per-load timeout.

Must be called before the singleton is first accessed. Call

Meth:

reset first to reconfigure an existing instance.

classmethod get() → simvx.core.resource_loader.ResourceLoader

Return the singleton instance.

classmethod reset()

Reset the singleton (for tests). Shuts down the thread pool.

register_loader(source_type: type, loader: collections.abc.Callable[[Any], Any]) → None

Register a custom loader keyed by source_type.

isinstance(spec, source_type) selects the loader. Tested in registration order, with the default file-bytes loader as fallback.

classmethod load_threaded_request(spec: simvx.core.resource_loader.AssetSpec, loader: collections.abc.Callable[[Any], Any] | None = None, *, timeout: float | None = None) → None

Start loading a resource in the background.

Args: spec: A filesystem path string / :class:~os.PathLike, a :class:~simvx.core.Resource, or an :class:importlib.resources.abc.Traversable. loader: Optional custom loader. Receives spec directly. If None, a registered type-loader is selected, falling back to a bytes reader. timeout: Optional per-request timeout in seconds. Overrides the configured default.

classmethod cancel(spec: simvx.core.resource_loader.AssetSpec) → bool

Cancel a pending load request. See class docstring for semantics.

classmethod load_threaded_get_status(spec: simvx.core.resource_loader.AssetSpec | None = None) → tuple[str, float]

Check the status of a background load.

If spec is None returns the most recent request’s status.

classmethod load_threaded_get(spec: simvx.core.resource_loader.AssetSpec | None = None, *, timeout: float | None = None) → Any

Get the loaded resource (blocks if still loading).

If spec is None returns the result of the most recent request.

classmethod is_loading() → bool

Check if any resources are currently loading.

classmethod get_progress() → float

Get overall loading progress across all pending requests (0.0 to 1.0).