Assets

PursuedPyBear features a background, eager-loading asset system. The first time an asset is referenced, PPB starts reading and parsing it in a background thread.

The data is kept in memory for the lifetime of the Asset. When nothing is referencing it any more, the Python garbage collector will clean up the object and its data.

Asset instances are consolidated or “interned”: if you ask for the same asset twice, you’ll get the same instance back. Note that this is a performance optimization and should not be relied upon (do not do things like asset1 is asset2).

General Asset Interface

All assets inherit from Asset. It handles the background loading system and the data logistics.

class ppb.assetlib.Asset(name)[source]

A resource to be loaded from the filesystem and used.

Meant to be subclassed, but in specific ways.

file_missing()

Called if the file could not be found, to produce a default value.

Subclasses may want to define this.

Called in the background thread.

free()

Called by __del__() if the data was loaded.

Meant to free any resources held outside of Python.

load(timeout: float = None)

Gets the parsed data.

Will block until the data is loaded.

is_loaded()

Returns if the data has been loaded and parsed.

background_parse(data: bytes)[source]

Takes the data loaded from the file and returns the parsed data.

Subclasses probably want to override this.

Called in the background thread.

Subclassing

Asset makes specific assumptions and is only suitable for loading file-based assets. These make the consolidation, background-loading, and other aspects of Asset possible.

You should really only implement three methods:

  • background_parse(): This is called with the loaded data and returns an object constructed from that data. This is called from a background thread and its return value is accessible from load()

    This is an excellent place for decompression, data parsing, and other tasks needed to turn a pile of bytes into a useful data structure.

  • file_missing(): This is called if the asset is not found. Defining this method suppresses load() from raising a FileNotFoundError and will instead call this, and load() will return what this returns.

    For example, ppb.Image uses this to produce the default square.

  • free(): This is to clean up any resources that would not normally be cleaned up by Python’s garbage collector. If you are integrating external libraries, you may need this.

Concrete Assets

While Asset can load anything, it only produces bytes, limiting its usefulness. Most likely, you want a concrete subclass that does something more useful.

class ppb.Image(name)[source]

Loads an image file and parses it into a form usable by the renderer.

class ppb.Sound(name)[source]

Loads and decodes an image file. A variety of formats are supported.

Asset Proxies and Virtual Assets

Asset Proxies and Virtual Assets are assets that implement the interface but either delegate to other Assets or are completely synthesized.

For example, ppb.features.animation.Animation is an asset proxy that delegates to actual ppb.Image instances.

class ppb.assetlib.AbstractAsset[source]

The asset interface.

This defines the common interface for virtual assets, proxy assets, and real/file assets.

is_loaded()[source]

Returns if the data is ready now or if load() will block.

abstract load(timeout: Optional[float] = None)[source]

Get the data of this asset, in the appropriate form.

not_found_message = ''

Can be overridden on child classes to add an additional message to show after “File not found: %r.”. See Image.not_found_message for an example.

class ppb.Rectangle(red: int, green: int, blue: int, aspect_ratio: Union[ppb.assets.AspectRatio, Tuple[Union[float, int], Union[float, int]]] = AspectRatio(width=1, height=1))[source]

A rectangle image of a single color.

class ppb.Ellipse(red: int, green: int, blue: int, aspect_ratio: Union[ppb.assets.AspectRatio, Tuple[Union[float, int], Union[float, int]]] = AspectRatio(width=1, height=1))[source]

An ellipse image of a single color.

class ppb.Triangle(red: int, green: int, blue: int, aspect_ratio: Union[ppb.assets.AspectRatio, Tuple[Union[float, int], Union[float, int]]] = AspectRatio(width=1, height=1))[source]

A triangle image of a single color.

class ppb.Circle(r, g, b)[source]

A convenience constructor for Ellipse that is a perfect circle.

class ppb.Square(r, g, b)[source]

A constructor for Rectangle that produces a square image.