Source code for zope.location.interfaces

##############################################################################
#
# Copyright (c) 2003-2009 Zope Foundation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (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.
#
##############################################################################
"""Location framework interfaces
"""
__docformat__ = 'restructuredtext'

from zope.interface import Interface
from zope.interface import Attribute
from zope.schema import TextLine

from zope.location._compat import u

[docs]class ILocation(Interface): """Objects that can be located in a hierachy. 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__ = Attribute("The parent in the location hierarchy.") __name__ = TextLine( title=u("The name within the parent"), description=u("The object can be looked up from the parent's " "sublocations using this name."), required=False, default=None) # The IContained interface was moved from zope.container to here in # zope.container 3.8.2 to break dependency cycles. It is not actually # used within this package, but is depended upon by external # consumers.
[docs]class IContained(ILocation): """Objects contained in containers."""
[docs]class ILocationInfo(Interface): """Provides supplemental information for located objects. Requires that the object has been given a location in a hierarchy. """
[docs] def getRoot(): """Return the root object of the hierarchy."""
[docs] def getPath(): """Return the physical path to the object as a string. Uses '/' as the path segment separator. """
[docs] def getParent(): """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. """
[docs] def getParents(): """Returns a list starting with the object's parent followed by each of its parents. Raises a TypeError if the object is not connected to a containment root. """
[docs] def getName(): """Return the last segment of the physical path."""
[docs] def getNearestSite(): """Return the site the object is contained in If the object is a site, the object itself is returned. """
[docs]class ISublocations(Interface): """Provide access to sublocations of an object. All objects with the same parent object are called the ``sublocations`` of that parent. """
[docs] def sublocations(): """Return an iterable of the object's sublocations."""
[docs]class IRoot(Interface): """Marker interface to designate root objects within a location hierarchy. """
[docs]class LocationError(KeyError, LookupError): """There is no object for a given location.""" # Soft dependency on zope.component. # # Also, these interfaces used to be defined here directly, so this provides # backward-compatibility
try: from zope.component.interfaces import ISite except ImportError: #pragma NO COVER class ISite(Interface): pass