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 py2exe or py2app.

As well as 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 ampersand (‘’@’’ 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.

Note

Since pyglet 1.1

Classes

FileLocation Location on the filesystem.
Loader Load program resource files from disk.
Location Abstract resource location.
URLLocation Location on the network.
ZIPLocation Location within a ZIP file.

Exceptions

ResourceNotFoundException(name) The named resource was not found on the search path.

Functions

get_script_home() Get the directory containing the program entry module.
get_settings_path(name) Get a directory to save user preferences.

Variables

add_font = <bound method _DefaultLoader.add_font of <pyglet.resource._DefaultLoader object at 0x7f26c1b91710>>

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, it is loaded by specifying its family name. For example:

resource.add_font('action_man.ttf')
action_man = font.load('Action Man')
Parameters:name (str) – Filename of the font resource to add.
animation = <bound method _DefaultLoader.animation of <pyglet.resource._DefaultLoader object at 0x7f26c1b91710>>

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 (int) – The returned image will be rotated clockwise by the given number of degrees (a multiple of 90).
Return type:

Animation

attributed = <bound method _DefaultLoader.attributed of <pyglet.resource._DefaultLoader object at 0x7f26c1b91710>>

Load an attributed text document.

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

Parameters:name (str) – Filename of the attribute text resource to load.
Return type:FormattedDocument
file = <bound method _DefaultLoader.file of <pyglet.resource._DefaultLoader object at 0x7f26c1b91710>>

Load a resource.

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:

file object

get_cached_animation_names = <bound method _DefaultLoader.get_cached_animation_names of <pyglet.resource._DefaultLoader object at 0x7f26c1b91710>>

Get a list of animation filenames that have been cached.

This is useful for debugging and profiling only.

Return type:list
Returns:List of str
get_cached_image_names = <bound method _DefaultLoader.get_cached_image_names of <pyglet.resource._DefaultLoader object at 0x7f26c1b91710>>

Get a list of image filenames that have been cached.

This is useful for debugging and profiling only.

Return type:list
Returns:List of str
get_cached_texture_names = <bound method _DefaultLoader.get_cached_texture_names of <pyglet.resource._DefaultLoader object at 0x7f26c1b91710>>

Get the names of textures currently cached.

Return type:list of str
get_texture_bins = <bound method _DefaultLoader.get_texture_bins of <pyglet.resource._DefaultLoader object at 0x7f26c1b91710>>

Get a list of texture bins in use.

This is useful for debugging and profiling only.

Return type:list
Returns:List of TextureBin
html = <bound method _DefaultLoader.html of <pyglet.resource._DefaultLoader object at 0x7f26c1b91710>>

Load an HTML document.

Parameters:name (str) – Filename of the HTML resource to load.
Return type:FormattedDocument
image = <bound method _DefaultLoader.image of <pyglet.resource._DefaultLoader object at 0x7f26c1b91710>>

Load an image with optional transformation.

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

Parameters:
  • name (str) – 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 (int) – 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 this argument to False.
Return type:

Texture

Returns:

A complete texture if the image is large or not in an atlas, otherwise a TextureRegion of a texture atlas.

location = <bound method _DefaultLoader.location of <pyglet.resource._DefaultLoader object at 0x7f26c1b91710>>

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.

Parameters:name (str) – Filename of the resource to locate.
Return type:Location
media = <bound method _DefaultLoader.media of <pyglet.resource._DefaultLoader object at 0x7f26c1b91710>>

Load a sound or video resource.

The meaning of streaming is as for media.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:

media.Source

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
reindex = <bound method _DefaultLoader.reindex of <pyglet.resource._DefaultLoader object at 0x7f26c1b91710>>

Refresh the file index.

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

text = <bound method _DefaultLoader.text of <pyglet.resource._DefaultLoader object at 0x7f26c1b91710>>

Load a plain text document.

Parameters:name (str) – Filename of the plain text resource to load.
Return type:UnformattedDocument
texture = <bound method _DefaultLoader.texture of <pyglet.resource._DefaultLoader object at 0x7f26c1b91710>>

Load a texture.

The named image will be loaded as a single OpenGL texture. If the dimensions of the image are not powers of 2 a TextureRegion will be returned.

Parameters:name (str) – Filename of the image resource to load.
Return type:Texture

Notes

Defined

  • os
  • pyglet
  • sys
  • weakref
  • zipfile

Table Of Contents

Previous topic

load Function

Next topic

FileLocation Class