zope.location API

zope.location.interfaces

Location framework interfaces

interface zope.location.interfaces.ILocation

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__

The parent in the location hierarchy.

__name__

The name within the parent

The object can be looked up from the parent’s sublocations using this name.

interface zope.location.interfaces.IContained

Extends: zope.location.interfaces.ILocation

Objects contained in containers.

interface zope.location.interfaces.ILocationInfo

Provides supplemental information for located objects.

Requires that the object has been given a location in a hierarchy.

getRoot()

Return the root object of the hierarchy.

getPath()

Return the physical path to the object as a string.

Uses ‘/’ as the path segment separator.

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.

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.

getName()

Return the last segment of the physical path.

getNearestSite()

Return the site the object is contained in

If the object is a site, the object itself is returned.

interface zope.location.interfaces.ISublocations

Provide access to sublocations of an object.

All objects with the same parent object are called the sublocations of that parent.

sublocations()

Return an iterable of the object’s sublocations.

interface zope.location.interfaces.IRoot

Marker interface to designate root objects within a location hierarchy.

exception zope.location.interfaces.LocationError

There is no object for a given location.

zope.location.location

Location support

class zope.location.location.Location

Mix-in that implements ILocation.

It provides the __parent__ and __name__ attributes.

zope.location.location.locate(obj, parent, name=None)

Update a location’s coordinates.

zope.location.location.located(obj, parent, name=None)

Ensure and return the location of an object.

Updates the location’s coordinates.

zope.location.location.LocationIterator(object)

Iterate over an object and all of its parents.

zope.location.location.inside(l1, l2)

Test whether l1 is a successor of l2.

l1 is a successor of l2 if l2 is in the chain of parents of l1 or l2 is l1.

class zope.location.location.LocationProxy(ob, container=None, name=None)

Location-object proxy

This is a non-picklable proxy that can be put around objects that don’t implement ILocation.

zope.location.traversing

Classes to support implenting IContained

class zope.location.traversing.LocationPhysicallyLocatable(context)

Provide location information for location objects

>>> from zope.interface.verify import verifyObject
>>> from zope.location.interfaces import ILocationInfo
>>> from zope.location.location import Location
>>> from zope.location.traversing import LocationPhysicallyLocatable
>>> info = LocationPhysicallyLocatable(Location())
>>> verifyObject(ILocationInfo, info)
True

getRoot()

See ILocationInfo.

>>> from zope.interface import directlyProvides
>>> from zope.location.interfaces import IRoot
>>> from zope.location.location import Location
>>> from zope.location.traversing import LocationPhysicallyLocatable
>>> root = Location()
>>> directlyProvides(root, IRoot)
>>> LocationPhysicallyLocatable(root).getRoot() is root
True

>>> o1 = Location(); o1.__parent__ = root
>>> LocationPhysicallyLocatable(o1).getRoot() is root
True

>>> o2 = Location(); o2.__parent__ = o1
>>> LocationPhysicallyLocatable(o2).getRoot() is root
True

We’ll get a TypeError if we try to get the location fo a rootless object:

>>> o1.__parent__ = None
>>> LocationPhysicallyLocatable(o1).getRoot()
Traceback (most recent call last):
...
TypeError: Not enough context to determine location root
>>> LocationPhysicallyLocatable(o2).getRoot()
Traceback (most recent call last):
...
TypeError: Not enough context to determine location root

If we screw up and create a location cycle, it will be caught:

>>> o1.__parent__ = o2
>>> LocationPhysicallyLocatable(o1).getRoot()
Traceback (most recent call last):
...
TypeError: Maximum location depth exceeded, probably due to a a location cycle.

getPath()

See ILocationInfo.

>>> from zope.interface import directlyProvides
>>> from zope.location.interfaces import IRoot
>>> from zope.location.location import Location
>>> from zope.location.traversing import LocationPhysicallyLocatable
>>> root = Location()
>>> directlyProvides(root, IRoot)
>>> LocationPhysicallyLocatable(root).getPath()
u'/'

>>> o1 = Location(); o1.__parent__ = root; o1.__name__ = 'o1'
>>> LocationPhysicallyLocatable(o1).getPath()
u'/o1'

>>> o2 = Location(); o2.__parent__ = o1; o2.__name__ = u'o2'
>>> LocationPhysicallyLocatable(o2).getPath()
u'/o1/o2'

It is an error to get the path of a rootless location:

>>> o1.__parent__ = None
>>> LocationPhysicallyLocatable(o1).getPath()
Traceback (most recent call last):
...
TypeError: Not enough context to determine location root

>>> LocationPhysicallyLocatable(o2).getPath()
Traceback (most recent call last):
...
TypeError: Not enough context to determine location root

If we screw up and create a location cycle, it will be caught:

>>> o1.__parent__ = o2
>>> LocationPhysicallyLocatable(o1).getPath()
Traceback (most recent call last):
...
TypeError: Maximum location depth exceeded, """ \
        """probably due to a a location cycle.

getParent()

See ILocationInfo.

>>> from zope.interface import directlyProvides
>>> from zope.location.interfaces import IRoot
>>> from zope.location.location import Location
>>> from zope.location.traversing import LocationPhysicallyLocatable
>>> root = Location()
>>> directlyProvides(root, IRoot)
>>> o1 = Location()
>>> o2 = Location()

>>> LocationPhysicallyLocatable(o2).getParent() 
Traceback (most recent call last):
TypeError: ('Not enough context information to get parent', <zope.location.location.Location object at 0x...>)

>>> o1.__parent__ = root
>>> LocationPhysicallyLocatable(o1).getParent() == root
True

>>> o2.__parent__ = o1
>>> LocationPhysicallyLocatable(o2).getParent() == o1
True

getParents()

See ILocationInfo.

>>> from zope.interface import directlyProvides
>>> from zope.interface import noLongerProvides
>>> from zope.location.interfaces import IRoot
>>> from zope.location.location import Location
>>> from zope.location.traversing import LocationPhysicallyLocatable
>>> root = Location()
>>> directlyProvides(root, IRoot)
>>> o1 = Location()
>>> o2 = Location()
>>> o1.__parent__ = root
>>> o2.__parent__ = o1
>>> LocationPhysicallyLocatable(o2).getParents() == [o1, root]
True

If the last parent is not an IRoot object, TypeError will be
raised as statet before.

>>> noLongerProvides(root, IRoot)
>>> LocationPhysicallyLocatable(o2).getParents()
Traceback (most recent call last):
...
TypeError: Not enough context information to get all parents

getName()

See ILocationInfo

>>> from zope.location.location import Location
>>> from zope.location.traversing import LocationPhysicallyLocatable
>>> o1 = Location(); o1.__name__ = u'o1'
>>> LocationPhysicallyLocatable(o1).getName()
u'o1'

getNearestSite()

See ILocationInfo

>>> from zope.interface import directlyProvides
>>> from zope.component.interfaces import ISite
>>> from zope.location.interfaces import IRoot
>>> from zope.location.location import Location
>>> from zope.location.traversing import LocationPhysicallyLocatable
>>> o1 = Location()
>>> o1.__name__ = 'o1'
>>> LocationPhysicallyLocatable(o1).getNearestSite()
Traceback (most recent call last):
...
TypeError: Not enough context information to get all parents

>>> root = Location()
>>> directlyProvides(root, IRoot)
>>> o1 = Location()
>>> o1.__name__ = 'o1'
>>> o1.__parent__ = root
>>> LocationPhysicallyLocatable(o1).getNearestSite() is root
True

>>> directlyProvides(o1, ISite)
>>> LocationPhysicallyLocatable(o1).getNearestSite() is o1
True

>>> o2 = Location()
>>> o2.__parent__ = o1
>>> LocationPhysicallyLocatable(o2).getNearestSite() is o1
True

class zope.location.traversing.RootPhysicallyLocatable(context)

Provide location information for the root object

This adapter is very simple, because there’s no places to search for parents and nearest sites, so we are only working with context object, knowing that its the root object already.

>>> from zope.interface.verify import verifyObject
>>> from zope.location.interfaces import ILocationInfo
>>> from zope.location.traversing import RootPhysicallyLocatable
>>> info = RootPhysicallyLocatable(None)
>>> verifyObject(ILocationInfo, info)
True

getRoot()

See ILocationInfo

No need to search for root when our context is already root :)

>>> from zope.location.traversing import RootPhysicallyLocatable
>>> o1 = object()
>>> RootPhysicallyLocatable(o1).getRoot() is o1
True

getPath()

See ILocationInfo

Root object is at the top of the tree, so always return /.

>>> from zope.location.traversing import RootPhysicallyLocatable
>>> o1 = object()
>>> RootPhysicallyLocatable(o1).getPath()
u'/'

getParent()

See ILocationInfo.

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

>>> from zope.location.traversing import RootPhysicallyLocatable
>>> o1 = object()
>>> RootPhysicallyLocatable(o1).getParent() is None
True

getParents()

See ILocationInfo

There’s no parents for the root object, return empty list.

>>> from zope.location.traversing import RootPhysicallyLocatable
>>> o1 = object()
>>> RootPhysicallyLocatable(o1).getParents()
[]

getName()

See ILocationInfo

Always return empty unicode string for the root object

>>> from zope.location.traversing import RootPhysicallyLocatable
>>> o1 = object()
>>> RootPhysicallyLocatable(o1).getName()
u''

getNearestSite()

See ILocationInfo

Return object itself as the nearest site, because there’s no other place to look for. It’s also usual that the root is the site as well.

>>> from zope.location.traversing import RootPhysicallyLocatable
>>> o1 = object()
>>> RootPhysicallyLocatable(o1).getNearestSite() is o1
True