pygrafix.resource — Managing resource locations

This module is used for managing resource locations from which pygrafix can load resources.

pygrafix.resource.add_location(location)

Adds a resource location to pygrafix. These resource locations are used in the functions get_path(), get_file(), get_location() and exists() as well as other resource loading functions throughout pygrafix (for example pygrafix.image.load()).

The location variable can be a string containing a path, a string containing the path to a zipfile as well as a custom object.

If a custom object is passed it must support at least the following methods:

class CustomLocation:
    # tries to open filename in this location with the correct mode
    # if for any reason this fails or the resource is not found raise IOError
    def open(self, filename, mode = "rb"):
        pass

    # return True if filename exists in this location, otherwise False
    def isfile(self, filename):
        pass

    # return an absolute path to filename in this location, whether it exists or not
    # if absolute paths are not applicable return anything you find appropriate, but don't raise an exception
    def getpath(self, filename):
        pass

pygrafix.resource.get_path(resource)

resource is a string containing the filename of a resource. This function will look through all resource locations and return an absolute path to the resource. IOError is raised if the resource was not found.

Note: an absolute path is not always available/appropriate, for example a path into a zipfile. Use this function for printing purposes only, or with care.

pygrafix.resource.get_file(resource)

resource is a string containing the filename of a resource. This function will look through all resource locations for the file and return a file object opened in binary reading mode. IOError is raised if the resource was not found.

pygrafix.resource.get_location(resource)

resource is a string containing the filename of a resource. This function will look through all resource locations for the resource, and if it’s found the function will return the containing location.

pygrafix.resource.exists(resource)

resource is a string containing the filename of a resource. This function will look through all resource locations and return True if the resource exists, otherwise False.

pygrafix.resource.get_script_home()

Returns a string containing the directory of 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.

pygrafix.resource.get_settings_path(name)

Returns a string containing 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.