Index: Doc/library/pkgutil.rst =================================================================== --- Doc/library/pkgutil.rst (revision 61688) +++ Doc/library/pkgutil.rst (working copy) @@ -8,7 +8,7 @@ .. versionadded:: 2.3 -This module provides a single function: +This module provides functions to manipulate packages: .. function:: extend_path(path, name) @@ -41,3 +41,24 @@ this function to raise an exception (in line with :func:`os.path.isdir` behavior). +.. function:: get_data(package, resource) + + Get a resource from a package. + + This is a wrapper round the PEP 302 loader :func:`get_data` API. The package + argument should be the name of a package, in standard module format + (foo.bar). The resource argument should be in the form of a relative + filename, using ``/`` as the path separator. The parent directory name + ``..`` is not allowed, and nor is a rooted name (starting with a ``/``). + + The function returns a binary string, which is the contents of the + specified resource. + + For packages located in the filesystem, which have already been imported, + this is the rough equivalent of:: + + d = os.path.dirname(sys.modules[package].__file__) + data = open(os.path.join(d, resource), 'rb').read() + + If the package cannot be located or loaded, or it uses a PEP 302 loader + which does not support :func:`get_data`, then None is returned. Index: Lib/test/test_pkgutil.py =================================================================== --- Lib/test/test_pkgutil.py (revision 0) +++ Lib/test/test_pkgutil.py (revision 0) @@ -0,0 +1,124 @@ +from test.test_support import run_unittest +import unittest +import sys +import imp +import pkgutil +import os +import os.path +import tempfile +import shutil +import zipfile + + + +class PkgutilTests(unittest.TestCase): + + def setUp(self): + self.dirname = tempfile.mkdtemp() + sys.path.insert(0, self.dirname) + + def tearDown(self): + del sys.path[0] + shutil.rmtree(self.dirname) + + def test_getdata_filesys(self): + pkg = 'test_getdata_filesys' + + # Include a LF and a CRLF, to test that binary data is read back + RESOURCE_DATA = 'Hello, world!\nSecond line\r\nThird line' + + # Make a package with some resources + package_dir = os.path.join(self.dirname, pkg) + os.mkdir(package_dir) + # Empty init.py + f = open(os.path.join(package_dir, '__init__.py'), "wb") + f.close() + # Resource files, res.txt, sub/res.txt + f = open(os.path.join(package_dir, 'res.txt'), "wb") + f.write(RESOURCE_DATA) + f.close() + os.mkdir(os.path.join(package_dir, 'sub')) + f = open(os.path.join(package_dir, 'sub', 'res.txt'), "wb") + f.write(RESOURCE_DATA) + f.close() + + # Check we can read the resources + res1 = pkgutil.get_data(pkg, 'res.txt') + self.assertEqual(res1, RESOURCE_DATA) + res2 = pkgutil.get_data(pkg, 'sub/res.txt') + self.assertEqual(res2, RESOURCE_DATA) + + def test_getdata_zipfile(self): + zip = 'test_getdata_zipfile.zip' + pkg = 'test_getdata_zipfile' + + # Include a LF and a CRLF, to test that binary data is read back + RESOURCE_DATA = 'Hello, world!\nSecond line\r\nThird line' + + # Make a package with some resources + zip_file = os.path.join(self.dirname, zip) + z = zipfile.ZipFile(zip_file, 'w') + + # Empty init.py + z.writestr(pkg + '/__init__.py', "") + # Resource files, res.txt, sub/res.txt + z.writestr(pkg + '/res.txt', RESOURCE_DATA) + z.writestr(pkg + '/sub/res.txt', RESOURCE_DATA) + z.close() + + # Check we can read the resources + sys.path.insert(0, zip_file) + res1 = pkgutil.get_data(pkg, 'res.txt') + self.assertEqual(res1, RESOURCE_DATA) + res2 = pkgutil.get_data(pkg, 'sub/res.txt') + self.assertEqual(res2, RESOURCE_DATA) + del sys.path[0] + +class PkgutilPEP302Tests(unittest.TestCase): + + class MyTestLoader(object): + def load_module(self, fullname): + # Create an empty module + mod = sys.modules.setdefault(fullname, imp.new_module(fullname)) + mod.__file__ = "<%s>" % self.__class__.__name__ + mod.__loader__ = self + # Make it a package + mod.__path__ = [] + # Count how many times the module is reloaded + mod.__dict__['loads'] = mod.__dict__.get('loads',0) + 1 + return mod + + def get_data(self, path): + return "Hello, world!" + + class MyTestImporter(object): + def find_module(self, fullname, path=None): + return PkgutilPEP302Tests.MyTestLoader() + + def setUp(self): + sys.meta_path.insert(0, self.MyTestImporter()) + + def tearDown(self): + del sys.meta_path[0] + + def test_getdata_pep302(self): + # Use a dummy importer/loader + self.assertEqual(pkgutil.get_data('foo', 'dummy'), "Hello, world!") + del sys.modules['foo'] + + def test_alreadyloaded(self): + # Ensure that get_data works without reloading - the "loads" module + # variable in the example loader should count how many times a reload + # occurs. + import foo + self.assertEqual(foo.loads, 1) + self.assertEqual(pkgutil.get_data('foo', 'dummy'), "Hello, world!") + self.assertEqual(foo.loads, 1) + del sys.modules['foo'] + +def test_main(): + run_unittest(PkgutilTests, PkgutilPEP302Tests) + +if __name__ == '__main__': + test_main() + Index: Lib/pkgutil.py =================================================================== --- Lib/pkgutil.py (revision 61688) +++ Lib/pkgutil.py (working copy) @@ -544,3 +544,40 @@ f.close() return path + +def get_data(package, resource): + """Get a resource from a package. + + This is a wrapper round the PEP 302 loader get_data API. The package + argument should be the name of a package, in standard module format + (foo.bar). The resource argument should be in the form of a relative + filename, using '/' as the path separator. The parent directory name '..' + is not allowed, and nor is a rooted name (starting with a '/'). + + The function returns a binary string, which is the contents of the + specified resource. + + For packages located in the filesystem, which have already been imported, + this is the rough equivalent of + + d = os.path.dirname(sys.modules[package].__file__) + data = open(os.path.join(d, resource), 'rb').read() + + If the package cannot be located or loaded, or it uses a PEP 302 loader + which does not support get_data(), then None is returned. + """ + + loader = get_loader(package) + if loader is None or not hasattr(loader, 'get_data'): + return None + mod = sys.modules.get(package) or loader.load_module(package) + if mod is None or not hasattr(mod, '__file__'): + return None + + # Modify the resource name to be compatible with the loader.get_data + # signature - an os.path format "filename" starting with the dirname of + # the package's __file__ + parts = resource.split('/') + parts.insert(0, os.path.dirname(mod.__file__)) + resource_name = os.path.join(*parts) + return loader.get_data(resource_name)