1 files changed, 97 insertions, 15 deletions

diff --git a/src/zope/location/interfaces.py b/src/zope/location/interfaces.py
index c8478aa..d4b20d0 100644
--- a/src/zope/location/interfaces.py
+++ b/src/zope/location/interfaces.py
@@ -1,6 +1,6 @@
 ##############################################################################
 #
-# Copyright (c) 2003 Zope Corporation and Contributors.
+# Copyright (c) 2003-2009 Zope Corporation and Contributors.
 # All Rights Reserved.
 #
 # This software is subject to the provisions of the Zope Public License,
@@ -17,34 +17,115 @@ $Id$
 """
 __docformat__ = 'restructuredtext'
 
-from zope.interface import Interface, Attribute
-from zope import schema
+import zope.interface
+import zope.schema
 
+_RAISE_KEYERROR = object()
 
-class ILocation(Interface):
-    """Objects that have a structural location"""
 
-    __parent__ = Attribute("The parent in the location hierarchy")
+class ILocation(zope.interface.Interface):
+    """Objects that can be located in a hierachy.
 
-    __name__ = schema.TextLine(
+    Given a parent and a name an object can be located within that parent. The
+    locatable object's `__name__` and `__parent__` attributes store this
+    information.
+
+    Located objects form a hierarchy that can be used to build file-system-like
+    structures. For example in Zope `ILocation` is used to build URLs and to
+    support security machinery.
+
+    To retrieve an object from its parent using its name, the `ISublocation`
+    interface provides the `sublocations` method to iterate over all objects
+    located within the parent. The object searched for can be found by reading
+    each sublocation's __name__ attribute.
+
+    """
+
+    __parent__ = zope.interface.Attribute("The parent in the location hierarchy.")
+
+    __name__ = zope.schema.TextLine(
         title=u"The name within the parent",
-        description=u"Traverse the parent with this name to get the object.",
+        description=u"The object can be looked up from the parent's "
+            "sublocations using this name.",
         required=False,
         default=None)
 
 
-class ISublocations(Interface):
-    """Provide access to sublocations."""
+class ILocationInfo(zope.interface.Interface):
+    """Provides supplemental information for located objects.
+
+    Requires that the object has been given a location in a hierarchy.
+
+    """
+
+    def getRoot():
+        """Return the root object of the hierarchy."""
+
+    def getPath():
+        """Return the physical path to the object as a string.
+
+        Uses '/' as the path segment separator.
+
+        """
+
+    def getName():
+        """Return the last segment of the physical path."""
+
+    def getNearestSite():
+        """Return the site the object is contained in
+
+        If the object is a site, the object itself is returned.
+
+        """
+
+
+class ISublocations(zope.interface.Interface):
+    """Provide access to sublocations of an object.
+
+    All objects with the same parent object are called the ``sublocations`` of
+    that parent.
+
+    """
 
     def sublocations():
-        """Return sublocations
+        """Return an iterable of the object's sublocations."""
+
+
+class IRoot(zope.interface.Interface):
+    """Marker interface to designate root objects within a location hierarchy.
+    """
+
+
+
+
+class ITraverser(zope.interface.Interface):
+    """Provide traverse features"""
+
+    # XXX This is used like a utility but implemented as an adapter: The
+    # traversal policy is only implemented once and repeated for all objects
+    # along the path.
+
+    def traverse(path, default=_RAISE_KEYERROR):
+        """Return an object given a path.
+
+        Path is either an immutable sequence of strings or a slash ('/')
+        delimited string.
+
+        If the first string in the path sequence is an empty string, or the
+        path begins with a '/', start at the root. Otherwise the path is
+        relative to the current context.
+
+        If the object is not found, return 'default' argument.
 
-        An iterable of objects whose __parent__ is the object
-        providing the interface is returned.
         """
 
-class IPossibleSite(Interface):
-    """An object that could be a site
+
+class LocationError(KeyError, LookupError):
+    """There is no object for a given location."""
+
+
+class IPossibleSite(zope.interface.Interface):
+    """An object that could be a site.
     """
 
     def setSiteManager(sitemanager):
@@ -57,5 +138,6 @@ class IPossibleSite(Interface):
         If there isn't a site manager, raise a component lookup.
         """
 
+
 class ISite(IPossibleSite):
     """Marker interface to indicate that we have a site"""