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, py2exe, 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()
.
New in version 1.1.
- exception ResourceNotFoundException(name)
The named resource was not found on the search path.
- exception UndetectableShaderType(name)
The type of the Shader source could not be identified.
- class FileLocation(filepath)
Location on the filesystem.
- open(filename, mode='rb')
Open a file at this location.
- Parameters
- filenamestr
The filename to open. Absolute paths are not supported. Relative paths are not supported by most locations (you should specify only a filename with no path component).
- modestr
The file mode to open with. Only files opened on the filesystem make use of this parameter; others ignore it.
- Return type
file object
- class Loader(path=None, script_home=None)
Load program resource files from disk.
The loader contains a search path which can include filesystem directories, ZIP archives and Python packages.
- Ivariables
- pathlist of str
List of search locations. After modifying the path you must call the reindex method.
- script_homestr
Base resource location, defaulting to the location of the application script.
- add_font(name)
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
- namestr
Filename of the font resource to add.
- animation(name, flip_x=False, flip_y=False, rotate=0, border=1)
Load an animation with optional transformation.
Animations loaded from the same source but with different transformations will use the same textures.
- Parameters
- namestr
Filename of the animation source to load.
- flip_xbool
If True, the returned image will be flipped horizontally.
- flip_ybool
If True, the returned image will be flipped vertically.
- rotateint
The returned image will be rotated clockwise by the given number of degrees (a multiple of 90).
- borderint
Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.
- Return type
Animation
- attributed(name)
Load an attributed text document.
See pyglet.text.formats.attributed for details on this format.
- Parameters
- namestr
Filename of the attribute text resource to load.
- Return type
FormattedDocument
- file(name, mode='rb')
Load a resource.
- Parameters
- namestr
Filename of the resource to load.
- modestr
Combination of
r
,w
,a
,b
andt
characters with the meaning as for the builtinopen
function.
- Return type
file object
- get_cached_animation_names()
Get a list of animation filenames that have been cached.
This is useful for debugging and profiling only.
- Return type
- Returns
List of str
- get_cached_image_names()
Get a list of image filenames that have been cached.
This is useful for debugging and profiling only.
- Return type
- Returns
List of str
- get_texture_bins()
Get a list of texture bins in use.
This is useful for debugging and profiling only.
- Return type
- Returns
List of
TextureBin
- html(name)
Load an HTML document.
- Parameters
- namestr
Filename of the HTML resource to load.
- Return type
FormattedDocument
- image(name, flip_x=False, flip_y=False, rotate=0, atlas=True, border=1)
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
- namestr
Filename of the image source to load.
- flip_xbool
If True, the returned image will be flipped horizontally.
- flip_ybool
If True, the returned image will be flipped vertically.
- rotateint
The returned image will be rotated clockwise by the given number of degrees (a multiple of 90).
- atlasbool
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.
- borderint
Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.
- 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(name)
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
- namestr
Filename of the resource to locate.
- Return type
Location
- media(name, streaming=True)
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
- namestr
Filename of the media source to load.
- streamingbool
True if the source should be streamed from disk, False if it should be entirely decoded into memory immediately.
- Return type
media.Source
- model(name, batch=None)
Load a 3D model.
- Parameters
- namestr
Filename of the 3D model to load.
- batchBatch or None
An optional Batch instance to add this model to.
- Return type
Model
- reindex()
Refresh the file index.
You must call this method if path is changed or the filesystem layout changes.
- shader(name, shader_type=None)
Load a Shader object.
- Parameters
- namestr
Filename of the Shader source to load.
- shader_typestr
A hint for the type of shader, such as ‘vertex’, ‘fragment’, etc. Not required if your shader has a standard file extension.
- Return type
A compiled Shader object.
- text(name)
Load a plain text document.
- Parameters
- namestr
Filename of the plain text resource to load.
- Return type
UnformattedDocument
- texture(name)
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
- namestr
Filename of the image resource to load.
- 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, and not necessarily have that path reside on the filesystem.
- open(filename, mode='rb')
Open a file at this location.
- Parameters
- filenamestr
The filename to open. Absolute paths are not supported. Relative paths are not supported by most locations (you should specify only a filename with no path component).
- modestr
The file mode to open with. Only files opened on the filesystem make use of this parameter; others ignore it.
- Return type
file object
- class URLLocation(base_url)
Location on the network.
This class uses the
urlparse
andurllib2
modules to open files on the network given a URL.- open(filename, mode='rb')
Open a file at this location.
- Parameters
- filenamestr
The filename to open. Absolute paths are not supported. Relative paths are not supported by most locations (you should specify only a filename with no path component).
- modestr
The file mode to open with. Only files opened on the filesystem make use of this parameter; others ignore it.
- Return type
file object
- class ZIPLocation(zip, dir)
Location within a ZIP file.
- open(filename, mode='rb')
Open a file at this location.
- Parameters
- filenamestr
The filename to open. Absolute paths are not supported. Relative paths are not supported by most locations (you should specify only a filename with no path component).
- modestr
The file mode to open with. Only files opened on the filesystem make use of this parameter; others ignore it.
- Return type
file object
- add_font(name)
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
- namestr
Filename of the font resource to add.
- animation(name, flip_x=False, flip_y=False, rotate=0, border=1)
Load an animation with optional transformation.
Animations loaded from the same source but with different transformations will use the same textures.
- Parameters
- namestr
Filename of the animation source to load.
- flip_xbool
If True, the returned image will be flipped horizontally.
- flip_ybool
If True, the returned image will be flipped vertically.
- rotateint
The returned image will be rotated clockwise by the given number of degrees (a multiple of 90).
- borderint
Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.
- Return type
Animation
- attributed(name)
Load an attributed text document.
See pyglet.text.formats.attributed for details on this format.
- Parameters
- namestr
Filename of the attribute text resource to load.
- Return type
FormattedDocument
- file(name, mode='rb')
Load a resource.
- Parameters
- namestr
Filename of the resource to load.
- modestr
Combination of
r
,w
,a
,b
andt
characters with the meaning as for the builtinopen
function.
- Return type
file object
- get_cached_animation_names()
Get a list of animation filenames that have been cached.
This is useful for debugging and profiling only.
- Return type
- Returns
List of str
- get_cached_image_names()
Get a list of image filenames that have been cached.
This is useful for debugging and profiling only.
- Return type
- Returns
List of str
- get_data_path(name)
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. Note that the returned path may not exist: applications should use
os.makedirs
to construct it if desired.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.- Parameters
- namestr
The name of the application.
- Return type
- get_script_home()
Get the directory containing the program entry module.
For ordinary Python scripts, this is the directory containing the
__main__
module. For executables created with py2exe the result is the directory containing the running executable file. For OS X bundles created using Py2App the result is the Resources directory within the running bundle.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 workaround this behaviour the full path to the real script can be specified in
pyglet.resource.path
.- Return type
- get_settings_path(name)
Get a directory to save user preferences.
Different platforms have different conventions for where to save user preferences, saved games, and settings. This function implements those conventions. Note that the returned path may not exist: applications should use
os.makedirs
to construct it if desired.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.- Parameters
- namestr
The name of the application.
- Return type
- get_texture_bins()
Get a list of texture bins in use.
This is useful for debugging and profiling only.
- Return type
- Returns
List of
TextureBin
- html(name)
Load an HTML document.
- Parameters
- namestr
Filename of the HTML resource to load.
- Return type
FormattedDocument
- image(name, flip_x=False, flip_y=False, rotate=0, atlas=True, border=1)
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
- namestr
Filename of the image source to load.
- flip_xbool
If True, the returned image will be flipped horizontally.
- flip_ybool
If True, the returned image will be flipped vertically.
- rotateint
The returned image will be rotated clockwise by the given number of degrees (a multiple of 90).
- atlasbool
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.
- borderint
Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.
- 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(name)
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
- namestr
Filename of the resource to locate.
- Return type
Location
- media(name, streaming=True)
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
- namestr
Filename of the media source to load.
- streamingbool
True if the source should be streamed from disk, False if it should be entirely decoded into memory immediately.
- Return type
media.Source
- model(name, batch=None)
Load a 3D model.
- Parameters
- namestr
Filename of the 3D model to load.
- batchBatch or None
An optional Batch instance to add this model to.
- Return type
Model
- reindex()
Refresh the file index.
You must call this method if path is changed or the filesystem layout changes.
- shader(name, shader_type=None)
Load a Shader object.
- Parameters
- namestr
Filename of the Shader source to load.
- shader_typestr
A hint for the type of shader, such as ‘vertex’, ‘fragment’, etc. Not required if your shader has a standard file extension.
- Return type
A compiled Shader object.
- text(name)
Load a plain text document.
- Parameters
- namestr
Filename of the plain text resource to load.
- Return type
UnformattedDocument
- texture(name)
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
- namestr
Filename of the image resource to load.
- 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.
Functions
- reindex()
Refresh the file index.
You must call this method if path is changed or the filesystem layout changes.
- file(name, mode='rb')
Load a resource.
- Parameters
- namestr
Filename of the resource to load.
- modestr
Combination of
r
,w
,a
,b
andt
characters with the meaning as for the builtinopen
function.
- Return type
file object
- location(name)
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
- namestr
Filename of the resource to locate.
- Return type
Location
- add_font(name)
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
- namestr
Filename of the font resource to add.
- image(name, flip_x=False, flip_y=False, rotate=0, atlas=True, border=1)
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
- namestr
Filename of the image source to load.
- flip_xbool
If True, the returned image will be flipped horizontally.
- flip_ybool
If True, the returned image will be flipped vertically.
- rotateint
The returned image will be rotated clockwise by the given number of degrees (a multiple of 90).
- atlasbool
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.
- borderint
Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.
- Return type
Texture
- Returns
A complete texture if the image is large or not in an atlas, otherwise a
TextureRegion
of a texture atlas.
- animation(name, flip_x=False, flip_y=False, rotate=0, border=1)
Load an animation with optional transformation.
Animations loaded from the same source but with different transformations will use the same textures.
- Parameters
- namestr
Filename of the animation source to load.
- flip_xbool
If True, the returned image will be flipped horizontally.
- flip_ybool
If True, the returned image will be flipped vertically.
- rotateint
The returned image will be rotated clockwise by the given number of degrees (a multiple of 90).
- borderint
Leaves specified pixels of blank space around each image in an atlas, which may help reduce texture bleeding.
- Return type
Animation
- texture(name)
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
- namestr
Filename of the image resource to load.
- Return type
Texture
- media(name, streaming=True)
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
- namestr
Filename of the media source to load.
- streamingbool
True if the source should be streamed from disk, False if it should be entirely decoded into memory immediately.
- Return type
media.Source
- model(name, batch=None)
Load a 3D model.
- Parameters
- namestr
Filename of the 3D model to load.
- batchBatch or None
An optional Batch instance to add this model to.
- Return type
Model
- shader(name, shader_type=None)
Load a Shader object.
- Parameters
- namestr
Filename of the Shader source to load.
- shader_typestr
A hint for the type of shader, such as ‘vertex’, ‘fragment’, etc. Not required if your shader has a standard file extension.
- Return type
A compiled Shader object.
- html(name)
Load an HTML document.
- Parameters
- namestr
Filename of the HTML resource to load.
- Return type
FormattedDocument
- attributed(name)
Load an attributed text document.
See pyglet.text.formats.attributed for details on this format.
- Parameters
- namestr
Filename of the attribute text resource to load.
- Return type
FormattedDocument
- text(name)
Load a plain text document.
- Parameters
- namestr
Filename of the plain text resource to load.
- Return type
UnformattedDocument
- get_cached_image_names()
Get a list of image filenames that have been cached.
This is useful for debugging and profiling only.
- Return type
- Returns
List of str
- get_cached_animation_names()
Get a list of animation filenames that have been cached.
This is useful for debugging and profiling only.
- Return type
- Returns
List of str
- get_texture_bins()
Get a list of texture bins in use.
This is useful for debugging and profiling only.
- Return type
- Returns
List of
TextureBin
Exceptions
- class ResourceNotFoundException(name)
The named resource was not found on the search path.
- class UndetectableShaderType(name)
The type of the Shader source could not be identified.