diff options
Diffstat (limited to 'src/zope/traversing/interfaces.py')
| -rw-r--r-- | src/zope/traversing/interfaces.py | 103 |
1 files changed, 55 insertions, 48 deletions
diff --git a/src/zope/traversing/interfaces.py b/src/zope/traversing/interfaces.py index cd515ed..ad3b410 100644 --- a/src/zope/traversing/interfaces.py +++ b/src/zope/traversing/interfaces.py @@ -36,12 +36,12 @@ class ITraversable(Interface): """Get the next item on the path Should return the item corresponding to 'name' or raise - LocationError where appropriate. + :exc:`~zope.location.interfaces.LocationError` where appropriate. - 'name' is an ASCII string or Unicode object. - - 'furtherPath' is a list of names still to be traversed. This - method is allowed to change the contents of furtherPath. + :param str name: an ASCII string or Unicode object. + :param list furtherPath: is a list of names still to be + traversed. This method is allowed to change the contents + of furtherPath. """ @@ -62,31 +62,34 @@ class ITraverser(Interface): 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. + If the object is not found, return *default* argument. """ class ITraversalAPI(Interface): - """Common API functions to ease traversal computations + """ + Common API functions to ease traversal computations. + + This is provided by :mod:`zope.traversing.api`. """ def joinPath(path, *args): - """Join the given relative paths to the given path. + """Join the given relative paths to the given *path*. - Returns a unicode 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. + 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" + 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 + segment to the left to be removed. ``joinPath('/', '..')`` should raise an exception. """ @@ -99,40 +102,37 @@ class ITraversalAPI(Interface): """ 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 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. + """Traverse *path* relative to the given object. + + :param str path: a string with path segments separated by '/'. + :keyword 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. """ 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. + """Traverse a single step *name* relative to the given object. - You can explicitly pass in an ITraversable as the - 'traversable' argument. If you do not, the given object will - be adapted to ITraversable. + *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. - 'request' is passed in when traversing from presentation code. This - allows paths like @@foo to work. + You can explicitly pass in an `ITraversable` as the + *traversable* argument. If you do not, the given object will + be adapted to `ITraversable`. - Raises LocationError if path cannot be found and 'default' was - not provided. + *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. """ def getName(obj): @@ -142,25 +142,28 @@ class ITraversalAPI(Interface): 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. + 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. + """ + 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. + :raises 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. + """ + 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. + :raises ValueError: if a badly formed path is given. """ @@ -182,7 +185,11 @@ class IBeforeTraverseEvent(IObjectEvent): @implementer(IBeforeTraverseEvent) class BeforeTraverseEvent(ObjectEvent): - """An event which gets sent on publication traverse""" + """ + An event which gets sent on publication traverse. + + Default implementation of `IBeforeTraverseEvent`. + """ def __init__(self, ob, request): |