# py-sdl2 / doc / modules / sdl2ext_resources.rst

 Marcus von Appen 28f1e1e 2013-04-24 Marcus von Appen 9e4aac0 2013-04-22 Marcus von Appen 28f1e1e 2013-04-24 Marcus von Appen 9e4aac0 2013-04-22 Marcus von Appen 28f1e1e 2013-04-24 Marcus von Appen 9e4aac0 2013-04-22 Marcus von Appen 8f3bb84 2013-11-16 Marcus von Appen 9e4aac0 2013-04-22 Marcus von Appen 28f1e1e 2013-04-24 Marcus von Appen 9e4aac0 2013-04-22 Marcus von Appen 28f1e1e 2013-04-24 Marcus von Appen 9e4aac0 2013-04-22   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 .. currentmodule:: sdl2.ext 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 --- .. class:: 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. .. method:: 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). .. method:: 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. .. method:: 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. .. method:: get(filename : string) -> BytesIO Gets a specific file from the resource container. Raises a :exc:KeyError, if the *filename* could not be found. .. method:: get_filelike(filename : string) -> file object Similar to :meth:get(), but tries to return the original file handle, if possible. If the found file is only available within an archive, a :class:io.BytesIO instance will be returned. Raises a :exc:KeyError, if the *filename* could not be found. .. method:: 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 :exc:KeyError, if the *filename* could not be found. .. method:: 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. .. function:: 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 :class: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 :exc: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. .. function:: open_url(filename : string[, basepath=None]) -> file object Opens and reads a certain file from a web or remote location. This function utilizes the :mod:urllib2 module for Python 2.7 and :mod: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. .. function:: open_zipfile(archive : string, filename : string \ [, directory : string]) -> BytesIO Opens and reads a certain file from a ZIP archive. The result is returned as :class: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 :exc:KeyError will be raised. Raises a :exc:TypeError, if *archive* is not a valid ZIP archive. 
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.