Resource management

Every application usually ships with various resources, such as image and data files, configuration files and so on. Accessing those files in the folder hierarchy or in a bundled format for various platforms can become a complex task. The Resources class allows you to manage different application data in a certain directory, providing a dictionary-style access functionality for your in-application resources.

Let’s assume, your application has the following installation layout

Application Directory
    Application.exe
    Application.conf
    data/
        background.jpg
        button1.jpg
        button2.jpg
        info.dat

Within the Application.exe code, you can - completely system-agnostic - define a new resource that keeps track of all data items.

apppath = os.path.dirname(os.path.abspath(__file__))
appresources = Resources(os.path.join(apppath, "data"))
# Access some images
bgimage = appresources.get("background.jpg")
btn1image = appresources.get("button1.jpg")
...

To access individual files, you do not need to concat paths the whole time and regardless of the current directory, your application operates on, you can access your resource files at any time through the Resources instance, you created initially.

The Resources class is also able to scan an index archived files, compressed via ZIP or TAR (gzip or bzip2 compression), and subdiectories automatically.

Application Directory
    Application.exe
    Application.conf
    data/
        audio/
            example.wav
        background.jpg
        button1.jpg
        button2.jpg
        graphics.zip
            [tileset1.bmp
             tileset2.bmp
             tileset3.bmp
             ]
        info.dat

tilesimage = appresources.get("tileset1.bmp")
audiofile = appresources.get("example.wav")

If you request an indexed file via Resources.get(), you will receive a io.BytesIO stream, containing the file data, for further processing.

Note

The scanned files act as keys within the Resources class. This means that two files, that have the same name, but are located in different directories, will not be indexed. Only one of them will be accessible through the Resources class.

API

class sdl2.ext.Resources([path=None[, subdir=None[, excludepattern=None]]])

The Resources class manages a set of file resources and eases accessing them by using relative paths, scanning archives automatically and so on.

add(filename : string)

Adds a file to the resource container. Depending on the file type (determined by the file suffix or name) the file will be automatically scanned (if it is an archive) or checked for availability (if it is a stream or network resource).

add_archive(filename : string[, typehint="zip"])

Adds an archive file to the resource container. This will scan the passed archive and add its contents to the list of available and accessible resources.

add_file(filename : string)

Adds a file to the resource container. This will only add the passed file and do not scan an archive or check the file for availability.

get(filename : string) → BytesIO

Gets a specific file from the resource container.

Raises a KeyError, if the filename could not be found.

get_filelike(filename : string) → file object

Similar to get(), but tries to return the original file handle, if possible. If the found file is only available within an archive, a io.BytesIO instance will be returned.

Raises a KeyError, if the filename could not be found.

get_path(filename : string) → string

Gets the path of the passed filename. If filename is only available within an archive, a string in the form filename@archivename will be returned.

Raises a KeyError, if the filename could not be found.

scan(path : string[, subdir=None[, excludepattern=None])

Scans a path and adds all found files to the resource container. If a file within the path is a supported archive (ZIP or TAR), its contents will be indexed aut added automatically.

The method will consider the directory part (os.path.dirname) of the provided path as path to scan, if the path is not a directory. If subdir is provided, it will be appended to the path and used as starting point for adding files to the resource container.

excludepattern can be a regular expression to skip directories, which match the pattern.

sdl2.ext.open_tarfile(archive : string, filename : string[, directory=None[, ftype=None]]) → BytesIO

Opens and reads a certain file from a TAR archive. The result is returned as BytesIO stream. filename can be a relative or absolute path within the TAR archive. The optional directory argument can be used to supply a relative directory path, under which filename will be searched.

ftype is used to supply additional compression information, in case the system cannot determine the compression type itself, and can be either “gz” for gzip compression or “bz2” for bzip2 compression.

If the filename could not be found or an error occurred on reading it, None will be returned.

Raises a TypeError, if archive is not a valid TAR archive or if ftype is not a valid value of (“gz”, “bz2”).

Note

If ftype is supplied, the compression mode will be enforced for opening and reading.

sdl2.ext.open_url(filename : string[, basepath=None]) → file object

Opens and reads a certain file from a web or remote location. This function utilizes the urllib2 module for Python 2.7 and urllib for Python 3.x, which means that it is restricted to the types of remote locations supported by the module.

basepath can be used to supply an additional location prefix.

sdl2.ext.open_zipfile(archive : string, filename : string[, directory : string]) → BytesIO

Opens and reads a certain file from a ZIP archive. The result is returned as BytesIO stream. filename can be a relative or absolute path within the ZIP archive. The optional directory argument can be used to supply a relative directory path, under which filename will be searched.

If the filename could not be found, a KeyError will be raised. Raises a TypeError, if archive is not a valid ZIP archive.