Automatic Resource Extraction¶

In a modern setup, Python packages are usually installed as directories,and all the files can be found on deterministic locations on the disk.This means that most of the tools expect package resources to be “real” files.

There are a few occasions however that packages are loaded in a different way(e.g., from a zip file), which is incompatible with the assumptions mentioned above.Moreover, a package developer may also include non-extension native libraries or other files thatC extensions may expect to be able to access.

In these scenarios, the use ofimportlib.resources is recommended.

Old implementations (prior to the advent ofimportlib.resources) andlong-living projects, however, may still rely on the librarypkg_resourcesto access these files.

If you have to support such systems, or want to provide backward compatibilityforpkg_resources, you may need to add an special configurationtosetuptools when packaging a project.This can be done by listing aseager_resources (argument tosetup()insetup.py or field insetup.cfg) all the files that need to beextracted together, whenever a C extension in the project is imported.

This is especially important if your project includes shared librariesotherthandistutils/setuptools-built C extensions, and those shared libraries use fileextensions other than.dll,.so, or.dylib, which are theextensions that setuptools 0.6a8 and higher automatically detects as sharedlibraries and adds to thenative_libs.txt file for you. Any sharedlibraries whose names do not end with one of those extensions should be listedaseager_resources, because they need to be present in the filesystem whenhe C extensions that link to them are used.

Thepkg_resources runtime for compressed packages will automaticallyextractall C extensions andeager_resources at the same time, wheneverany C extension or eager resource is requested via theresource_filename()API. (C extensions are imported usingresource_filename() internally.)This ensures that C extensions will see all of the “real” files that theyexpect to see.

Note also that you can list directory resource names ineager_resources aswell, in which case the directory’s contents (including subdirectories) will beextracted whenever any C extension or eager resource is requested.

Please note that if you’re not sure whether you need to use this argument, youdon’t! It’s really intended to support projects with lots of non-Pythondependencies and as a last resort for crufty projects that can’t otherwisehandle being compressed. If your package is pure Python, Python plus datafiles, or Python plus C, you really don’t need this. You’ve got to be usingeither C or an external program that needs “real” files in your project beforethere’s any possibility ofeager_resources being relevant to your project.