# Module 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.

Since: pyglet 1.1

## Classes

| ResourceNotFoundException The named resource was not found on the search path.
| Location Abstract resource location.
| FileLocation Location on the filesystem.
| ZIPLocation Location within a ZIP file.
| URLLocation Location on the network.
| Loader Load program resource files from disk.

## Functions

str | get_script_home() Get the directory containing the program entry module.
str | get_settings_path(name) Get a directory to save user preferences.
| reindex() Refresh the file index.
file object | file(name, mode=`'``rb``'`) Load a resource.
Location | location(name) Get the location of a resource.
| add_font(name) Add a font resource to the application.
Texture | image(name, flip_x=False, flip_y=False, rotate=0) Load an image with optional transformation.
Animation | animation(name, flip_x=False, flip_y=False, rotate=0) Load an animation with optional transformation.
list | get_cached_image_names() Get a list of image filenames that have been cached.
list | get_cached_animation_names() Get a list of animation filenames that have been cached.
list | get_texture_bins() Get a list of texture bins in use.
media.Source | media(name, streaming=True) Load a sound or video resource.
Texture | texture(name) Load a texture.
FormattedDocument | html(name) Load an HTML document.
FormattedDocument | attributed(name) Load an attributed text document.
UnformattedDocument | text(name) Load a plain text document.
list of str | get_cached_texture_names() Get the names of textures currently cached.

## Variables

| path = ``[``'``.``'``]``
| __package__ = ``'``pyglet``'``

## Function Details

### get_script_home

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.

Returns: str

### get_settings_path

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 hidden directory `name` in the user's home directory is returned.

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:
  name : str
    The name of the application.
Returns: str

### reindex

reindex()

Refresh the file index.

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

### file

file(name, mode=`'``rb``'`)
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.
Returns: file object

### location

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:
  name : str
    Filename of the resource to locate.
Returns: Location

### add_font

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:
  name : str
    Filename of the font resource to add.

### image

image(name, flip_x=False, flip_y=False, rotate=0)

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).
Returns:
  Texture: A complete texture if the image is large, otherwise a TextureRegion of a texture atlas.

### animation

animation(name, flip_x=False, flip_y=False, rotate=0)

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).
Returns: Animation

### get_cached_image_names

get_cached_image_names()

Get a list of image filenames that have been cached.

This is useful for debugging and profiling only.

Returns:
  list: List of str

### get_cached_animation_names

get_cached_animation_names()

Get a list of animation filenames that have been cached.

This is useful for debugging and profiling only.

Returns:
  list: List of str

### get_texture_bins

get_texture_bins()

Get a list of texture bins in use.

This is useful for debugging and profiling only.

Returns:
  list: List of TextureBin

### media

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:
  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.
Returns: media.Source

### texture

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:
  name : str
    Filename of the image resource to load.
Returns: Texture

### html

html(name)
Load an HTML document.

Parameters:
  name : str
    Filename of the HTML resource to load.
Returns: FormattedDocument

### attributed

attributed(name)

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.
Returns: FormattedDocument

### text

text(name)
Load a plain text document.

Parameters:
  name : str
    Filename of the plain text resource to load.
Returns: UnformattedDocument