[Import-SIG] Loading Resources From a Python Module/Package

[Vinay Sajip]

PJ Eby <pje <at> telecommunity.com> writes:

> Apart from that, the implementations in pkg_resources can mostly be
> pulled for reuse, as well as the interfaces, and I'd suggest doing
> exactly that.  There are a lot of non-obvious gotchas dealing with
> zipfiles, and the implementation is fairly battle-hardened at this
> point.

I'm a bit late to this thread, but never mind :-)

Another possibility is to use distlib's resource implementation, which 
offers the same basic functionality as is being proposed / pkg_resources, 
along with a higher level API which I find easier to use. The API works 
uniformly with both filesystem resources and resources in zip files.

Basic usage:

import distlib.resources

finder = distlib.resources.Finder('package.name')
resource = finder.find('resource.bin') # could be 'nested/resource.bin

If there's no such resource, find() returns None. Otherwise, you can do a 
number of things with resource via its properties:

is_container - Whether this instance is a container of other resources.

bytes - All of the resource data as a byte string.

size - The size of the resource data in bytes.

resources - The relative names of all the contents of this resource.

path - This attribute is set by the resource’s finder. It is a textual 
representation of the path, such that if a PEP 302 loader’s get_data() 
method is called with the path, the resource’s bytes are returned by the 
loader. This attribute is analogous to the resource_filename API in 
setuptools. Note that for resources in zip files, the path will be a pointer 
to the resource in the zip file, and not directly usable as a filename. 
While setuptools deals with this by extracting zip entries to cache and 
returning filenames from the cache, this does not seem an appropriate thing 
to do in this package, as a resource is already made available to callers 
either as a stream or a string of bytes.

file_path - This attribute is the same as the path for file-based resource. 
For resources in a .zip file, the relevant resource is extracted to a file 
in a cache in the file system, and the name of the cached file is returned. 
This is for use with APIs that need file names, or need to be able to access 
data through OS-level file handles.

The resource also as an as_stream() method, which returns a binary stream of 
the resource’s data. This must be closed by the caller when it’s finished 
with.

There's a little more than I've mentioned here. Tutorial documentation is 
available at [1] and reference documentation is available at [2].

Regards,

Vinay Sajip

[1] http://distlib.readthedocs.org/en/latest/tutorial.html#using-the-
resource-api
[2] http://distlib.readthedocs.org/en/latest/reference.html#the-distlib-
resources-package