Interfaces

Interfaces to do with traversing.

interface zope.traversing.interfaces.ITraversable

To traverse an object, this interface must be provided

traverse(name, furtherPath)

Get the next item on the path

Should return the item corresponding to ‘name’ or raise LocationError where appropriate.

Parameters:

• name (str) – an ASCII string or Unicode object.
• furtherPath (list) – is a list of names still to be traversed. This method is allowed to change the contents of furtherPath.

interface zope.traversing.interfaces.ITraverser

Provide traverse features

traverse(path, default=<object object at 0x7f7e2656c5b0>)

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.

interface zope.traversing.interfaces.ITraversalAPI

Common API functions to ease traversal computations.

This is provided by zope.traversing.api.

joinPath(path, *args)

Join the given relative paths to the given path.

Returns a text (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.

getPath(obj)

Returns a string representing the physical path to the object.

getRoot(obj)

Returns the root of the traversal for the given object.

traverse(object, path, default=None, request=None)

Traverse path relative to the given object.

Parameters:

• path (str) – a string with path segments separated by ‘/’.
• request – Passed in when traversing from presentation code. This allows paths like “@@foo” to work.

Raises:

zope.location.interfaces.LocationError – if path cannot be found

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.

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:zope.location.interfaces.LocationError – if path cannot be found and default was not provided.

getName(obj)

Get the name an object was traversed via

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.

getParents(obj)

Returns a list starting with the given object’s parent followed by each of its parents.

Raises:TypeError – if the context doesn’t go all the way down to a containment root.

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.

interface zope.traversing.interfaces.IPathAdapter

Marker interface for adapters to be used in paths

interface zope.traversing.interfaces.IEtcNamespace

Marker for utility registrations in the ++etc++ namespace

interface zope.traversing.interfaces.IBeforeTraverseEvent

Extends: zope.interface.interfaces.IObjectEvent

An event which gets sent on publication traverse

request

The current request

class zope.traversing.interfaces.BeforeTraverseEvent(ob, request)

Bases: zope.interface.interfaces.ObjectEvent

An event which gets sent on publication traverse.

Default implementation of IBeforeTraverseEvent.