[Python-checkins] r62350 - in python/trunk: Doc/library/pkgutil.rst Lib/pkgutil.py Misc/NEWS

[nick.coghlan]

Author: nick.coghlan
Date: Tue Apr 15 12:25:31 2008
New Revision: 62350

Log:
Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore)

Modified:
   python/trunk/Doc/library/pkgutil.rst
   python/trunk/Lib/pkgutil.py
   python/trunk/Misc/NEWS

Modified: python/trunk/Doc/library/pkgutil.rst
==============================================================================
--- python/trunk/Doc/library/pkgutil.rst	(original)
+++ python/trunk/Doc/library/pkgutil.rst	Tue Apr 15 12:25:31 2008
@@ -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.

Modified: python/trunk/Lib/pkgutil.py
==============================================================================
--- python/trunk/Lib/pkgutil.py	(original)
+++ python/trunk/Lib/pkgutil.py	Tue Apr 15 12:25:31 2008
@@ -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)

Modified: python/trunk/Misc/NEWS
==============================================================================
--- python/trunk/Misc/NEWS	(original)
+++ python/trunk/Misc/NEWS	Tue Apr 15 12:25:31 2008
@@ -29,6 +29,9 @@
 Library
 -------
 
+- Issue #2439: Added new function pkgutil.get_data(), which is a
+  convenience wrapper for the PEP 302 get_data() API.
+
 - Issue #2616: The ctypes.pointer() and ctypes.POINTER() functions are
   now implemented in C for better performance.