zope.location API — zope.location 4.0 documentation

### Navigation

- index
- modules |
- previous |
- zope.location 4.0 documentation »

# `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

### Navigation

- index
- modules |
- previous |
- zope.location 4.0 documentation »