[Zope3-checkins] CVS: Zope3/src/zope/app/traversing - interfaces.py:1.1 __init__.py:1.27 adapters.py:1.19 configure.zcml:1.12 namespace.py:1.27

[Stephan Richter]

Update of /cvs-repository/Zope3/src/zope/app/traversing
In directory cvs.zope.org:/tmp/cvs-serv31403/src/zope/app/traversing

Modified Files:
	__init__.py adapters.py configure.zcml namespace.py 
Added Files:
	interfaces.py 
Log Message:


Moved traversing interfaces to zope.app.traversing.interfaces.


=== Added File Zope3/src/zope/app/traversing/interfaces.py ===
##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.0 (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.
#
##############################################################################
"""Interfaces to do with traversing.

$Id: interfaces.py,v 1.1 2004/03/13 21:03:23 srichter Exp $
"""
from zope.interface import Interface

class IContainmentRoot(Interface):
    """Marker interface to designate root objects
    """

class INamespaceHandler(Interface):

    def __call__(name, parameters, pname, object, request):
        """Access a name in a namespace

        The name lookup usually depends on an object and/or a
        request. If an object or request is unavailable, None will be passed.

        The parameters provided, are passed as a sequence of
        name, value items.  The 'pname' argument has the original name
        before parameters were removed.

        It is not the respoonsibility of the handler to wrap the return value.
        """

class IPhysicallyLocatable(Interface):
    """Objects that have a physical location in a containment hierarchy.
    """

    def getRoot():
        """Return the physical root object
        """

    def getPath():
        """Return the physical path to the object as a string.
        """

    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, self is returned.
        """

class ITraversable(Interface):
    """To traverse an object, this interface must be provided"""

    def traverse(name, parameters, pname, furtherPath):
        """Get the next item on the path

        Should return the item corresponding to 'name' or raise
        NotFoundError where appropriate.

        The parameters provided, are passed as a sequence of
        name, value items.  The 'pname' argument has the original name
        before parameters were removed.

        furtherPath is a list of names still to be traversed. This method is
        allowed to change the contents of furtherPath.

        """

_RAISE_KEYERROR = object()

class ITraverser(Interface):
    """Provide traverse features"""

    def traverse(path, default=_RAISE_KEYERROR, request=None):
        """
        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.

        'request' is passed in when traversing from presentation code. This
        allows paths like @@foo to work.
        """

class ITraversalAPI(Interface):
    """Common API functions to ease traversal computations
    """

    def joinPath(path, *args):
        """Join the given relative paths to the given path.

        Returns a unicode path.

        The path should be well-formed, and not end in a '/' unless it is
        the root path. It can be either a string (ascii only) or unicode.
        The positional arguments are relative paths to be added to the
        path as new path segments.  The path may be absolute or relative.

        A segment may not start with a '/' because that would be confused
        with an absolute path. A segment may not end with a '/' because we
        do not allow '/' at the end of relative paths.  A segment may
        consist of . or .. to mean "the same place", or "the parent path"
        respectively. A '.' should be removed and a '..' should cause the
        segment to the left to be removed.  joinPath('/', '..') should
        raise an exception.
        """

    def getPath(obj):
        """Returns a string representing the physical path to the object.
        """

    def getRoot(obj):
        """Returns the root of the traversal for the given object.
        """

    def traverse(object, path, default=None, request=None):
        """Traverse 'path' relative to the given object.

        'path' is a string with path segments separated by '/'.

        'request' is passed in when traversing from presentation code. This
        allows paths like @@foo to work.

        Raises NotFoundError if path cannot be found
        Raises TypeError if place is not context wrapped

        Note: calling traverse with a path argument taken from an untrusted
              source, such as an HTTP request form variable, is a bad idea.
              It could allow a maliciously constructed request to call
              code unexpectedly.
              Consider using traverseName instead.
        """

    def traverseName(obj, name, default=None, traversable=None,
                     request=None):
        """Traverse a single step 'name' relative to the given object.

        'name' must be a string. '.' and '..' are treated specially, as well as
        names starting with '@' or '+'. Otherwise 'name' will be treated as a
        single path segment.

        You can explicitly pass in an ITraversable as the
        'traversable' argument. If you do not, the given object will
        be adapted to ITraversable.

        'request' is passed in when traversing from presentation code. This
        allows paths like @@foo to work.

        Raises NotFoundError if path cannot be found and 'default' was
        not provided.

        """

    def getName(obj):
        """Get the name an object was traversed via
        """

    def getParent(obj):
        """Returns the container the object was traversed via.

        Returns None if the object is a containment root.
        Raises TypeError if the object doesn't have enough context to get the
        parent.
        """

    def getParents(obj):
        """Returns a list starting with the given object's parent followed by
        each of its parents.

        Raises a TypeError if the context doesn't go all the way down to
        a containment root.
        """

    def canonicalPath(path_or_object):
        """Returns a canonical absolute unicode path for the path or object.

        Resolves segments that are '.' or '..'.

        Raises ValueError if a badly formed path is given.
        """



=== Zope3/src/zope/app/traversing/__init__.py 1.26 => 1.27 ===
--- Zope3/src/zope/app/traversing/__init__.py:1.26	Sat Mar  6 11:50:31 2004
+++ Zope3/src/zope/app/traversing/__init__.py	Sat Mar 13 16:03:23 2004
@@ -18,8 +18,8 @@
 """
 
 from zope.interface import moduleProvides
-from zope.app.interfaces.traversing import IContainmentRoot, ITraversalAPI
-from zope.app.interfaces.traversing import ITraverser, IPhysicallyLocatable
+from interfaces import IContainmentRoot, ITraversalAPI
+from interfaces import ITraverser, IPhysicallyLocatable
 
 moduleProvides(ITraversalAPI)
 __all__ = tuple(ITraversalAPI)


=== Zope3/src/zope/app/traversing/adapters.py 1.18 => 1.19 ===
--- Zope3/src/zope/app/traversing/adapters.py:1.18	Sat Mar  6 12:48:54 2004
+++ Zope3/src/zope/app/traversing/adapters.py	Sat Mar 13 16:03:23 2004
@@ -17,9 +17,9 @@
 
 from zope.exceptions import NotFoundError
 
-from zope.app.interfaces.traversing import IPhysicallyLocatable
-from zope.app.interfaces.traversing import IContainmentRoot
-from zope.app.interfaces.traversing import ITraverser, ITraversable
+from zope.app.traversing.interfaces import IPhysicallyLocatable
+from zope.app.traversing.interfaces import IContainmentRoot
+from zope.app.traversing.interfaces import ITraverser, ITraversable
 
 from zope.app.traversing.namespace import namespaceLookup
 from zope.app.traversing.namespace import UnexpectedParameters


=== Zope3/src/zope/app/traversing/configure.zcml 1.11 => 1.12 ===
--- Zope3/src/zope/app/traversing/configure.zcml:1.11	Sun Sep 21 13:31:14 2003
+++ Zope3/src/zope/app/traversing/configure.zcml	Sat Mar 13 16:03:23 2004
@@ -3,16 +3,16 @@
 <adapter 
     for="*"
     factory="zope.app.traversing.adapters.Traverser"
-    provides="zope.app.interfaces.traversing.ITraverser" />
+    provides="zope.app.traversing.interfaces.ITraverser" />
 
 <adapter 
     for="*"
     factory="zope.app.traversing.adapters.DefaultTraversable"
-    provides="zope.app.interfaces.traversing.ITraversable" />
+    provides="zope.app.traversing.interfaces.ITraversable" />
 
 <adapter 
-    provides="zope.app.interfaces.traversing.IPhysicallyLocatable"
-    for="zope.app.interfaces.traversing.IContainmentRoot"
+    provides="zope.app.traversing.interfaces.IPhysicallyLocatable"
+    for="zope.app.traversing.interfaces.IContainmentRoot"
     factory="zope.app.traversing.adapters.RootPhysicallyLocatable" />
 
 <traversalNamespace


=== Zope3/src/zope/app/traversing/namespace.py 1.26 => 1.27 ===
--- Zope3/src/zope/app/traversing/namespace.py:1.26	Sat Mar  6 12:48:54 2004
+++ Zope3/src/zope/app/traversing/namespace.py	Sat Mar 13 16:03:23 2004
@@ -18,7 +18,7 @@
 import re
 from zope.app import zapi
 from zope.exceptions import NotFoundError
-from zope.app.interfaces.traversing import ITraversable
+from zope.app.traversing.interfaces import ITraversable
 from zope.proxy import removeAllProxies
 
 class UnexpectedParameters(NotFoundError):
@@ -146,7 +146,7 @@
 
 from zope.app.applicationcontrol.applicationcontrol \
     import applicationController
-from zope.app.interfaces.traversing import IContainmentRoot
+from zope.app.traversing.interfaces import IContainmentRoot
 def etc(name, parameters, pname, ob, request):
     # XXX