[Zope3-checkins] SVN: Zope3/branches/zipimport-support/src/zope/filereference/ add a convenience function to create a locale package reference

[Fred L. Drake, Jr.]

Log message for revision 40045:
  add a convenience function to create a locale package reference

Changed:
  U   Zope3/branches/zipimport-support/src/zope/filereference/README.txt
  U   Zope3/branches/zipimport-support/src/zope/filereference/__init__.py
  U   Zope3/branches/zipimport-support/src/zope/filereference/reference.py
  A   Zope3/branches/zipimport-support/src/zope/filereference/testmodule.py

-=-
Modified: Zope3/branches/zipimport-support/src/zope/filereference/README.txt
===================================================================
--- Zope3/branches/zipimport-support/src/zope/filereference/README.txt	2005-11-10 22:13:28 UTC (rev 40044)
+++ Zope3/branches/zipimport-support/src/zope/filereference/README.txt	2005-11-11 00:58:32 UTC (rev 40045)
@@ -147,3 +147,43 @@
   False
   >>> zope.filereference.isdir(ref)
   False
+
+Getting a local package-relative reference
+------------------------------------------
+
+It's easy to create package-relative references from within a
+package, or to files in other packages.  Let's start by specifying the
+package we're interested in.  We'll need a candidate package and the
+file name we're expecting to see::
+
+  >>> import xml.sax
+  >>> initfile = os.path.join(os.path.dirname(xml.sax.__file__), "__init__.py")
+
+Let's start by specifying the package using the package module::
+
+  >>> ref = zope.filereference.packageReference(
+  ...     "__init__.py", package=xml.sax)
+
+  >>> ref == initfile
+  True
+
+This will also work when we specify the context package using a
+string::
+
+  >>> ref = zope.filereference.packageReference(
+  ...     "__init__.py", package="xml.sax")
+
+  >>> ref == initfile
+  True
+
+To demonstrate this function from the context of a real package, we're
+going to use the `testmodule` module in this package.  We'll import
+the reference created there and check that it produces the reference
+we expect::
+
+  >>> initfile = os.path.join(
+  ...     os.path.dirname(zope.filereference.__file__), "__init__.py")
+
+  >>> from zope.filereference.testmodule import ref
+  >>> ref == initfile
+  True

Modified: Zope3/branches/zipimport-support/src/zope/filereference/__init__.py
===================================================================
--- Zope3/branches/zipimport-support/src/zope/filereference/__init__.py	2005-11-10 22:13:28 UTC (rev 40044)
+++ Zope3/branches/zipimport-support/src/zope/filereference/__init__.py	2005-11-11 00:58:32 UTC (rev 40045)
@@ -21,7 +21,8 @@
 import zope.interface
 
 
-from reference import open, new, exists, isdir, isfile, getmtime
+from reference import open, new, packageReference
+from reference import exists, isdir, isfile, getmtime
 
 
 from interfaces import IFileReferenceAPI

Modified: Zope3/branches/zipimport-support/src/zope/filereference/reference.py
===================================================================
--- Zope3/branches/zipimport-support/src/zope/filereference/reference.py	2005-11-10 22:13:28 UTC (rev 40044)
+++ Zope3/branches/zipimport-support/src/zope/filereference/reference.py	2005-11-11 00:58:32 UTC (rev 40045)
@@ -20,6 +20,7 @@
 import errno
 import os
 import StringIO
+import sys
 import zipimport
 
 import zope.interface
@@ -101,6 +102,34 @@
         return PathReference(p)
 
 
+def packageReference(path, package=None):
+    """Return a package-relative reference.
+
+    If `package` is None, this uses the context of the caller to generate
+    a package-relative reference to `path`, which should be a relative
+    path name.
+
+    If `package` is not None, it may be either a package name (as a string)
+    or a package module.  That package will be used instead of the caller's
+    package context.
+
+    """
+    if package is None:
+        globals = sys._getframe(1).f_globals
+        if "__path__" in globals:
+            # it's a package
+            package = globals["__name__"]
+        else:
+            name = globals["__name__"]
+            if "." in name:
+                package = name[:name.rfind(".")]
+            else:
+                raise ValueError("not called from a package context")
+    if isinstance(package, basestring):
+        package = sys.modules[package]
+    return new(path, package=package)
+
+
 class PathReference(str):
 
     zope.interface.implements(IFileReference)

Added: Zope3/branches/zipimport-support/src/zope/filereference/testmodule.py
===================================================================
--- Zope3/branches/zipimport-support/src/zope/filereference/testmodule.py	2005-11-10 22:13:28 UTC (rev 40044)
+++ Zope3/branches/zipimport-support/src/zope/filereference/testmodule.py	2005-11-11 00:58:32 UTC (rev 40045)
@@ -0,0 +1,23 @@
+##############################################################################
+#
+# Copyright (c) 2005 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Example use of the packageReference() function.
+
+This is referenced from the tests.
+
+"""
+__docformat__ = "reStructuredText"
+
+from zope.filereference import packageReference
+
+ref = packageReference("__init__.py")


Property changes on: Zope3/branches/zipimport-support/src/zope/filereference/testmodule.py
___________________________________________________________________
Name: svn:mime-type
   + text/x-python
Name: svn:eol-style
   + native