pyglet.resource

Load application resources from a known path.

Loading resources by specifying relative paths to filenames is often problematic in Python, as the working directory is not necessarily the same directory as the application’s script files.

This module allows applications to specify a search path for resources. Relative paths are taken to be relative to the application’s __main__ module. ZIP files can appear on the path; they will be searched inside. The resource module also behaves as expected when applications are bundled using Freezers such as PyInstaller, Nuitka, py2app, etc..

In addition to providing file references (with the file() function), the resource module also contains convenience functions for loading images, textures, fonts, media and documents.

3rd party modules or packages not bound to a specific application should construct their own Loader instance and override the path to use the resources in the module’s directory.

Path format

The resource path path (see also Loader.__init__() and Loader.path()) is a list of locations to search for resources. Locations are searched in the order given in the path. If a location is not valid (for example, if the directory does not exist), it is skipped.

Locations in the path beginning with an “at” symbol (‘’@’’) specify Python packages. Other locations specify a ZIP archive or directory on the filesystem. Locations that are not absolute are assumed to be relative to the script home. Some examples:

# Search just the `res` directory, assumed to be located alongside the
# main script file.
path = ['res']

# Search the directory containing the module `levels.level1`, followed
# by the `res/images` directory.
path = ['@levels.level1', 'res/images']

Paths are always case-sensitive and forward slashes are always used as path separators, even in cases when the filesystem or platform does not do this. This avoids a common programmer error when porting applications between platforms.

The default path is ['.']. If you modify the path, you must call reindex().

exception ResourceNotFoundException

The named resource was not found on the search path.

__init__(name)

exception UndetectableShaderType

The type of the Shader source could not be identified.

__init__(name)

class FileLocation

Location on the filesystem.

__init__(filepath: str) → None: Create a location given a relative or absolute path.

open(filename: str, mode: str = 'rb') → IO

Open a file at this location.

Parameters:

name – The file name to open. Absolute paths are not supported. Relative paths are not supported by most locations (you should specify only a file name with no path component).
mode (str) – The file mode to open with. Only files opened on the filesystem make use of this parameter; others ignore it.

Return type:

IO

class Loader

Load program resource files from disk.

The loader contains a search path which can include filesystem directories, ZIP archives, URLs, and Python packages.

__init__( pathlist: list[str] | None = None, script_home: str | None = None, ) → None

Create a loader for the given path.

If no path is specified it defaults to ['.']; that is, just the program directory.

See the module documentation for details on the path format.

Parameters:

pathlist (list[str] | None) – List of locations to search for resources.
script_home (str | None) – Base location of relative files. Defaults to the result of get_script_home().

add_font(filename: str) → None

Add a font resource to the application.

Fonts not installed on the system must be added to pyglet before they can be used with font.load. Although the font is added with its filename using this function, fonts are always loaded by specifying their family name. For example:

resource.add_font('action_man.ttf')
action_man = font.load('Action Man')

Return type:: None

animation( name: str, flip_x: bool = False, flip_y: bool = False, rotate: Literal[0, 90, 180, 270, 360] = 0, border: int = 1, ) → Animation

Load an animation with optional transformation.

Animations loaded from the same source but with different transformations will use the same textures.

Parameters:

name (str) – Filename of the animation source to load.
flip_x (bool) – If True, the returned image will be flipped horizontally.
flip_y (bool) – If True, the returned image will be flipped vertically.
rotate (Literal[0, 90, 180, 270, 360]) – The returned image will be rotated clockwise by the given number of degrees (must be a multiple of 90).
border (int) – Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.

Return type:

Animation

attributed(name: str) → AbstractDocument

Load an attributed text document.

See pyglet.text.formats.attributed for details on this format.

Return type:: AbstractDocument

file(name: str, mode: str = 'rb') → BytesIO | StringIO | IO

Load a file-like object.

Parameters:

name (str) – Filename of the resource to load.
mode (str) – Combination of r, w, a, b and t characters with the meaning as for the builtin open function.

Return type:

BytesIO | StringIO | IO

get_cached_animation_names() → list[str]

Get a list of animation filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

get_cached_image_names() → list[str]

Get a list of image filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

get_cached_texture_names() → list[str]

Get a list of texture filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

get_texture_bins() → list[TextureBin]

Get a list of texture bins in use.

This is useful for debugging and profiling only.

Return type:: list[TextureBin]

html(name: str) → AbstractDocument

Load an HTML document.

Return type:: AbstractDocument

image( name: str, flip_x: bool = False, flip_y: bool = False, rotate: Literal[0, 90, 180, 270, 360] = 0, atlas: bool = True, border: int = 1, ) → Texture | TextureRegion

Load an image with optional transformation.

This is similar to texture, except the resulting image will be packed into a TextureBin (TextureAtlas) if it is an appropriate size for packing. This is more efficient than loading images into separate textures.

Parameters:

name (str) – The filename of the image source to load.
flip_x (bool) – If True, the returned image will be flipped horizontally.
flip_y (bool) – If True, the returned image will be flipped vertically.
rotate (Literal[0, 90, 180, 270, 360]) – The returned image will be rotated clockwise by the given number of degrees (a multiple of 90).
atlas (bool) – If True, the image will be loaded into an atlas managed by pyglet. If atlas loading is not appropriate for specific texturing reasons (e.g. border control is required) then set to False.
border (int) – Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.

Return type:

Texture | TextureRegion

Note

When using flip_x/y or rotate, the actual image data is not modified. Instead, the texture coordinates are manipulated to produce the desired result.

location( filename: str, ) → FileLocation | URLLocation | ZIPLocation

Get the location of a resource.

This method is useful for opening files referenced from a resource. For example, an HTML file loaded as a resource might reference some images. These images should be located relative to the HTML file, not looked up individually in the loader’s path.

Return type:: FileLocation | URLLocation | ZIPLocation

media(name: str, streaming: bool = True) → Source

Load a sound or video resource.

The meaning of streaming is as for load(). Compressed sources cannot be streamed (that is, video and compressed audio cannot be streamed from a ZIP archive).

Parameters:

name (str) – Filename of the media source to load.
streaming (bool) – True if the source should be streamed from disk, False if it should be entirely decoded into memory immediately.

Return type:

Source

reindex()

Refresh the file index.

You must call this method if resource.path is changed, or the filesystem layout changes.

scene(name: str) → Scene

Load a 3D Scene.

Return type:: Scene

shader(name: str, shader_type: str | None = None) → Shader

Load a Shader object.

Parameters:

name (str) – Filename of the Shader source to load.
shader_type (str | None) – A hint for the type of shader, such as ‘vertex’, ‘fragment’, etc. Not required if your shader has a standard file extension, such as .vert, .frag, etc..

Return type:

Shader

text(name: str) → AbstractDocument

Load a plain text document.

Return type:: AbstractDocument

texture(name: str) → Texture

Load an image as a single OpenGL texture.

Return type:: Texture

class Location

Abstract resource location.

Given a location, a file can be loaded from that location with the open() method. This provides a convenient way to specify a path to load files from, even when that path does not reside on the filesystem.

open( name: str, mode: str = 'rb', ) → BytesIO | StringIO | IO

Open a file at this location.

Parameters:

name (str) – The file name to open. Absolute paths are not supported. Relative paths are not supported by most locations (you should specify only a file name with no path component).
mode (str) – The file mode to open with. Only files opened on the filesystem make use of this parameter; others ignore it.

Return type:

BytesIO | StringIO | IO

class URLLocation

Location on the network.

This class uses the urllib module to open files on the network, given a base URL.

__init__(base_url: str) → None: Create a location given a base URL.

open(filename: str, mode: str = '') → IO

Open a remote file.

Parameters:

filename (str) – The name of the remote resource to open.
mode (str) – Unused, as the mode is determined by the remote server.

Return type:

IO

class ZIPLocation

Location within a ZIP file.

__init__(zipfileobj: ZipFile, directory: str | None)

Create a location given an open ZIP file and a path within that file.

Parameters:

zipfileobj (ZipFile) – An open ZIP file from the zipfile module.
directory (str | None) – A path within that ZIP file. Can be empty to specify files at the top level of the ZIP file.

open(filename: str, mode='rb') → BytesIO | StringIO

Open a file from inside the ZipFile.

Parameters:

filename (str) – The filename to open.
mode – Valid modes are ‘r’ and ‘rb’.

Return type:

BytesIO | StringIO

add_font(filename: str) → None

Add a font resource to the application.

Fonts not installed on the system must be added to pyglet before they can be used with font.load. Although the font is added with its filename using this function, fonts are always loaded by specifying their family name. For example:

resource.add_font('action_man.ttf')
action_man = font.load('Action Man')

Return type:: None

animation( name: str, flip_x: bool = False, flip_y: bool = False, rotate: Literal[0, 90, 180, 270, 360] = 0, border: int = 1, ) → Animation

Load an animation with optional transformation.

Animations loaded from the same source but with different transformations will use the same textures.

Parameters:

name (str) – Filename of the animation source to load.
flip_x (bool) – If True, the returned image will be flipped horizontally.
flip_y (bool) – If True, the returned image will be flipped vertically.
rotate (Literal[0, 90, 180, 270, 360]) – The returned image will be rotated clockwise by the given number of degrees (must be a multiple of 90).
border (int) – Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.

Return type:

Animation

attributed(name: str) → AbstractDocument

Load an attributed text document.

See pyglet.text.formats.attributed for details on this format.

Return type:: AbstractDocument

file(name: str, mode: str = 'rb') → BytesIO | StringIO | IO

Load a file-like object.

Parameters:

name (str) – Filename of the resource to load.
mode (str) – Combination of r, w, a, b and t characters with the meaning as for the builtin open function.

Return type:

BytesIO | StringIO | IO

get_cached_animation_names() → list[str]

Get a list of animation filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

get_cached_image_names() → list[str]

Get a list of image filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

get_cached_texture_names() → list[str]

Get a list of texture filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

get_data_path(name: str) → str

Get a directory to save user data.

For a Posix or Linux based system many distributions have a separate directory to store user data for a specific application and this function returns the path to that location.

On Linux, a directory name in the user’s data directory is returned (usually under ~/.local/share).

On Windows (including under Cygwin) the name directory in the user’s Application Settings directory is returned.

On Mac OS X the name directory under ~/Library/Application Support is returned. :rtype: str

Note

This function does not perform any directory creation. Users should use os.path.exists and os.makedirs to construct the directory if desired.

get_script_home() → str

Get the directory containing the program entry module.

For ordinary Python scripts, this is the directory containing the __main__ module. For applications that have been bundled with PyInstaller, Nuitka, etc., this may be the bundle path or a temporary directory.

If none of the above cases apply and the file for __main__ cannot be determined the working directory is returned.

When the script is being run by a Python profiler, this function may return the directory where the profiler is running instead of the directory of the real script. To work around this behaviour the full path to the real script can be specified in pyglet.resource.path.

Return type:: str

get_settings_path(name: str) → str

Get a directory path to save user preferences.

Different platforms have different conventions for where to save user preferences and settings. This function implements those conventions as described below, and returns a fully formed path.

On Linux, a directory name in the user’s configuration directory is returned (usually under ~/.config).

On Windows (including under Cygwin) the name directory in the user’s Application Settings directory is returned.

On Mac OS X the name directory under ~/Library/Application Support is returned. :rtype: str

Note

This function does not perform any directory creation. Users should use os.path.exists and os.makedirs to construct the directory if desired.

get_texture_bins() → list[TextureBin]

Get a list of texture bins in use.

This is useful for debugging and profiling only.

Return type:: list[TextureBin]

html(name: str) → AbstractDocument

Load an HTML document.

Return type:: AbstractDocument

image( name: str, flip_x: bool = False, flip_y: bool = False, rotate: Literal[0, 90, 180, 270, 360] = 0, atlas: bool = True, border: int = 1, ) → Texture | TextureRegion

Load an image with optional transformation.

This is similar to texture, except the resulting image will be packed into a TextureBin (TextureAtlas) if it is an appropriate size for packing. This is more efficient than loading images into separate textures.

Parameters:

name (str) – The filename of the image source to load.
flip_x (bool) – If True, the returned image will be flipped horizontally.
flip_y (bool) – If True, the returned image will be flipped vertically.
rotate (Literal[0, 90, 180, 270, 360]) – The returned image will be rotated clockwise by the given number of degrees (a multiple of 90).
atlas (bool) – If True, the image will be loaded into an atlas managed by pyglet. If atlas loading is not appropriate for specific texturing reasons (e.g. border control is required) then set to False.
border (int) – Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.

Return type:

Texture | TextureRegion

Note

When using flip_x/y or rotate, the actual image data is not modified. Instead, the texture coordinates are manipulated to produce the desired result.

location( filename: str, ) → FileLocation | URLLocation | ZIPLocation

Get the location of a resource.

This method is useful for opening files referenced from a resource. For example, an HTML file loaded as a resource might reference some images. These images should be located relative to the HTML file, not looked up individually in the loader’s path.

Return type:: FileLocation | URLLocation | ZIPLocation

media(name: str, streaming: bool = True) → Source

Load a sound or video resource.

The meaning of streaming is as for load(). Compressed sources cannot be streamed (that is, video and compressed audio cannot be streamed from a ZIP archive).

Parameters:

name (str) – Filename of the media source to load.
streaming (bool) – True if the source should be streamed from disk, False if it should be entirely decoded into memory immediately.

Return type:

Source

reindex()

Refresh the file index.

You must call this method if resource.path is changed, or the filesystem layout changes.

scene(name: str) → Scene

Load a 3D Scene.

Return type:: Scene

shader(name: str, shader_type: str | None = None) → Shader

Load a Shader object.

Parameters:

name (str) – Filename of the Shader source to load.
shader_type (str | None) – A hint for the type of shader, such as ‘vertex’, ‘fragment’, etc. Not required if your shader has a standard file extension, such as .vert, .frag, etc..

Return type:

Shader

text(name: str) → AbstractDocument

Load a plain text document.

Return type:: AbstractDocument

texture(name: str) → Texture

Load an image as a single OpenGL texture.

Return type:: Texture

path = ['.']

Default resource search path.

Locations in the search path are searched in order and are always case-sensitive. After changing the path you must call reindex.

See the module documentation for details on the path format.

Type:: list of str

Functions

reindex()

Refresh the file index.

You must call this method if resource.path is changed, or the filesystem layout changes.

file(name: str, mode: str = 'rb') → BytesIO | StringIO | IO

Load a file-like object.

Parameters:

name (str) – Filename of the resource to load.
mode (str) – Combination of r, w, a, b and t characters with the meaning as for the builtin open function.

Return type:

BytesIO | StringIO | IO

location( filename: str, ) → FileLocation | URLLocation | ZIPLocation

Get the location of a resource.

This method is useful for opening files referenced from a resource. For example, an HTML file loaded as a resource might reference some images. These images should be located relative to the HTML file, not looked up individually in the loader’s path.

Return type:: FileLocation | URLLocation | ZIPLocation

add_font(filename: str) → None

Add a font resource to the application.

Fonts not installed on the system must be added to pyglet before they can be used with font.load. Although the font is added with its filename using this function, fonts are always loaded by specifying their family name. For example:

resource.add_font('action_man.ttf')
action_man = font.load('Action Man')

Return type:: None

image( name: str, flip_x: bool = False, flip_y: bool = False, rotate: Literal[0, 90, 180, 270, 360] = 0, atlas: bool = True, border: int = 1, ) → Texture | TextureRegion

Load an image with optional transformation.

This is similar to texture, except the resulting image will be packed into a TextureBin (TextureAtlas) if it is an appropriate size for packing. This is more efficient than loading images into separate textures.

Parameters:

name (str) – The filename of the image source to load.
flip_x (bool) – If True, the returned image will be flipped horizontally.
flip_y (bool) – If True, the returned image will be flipped vertically.
rotate (Literal[0, 90, 180, 270, 360]) – The returned image will be rotated clockwise by the given number of degrees (a multiple of 90).
atlas (bool) – If True, the image will be loaded into an atlas managed by pyglet. If atlas loading is not appropriate for specific texturing reasons (e.g. border control is required) then set to False.
border (int) – Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.

Return type:

Texture | TextureRegion

Note

When using flip_x/y or rotate, the actual image data is not modified. Instead, the texture coordinates are manipulated to produce the desired result.

animation( name: str, flip_x: bool = False, flip_y: bool = False, rotate: Literal[0, 90, 180, 270, 360] = 0, border: int = 1, ) → Animation

Load an animation with optional transformation.

Animations loaded from the same source but with different transformations will use the same textures.

Parameters:

name (str) – Filename of the animation source to load.
flip_x (bool) – If True, the returned image will be flipped horizontally.
flip_y (bool) – If True, the returned image will be flipped vertically.
rotate (Literal[0, 90, 180, 270, 360]) – The returned image will be rotated clockwise by the given number of degrees (must be a multiple of 90).
border (int) – Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.

Return type:

Animation

texture(name: str) → Texture

Load an image as a single OpenGL texture.

Return type:: Texture

media(name: str, streaming: bool = True) → Source

Load a sound or video resource.

The meaning of streaming is as for load(). Compressed sources cannot be streamed (that is, video and compressed audio cannot be streamed from a ZIP archive).

Parameters:

name (str) – Filename of the media source to load.
streaming (bool) – True if the source should be streamed from disk, False if it should be entirely decoded into memory immediately.

Return type:

Source

shader(name: str, shader_type: str | None = None) → Shader

Load a Shader object.

Parameters:

name (str) – Filename of the Shader source to load.
shader_type (str | None) – A hint for the type of shader, such as ‘vertex’, ‘fragment’, etc. Not required if your shader has a standard file extension, such as .vert, .frag, etc..

Return type:

Shader

html(name: str) → AbstractDocument

Load an HTML document.

Return type:: AbstractDocument

attributed(name: str) → AbstractDocument

Load an attributed text document.

See pyglet.text.formats.attributed for details on this format.

Return type:: AbstractDocument

text(name: str) → AbstractDocument

Load a plain text document.

Return type:: AbstractDocument

get_cached_image_names() → list[str]

Get a list of image filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

get_cached_animation_names() → list[str]

Get a list of animation filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

get_texture_bins() → list[TextureBin]

Get a list of texture bins in use.

This is useful for debugging and profiling only.

Return type:: list[TextureBin]

get_cached_texture_names() → list[str]

Get a list of texture filenames that have been cached.

This is useful for debugging and profiling only.

Return type:: list[str]

Exceptions

class ResourceNotFoundException

The named resource was not found on the search path.

__init__(name)

class UndetectableShaderType

The type of the Shader source could not be identified.

__init__(name)