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, aio.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 andurllib
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 aTypeError
, if archive is not a valid ZIP archive.