py-sdl2 / doc / modules / sdl2ext_resources.rst

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 :class:`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 :class:`Resources` instance, you created initially.

The :class:`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 :meth:`Resources.get`, you will receive a :class:`io.BytesIO` stream, containing the file data, for further processing.

Note

The scanned files act as keys within the :class:`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 :class:`Resources` class.

API

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

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.