[Zope3-checkins] SVN: Zope3/branches/zipimport-support/src/zope/filereference/ - add packageReference() to IFileReferenceAPI

[Fred L. Drake, Jr.]

Log message for revision 40116:
  - add packageReference() to IFileReferenceAPI
  - add test that zope.filereference conforms to IFileReferenceAPI
  

Changed:
  U   Zope3/branches/zipimport-support/src/zope/filereference/README.txt
  U   Zope3/branches/zipimport-support/src/zope/filereference/interfaces.py

-=-
Modified: Zope3/branches/zipimport-support/src/zope/filereference/README.txt
===================================================================
--- Zope3/branches/zipimport-support/src/zope/filereference/README.txt	2005-11-15 03:03:04 UTC (rev 40115)
+++ Zope3/branches/zipimport-support/src/zope/filereference/README.txt	2005-11-15 03:07:27 UTC (rev 40116)
@@ -13,12 +13,24 @@
 before this API existed, while new code can use the extended API for
 more flexibility.
 
-There are several interesting functions: `new()` is used to construct
-a new path reference, and `open()` is used to open the resource as a
-file-like object.  Additional functions correlate to the common
-functions `os.path.exists()`, `os.path.isdir()`, and
-`os.path.isfile()`.
+There are several interesting functions: `new()` and
+`packageReference()` are used to construct a new path reference, and
+`open()` is used to open the resource as a file-like object.
+Additional functions correlate to the common functions
+`os.path.exists()`, `os.path.isdir()`, and `os.path.isfile()`.
 
+The `zope.filereference` package implements the `IFileReferenceAPI`
+interface::
+
+  >>> import zope.filereference
+  >>> import zope.filereference.interfaces
+  >>> import zope.interface.verify
+
+  >>> zope.interface.verify.verifyObject(
+  ...     zope.filereference.interfaces.IFileReferenceAPI,
+  ...     zope.filereference)
+  True
+
 `new()` takes three arguments: a path, a package, and a base path.
 Only the first is required; passing `None` for the `package` and
 `basepath` arguments is equivalent to omitting them.
@@ -29,9 +41,6 @@
 to the constructor is non-`None`.  Let's take a look at what this
 provides::
 
-  >>> import os
-  >>> import zope.filereference
-
   >>> ref = zope.filereference.new("README.txt", package=zope.filereference)
 
 When a file reference is passed to `new()`, it is returned instead of
@@ -44,6 +53,8 @@
 If we examine the reference as a string, we get a path that points
 into the package::
 
+  >>> import os
+
   >>> directory = os.path.dirname(zope.filereference.__file__)
   >>> filename = os.path.join(directory, "README.txt")
   >>> ref == filename

Modified: Zope3/branches/zipimport-support/src/zope/filereference/interfaces.py
===================================================================
--- Zope3/branches/zipimport-support/src/zope/filereference/interfaces.py	2005-11-15 03:03:04 UTC (rev 40115)
+++ Zope3/branches/zipimport-support/src/zope/filereference/interfaces.py	2005-11-15 03:07:27 UTC (rev 40116)
@@ -57,6 +57,19 @@
     def new(path, package=None, basepath=None):
         """Return a new `IFileReference` object."""
 
+    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.
+
+        """
+
     def open(ref, mode="r"):
         """Open the referenced resource, returning a file-like object.