zope.container API

Interfaces

Container-related interfaces

exception zope.container.interfaces.ContainerError

Bases: Exception

An error of a container with one of its components.

exception zope.container.interfaces.DuplicateIDError

Bases: KeyError

exception zope.container.interfaces.InvalidContainerType

Bases: Invalid, TypeError

The type of a container is not valid.

exception zope.container.interfaces.InvalidItemType

Bases: Invalid, TypeError

The type of an item is not valid.

exception zope.container.interfaces.InvalidType

Bases: Invalid, TypeError

The type of an object is not valid.

exception zope.container.interfaces.NameReserved

Bases: ValueError

The name is reserved for this container

exception zope.container.interfaces.UnaddableError(container, obj, message='')

Bases: ContainerError

An object cannot be added to a container.

Implementations

Bases and Events

Classes to support implementing IContained

class zope.container.contained.Contained

Bases: object

Simple mix-in that defines __parent__ and __name__ attributes and implements IContained.

class zope.container.contained.ContainedProxy

Bases: ContainedProxyBase

Wraps an object to implement zope.container.interfaces.IContained with a new __name__ and __parent__.

The new object provides everything the wrapped object did, plus IContained and IPersistent.

class zope.container.contained.ContainedProxyClassProvides(cls, metacls, *interfaces)

Bases: ClassProvides

Delegates __provides__ to the instance.

>>> class D1(ContainedProxy):
...    pass
>>> class Base(object):
...    pass
>>> base = Base()
>>> d = D1(base)
>>> d.__provides__ = 42
>>> base.__provides__
42
>>> del d.__provides__
>>> hasattr(base, '__provides__')
False

class zope.container.contained.ContainerModifiedEvent(object, *descriptions)

Bases: ObjectModifiedEvent

The container has been modified.

Init with a list of modification descriptions.

class zope.container.contained.ContainerSublocations(container)

Bases: object

Get the sublocations for a container

Obviously, this is the container values:

>>> class MyContainer(object):
...     def __init__(self, **data):
...         self.data = data
...     def __iter__(self):
...         return iter(self.data)
...     def __getitem__(self, key):
...         return self.data[key]

>>> container = MyContainer(x=1, y=2, z=42)
>>> adapter = ContainerSublocations(container)
>>> sublocations = list(adapter.sublocations())
>>> sublocations.sort()
>>> sublocations
[1, 2, 42]

class zope.container.contained.DecoratedSecurityCheckerDescriptor

Bases: object

Descriptor for a Decorator that provides a decorated security checker.

>>> class WithChecker(object):
...     __Security_checker__ = object()

>>> class D1(ContainedProxy):
...    pass

>>> d = D1(object())
>>> d.__Security_checker__
<...Checker...>

An existing checker is added to this one:

>>> d = D1(WithChecker())
>>> d.__Security_checker__
<...CombinedChecker...>

class zope.container.contained.DecoratorSpecificationDescriptor

Bases: ObjectSpecificationDescriptor

Support for interface declarations on decorators

>>> from zope.interface import Interface, directlyProvides, implementer
>>> class I1(Interface):
...     pass
>>> class I2(Interface):
...     pass
>>> class I3(Interface):
...     pass
>>> class I4(Interface):
...     pass

>>> @implementer(I1)
... class D1(ContainedProxy):
...   pass

>>> @implementer(I2)
... class D2(ContainedProxy):
...   pass

>>> @implementer(I3)
... class X:
...   pass

>>> x = X()
>>> directlyProvides(x, I4)

Interfaces of X are ordered with the directly-provided interfaces first

>>> [interface.getName() for interface in list(providedBy(x))]
['I4', 'I3']

When we decorate objects, what order should the interfaces come in? One could argue that decorators are less specific, so they should come last. This is subject to respecting the C3 resolution order, of course.

>>> [interface.getName() for interface in list(providedBy(D1(x)))]
['I4', 'I3', 'I1', 'IContained', 'IPersistent']

>>> [interface.getName() for interface in list(providedBy(D2(D1(x))))]
['I4', 'I3', 'I1', 'I2', 'IContained', 'IPersistent']

zope.container.contained.contained(object, container, name=None)

Establish the containment of the object in the container

Just return the contained object without an event. This is a convenience “macro” for:

containedEvent(object, container, name)[0]

This function is only used for tests.

zope.container.contained.containedEvent(object, container, name=None)

Establish the containment of the object in the container

The object and necessary event are returned. The object may be a ContainedProxy around the original object. The event is an added event, a moved event, or None.

If the object implements IContained, simply set its __parent__ and __name__ attributes:

>>> container = {}
>>> item = Contained()
>>> x, event = containedEvent(item, container, 'foo')
>>> x is item
True
>>> item.__parent__ is container
True
>>> item.__name__
'foo'

We have an added event:

>>> event.__class__.__name__
'ObjectAddedEvent'
>>> event.object is item
True
>>> event.newParent is container
True
>>> event.newName
'foo'
>>> event.oldParent
>>> event.oldName

Now if we call contained again:

>>> x2, event = containedEvent(item, container, 'foo')
>>> x2 is item
True
>>> item.__parent__ is container
True
>>> item.__name__
'foo'

We don’t get a new added event:

>>> event

If the object already had a parent but the parent or name was different, we get a moved event:

>>> x, event = containedEvent(item, container, 'foo2')
>>> event.__class__.__name__
'ObjectMovedEvent'
>>> event.object is item
True
>>> event.newParent is container
True
>>> event.newName
'foo2'
>>> event.oldParent is container
True
>>> event.oldName
'foo'

If the object implements ILocation, but not IContained, set its __parent__ and __name__ attributes and declare that it implements IContained:

>>> from zope.location import Location
>>> from zope.location.interfaces import IContained
>>> item = Location()
>>> IContained.providedBy(item)
False
>>> x, event = containedEvent(item, container, 'foo')
>>> x is item
True
>>> item.__parent__ is container
True
>>> item.__name__
'foo'
>>> IContained.providedBy(item)
True

If the object doesn’t even implement ILocation, put a ContainedProxy around it:

>>> item = []
>>> x, event = containedEvent(item, container, 'foo')
>>> x is item
False
>>> x.__parent__ is container
True
>>> x.__name__
'foo'

Make sure we don’t lose existing directly provided interfaces.

>>> from zope.interface import Interface, directlyProvides
>>> class IOther(Interface):
...     pass
>>> from zope.location import Location
>>> item = Location()
>>> directlyProvides(item, IOther)
>>> IOther.providedBy(item)
True
>>> x, event = containedEvent(item, container, 'foo')
>>> IOther.providedBy(item)
True

zope.container.contained.dispatchToSublocations(object, event)

Dispatch an event to sublocations of a given object

When a move event happens for an object, it’s important to notify subobjects as well.

We do this based on locations.

Suppose, for example, that we define some location objects.

>>> @zope.interface.implementer(ILocation)
... class L(object):
...     def __init__(self, name):
...         self.__name__ = name
...         self.__parent__ = None
...     def __repr__(self):
...         return '%s(%s)' % (
...                 self.__class__.__name__, str(self.__name__))

>>> @zope.interface.implementer(ISublocations)
... class C(L):
...     def __init__(self, name, *subs):
...         L.__init__(self, name)
...         self.subs = subs
...         for sub in subs:
...             sub.__parent__ = self
...     def sublocations(self):
...         return self.subs

>>> c = C(1,
...       C(11,
...         L(111),
...         L(112),
...         ),
...       C(12,
...         L(121),
...         L(122),
...         L(123),
...         L(124),
...         ),
...       L(13),
...       )

Now, if we call the dispatcher, it should call event handlers for all of the objects.

Lets create an event handler that records the objects it sees:

>>> seen = []
>>> def handler(ob, event):
...     seen.append((ob, event.object))

Note that we record the the object the handler is called on as well as the event object:

Now we’ll register it:

>>> from zope import component
>>> from zope.lifecycleevent.interfaces import IObjectMovedEvent
>>> component.provideHandler(handler, [None, IObjectMovedEvent])

We also register our dispatcher:

>>> component.provideHandler(dispatchToSublocations,
...   [None, IObjectMovedEvent])

We can then call the dispatcher for the root object:

>>> event = ObjectRemovedEvent(c)
>>> dispatchToSublocations(c, event)

Now, we should have seen all of the subobjects:

>>> seenreprs = sorted(map(repr, seen))
>>> seenreprs
['(C(11), C(1))', '(C(12), C(1))', '(L(111), C(1))', '(L(112), C(1))', '(L(121), C(1))', '(L(122), C(1))', '(L(123), C(1))', '(L(124), C(1))', '(L(13), C(1))']

We see that we get entries for each of the subobjects and that,for each entry, the event object is top object.

This suggests that location event handlers need to be aware that the objects they are called on and the event objects could be different.

zope.container.contained.notifyContainerModified(object, *descriptions)

Notify that the container was modified.

zope.container.contained.setitem(container, setitemf, name, object)

Helper function to set an item and generate needed events

This helper is needed, in part, because the events need to get published after the object has been added to the container.

If the item implements IContained, simply set its __parent__ and __name__ attributes:

>>> class IItem(zope.interface.Interface):
...     pass
>>> @zope.interface.implementer(IItem)
... class Item(Contained):
...     def setAdded(self, event):
...         self.added = event
...     def setMoved(self, event):
...         self.moved = event

>>> from zope.lifecycleevent.interfaces import IObjectAddedEvent
>>> from zope.lifecycleevent.interfaces import IObjectMovedEvent

>>> from zope import component
>>> component.provideHandler(lambda obj, event: obj.setAdded(event),
...   [IItem, IObjectAddedEvent])
>>> component.provideHandler(lambda obj, event: obj.setMoved(event),
...   [IItem, IObjectMovedEvent])

>>> item = Item()

>>> container = {}
>>> setitem(container, container.__setitem__, 'c', item)
>>> container['c'] is item
True
>>> item.__parent__ is container
True
>>> item.__name__
'c'

If we run this using the testing framework, we’ll use getEvents to track the events generated:

>>> from zope.component.eventtesting import getEvents
>>> from zope.lifecycleevent.interfaces import IObjectModifiedEvent

We have an added event:

>>> len(getEvents(IObjectAddedEvent))
1
>>> event = getEvents(IObjectAddedEvent)[-1]
>>> event.object is item
True
>>> event.newParent is container
True
>>> event.newName
'c'
>>> event.oldParent
>>> event.oldName

As well as a modification event for the container:

>>> len(getEvents(IObjectModifiedEvent))
1
>>> getEvents(IObjectModifiedEvent)[-1].object is container
1

The item’s hooks have been called:

>>> item.added is event
1
>>> item.moved is event
1

We can suppress events and hooks by setting the __parent__ and __name__ first:

>>> item = Item()
>>> item.__parent__, item.__name__ = container, 'c2'
>>> setitem(container, container.__setitem__, 'c2', item)
>>> len(container)
2
>>> len(getEvents(IObjectAddedEvent))
1
>>> len(getEvents(IObjectModifiedEvent))
1

>>> getattr(item, 'added', None)
>>> getattr(item, 'moved', None)

If the item had a parent or name (as in a move or rename), we generate a move event, rather than an add event:

>>> setitem(container, container.__setitem__, 'c3', item)
>>> len(container)
3
>>> len(getEvents(IObjectAddedEvent))
1
>>> len(getEvents(IObjectModifiedEvent))
2
>>> len(getEvents(IObjectMovedEvent))
2

(Note that we have 2 move events because add are move events.)

We also get the move hook called, but not the add hook:

>>> event = getEvents(IObjectMovedEvent)[-1]
>>> getattr(item, 'added', None)
>>> item.moved is event
1

If we try to replace an item without deleting it first, we’ll get an error:

>>> setitem(container, container.__setitem__, 'c', [])
Traceback (most recent call last):
...
KeyError: 'c'

>>> del container['c']
>>> setitem(container, container.__setitem__, 'c', [])
>>> len(getEvents(IObjectAddedEvent))
2
>>> len(getEvents(IObjectModifiedEvent))
3

If the object implements ILocation, but not IContained, set it’s __parent__ and __name__ attributes and declare that it implements IContained:

>>> from zope.location import Location
>>> item = Location()
>>> IContained.providedBy(item)
0
>>> setitem(container, container.__setitem__, 'l', item)
>>> container['l'] is item
1
>>> item.__parent__ is container
1
>>> item.__name__
'l'
>>> IContained.providedBy(item)
1

We get new added and modification events:

>>> len(getEvents(IObjectAddedEvent))
3
>>> len(getEvents(IObjectModifiedEvent))
4

If the object doesn’t even implement ILocation, put a ContainedProxy around it:

>>> item = []
>>> setitem(container, container.__setitem__, 'i', item)
>>> container['i']
[]
>>> container['i'] is item
0
>>> item = container['i']
>>> item.__parent__ is container
1
>>> item.__name__
'i'
>>> IContained.providedBy(item)
1

>>> len(getEvents(IObjectAddedEvent))
4
>>> len(getEvents(IObjectModifiedEvent))
5

We’ll get type errors if we give keys that aren’t unicode or ascii keys:

>>> setitem(container, container.__setitem__, 42, item)
Traceback (most recent call last):
...
TypeError: name not unicode or ascii string

>>> setitem(container, container.__setitem__, None, item)
Traceback (most recent call last):
...
TypeError: name not unicode or ascii string

>>> setitem(container, container.__setitem__, b'hello \xc8', item)
Traceback (most recent call last):
...
TypeError: name not unicode or ascii string

and we’ll get a value error of we give an empty string or unicode:

>>> setitem(container, container.__setitem__, '', item)
Traceback (most recent call last):
...
ValueError: empty names are not allowed

>>> setitem(container, container.__setitem__, '', item)
Traceback (most recent call last):
...
ValueError: empty names are not allowed

zope.container.contained.uncontained(object, container, name=None)

Clear the containment relationship between the object and the container.

If we run this using the testing framework, we’ll use getEvents to track the events generated:

>>> from zope.component.eventtesting import getEvents
>>> from zope.lifecycleevent.interfaces import IObjectModifiedEvent
>>> from zope.lifecycleevent.interfaces import IObjectRemovedEvent

We’ll start by creating a container with an item:

>>> class Item(Contained):
...     pass

>>> item = Item()
>>> container = {'foo': item}
>>> x, event = containedEvent(item, container, 'foo')
>>> item.__parent__ is container
1
>>> item.__name__
'foo'

Now we’ll remove the item. It’s parent and name are cleared:

>>> uncontained(item, container, 'foo')
>>> item.__parent__
>>> item.__name__

We now have a new removed event:

>>> len(getEvents(IObjectRemovedEvent))
1
>>> event = getEvents(IObjectRemovedEvent)[-1]
>>> event.object is item
1
>>> event.oldParent is container
1
>>> event.oldName
'foo'
>>> event.newParent
>>> event.newName

As well as a modification event for the container:

>>> len(getEvents(IObjectModifiedEvent))
1
>>> getEvents(IObjectModifiedEvent)[-1].object is container
1

Now if we call uncontained again:

>>> uncontained(item, container, 'foo')

We won’t get any new events, because __parent__ and __name__ are None:

>>> len(getEvents(IObjectRemovedEvent))
1
>>> len(getEvents(IObjectModifiedEvent))
1

But, if either the name or parent are not None and they are not the container and the old name, we’ll get a modified event but not a removed event.

>>> item.__parent__, item.__name__ = container, None
>>> uncontained(item, container, 'foo')
>>> len(getEvents(IObjectRemovedEvent))
1
>>> len(getEvents(IObjectModifiedEvent))
2

>>> item.__parent__, item.__name__ = None, 'bar'
>>> uncontained(item, container, 'foo')
>>> len(getEvents(IObjectRemovedEvent))
1
>>> len(getEvents(IObjectModifiedEvent))
3

If one tries to delete a Broken object, we allow them to do just that.

>>> class Broken(object):
...     __Broken_state__ = {}
>>> broken = Broken()
>>> broken.__Broken_state__['__name__'] = 'bar'
>>> broken.__Broken_state__['__parent__'] = container
>>> container['bar'] = broken
>>> uncontained(broken, container, 'bar')
>>> len(getEvents(IObjectRemovedEvent))
2

BTree

This module provides a sample btree container implementation.

class zope.container.btree.BTreeContainer

Bases: Contained, Persistent

OOBTree-based container

get(key, default=None)

See interface IReadContainer

has_key(key)

See interface IReadContainer

Directory

File-system representation adapters for containers

This module includes two adapters (adapter factories, really) for providing a file-system representation for containers:

noop

Factory that “adapts” IContainer to IWriteDirectory. This is a lie, since it just returns the original object.

Cloner

An IDirectoryFactory adapter that just clones the original object.

class zope.container.directory.Cloner(context)

Bases: object

IContainer to zope.filerepresentation.interfaces.IDirectoryFactory adapter that clones.

This adapter provides a factory that creates a new empty container of the same class as it’s context.

class zope.container.directory.ReadDirectory(context)

Bases: object

Adapter to provide a file-system rendition of folders.

zope.container.directory.noop(container)

Adapt an IContainer to an IWriteDirectory by just returning it

This “works” because IContainer and IWriteDirectory have the same methods, however, the output doesn’t actually implement IWriteDirectory.

Folders

The standard Zope Folder.

class zope.container.folder.Folder

Bases: BTreeContainer

The standard Zope Folder implementation.

Find Support

class zope.container.find.FindAdapter(context)

Bases: object

Adapts zope.container.interfaces.IReadContainer

find(id_filters=None, object_filters=None)

See IFind

class zope.container.find.SimpleIdFindFilter(ids)

Bases: object

Filter objects by ID

matches(id)

See INameFindFilter

class zope.container.find.SimpleInterfacesFindFilter(*interfaces)

Bases: object

Filter objects on the provided interfaces

Ordered

Ordered container implementation.

class zope.container.ordered.OrderedContainer

Bases: Persistent, Contained

OrderedContainer maintains entries’ order as added and moved.

>>> oc = OrderedContainer()
>>> int(IOrderedContainer.providedBy(oc))
1
>>> len(oc)
0

get(key, default=None)

See IOrderedContainer.

>>> oc = OrderedContainer()
>>> oc['foo'] = 'bar'
>>> oc.get('foo')
'bar'
>>> oc.get('funky', 'No chance, dude.')
'No chance, dude.'

has_key(key)

See IOrderedContainer.

>>> oc = OrderedContainer()
>>> oc['foo'] = 'bar'
>>> int('foo' in oc)
1
>>> int('quux' in oc)
0

items()

See IOrderedContainer.

>>> oc = OrderedContainer()
>>> oc.keys()
[]
>>> oc['foo'] = 'bar'
>>> oc.items()
[('foo', 'bar')]
>>> oc['baz'] = 'quux'
>>> oc.items()
[('foo', 'bar'), ('baz', 'quux')]
>>> int(len(oc._order) == len(oc._data))
1

keys()

See IOrderedContainer.

>>> oc = OrderedContainer()
>>> oc.keys()
[]
>>> oc['foo'] = 'bar'
>>> oc.keys()
['foo']
>>> oc['baz'] = 'quux'
>>> oc.keys()
['foo', 'baz']
>>> int(len(oc._order) == len(oc._data))
1

updateOrder(order)

See IOrderedContainer.

>>> oc = OrderedContainer()
>>> oc['foo'] = 'bar'
>>> oc['baz'] = 'quux'
>>> oc['zork'] = 'grue'
>>> oc.keys()
['foo', 'baz', 'zork']
>>> oc.updateOrder(['baz', 'foo', 'zork'])
>>> oc.keys()
['baz', 'foo', 'zork']
>>> oc.updateOrder(['baz', 'zork', 'foo'])
>>> oc.keys()
['baz', 'zork', 'foo']
>>> oc.updateOrder(['baz', 'zork', 'foo'])
>>> oc.keys()
['baz', 'zork', 'foo']
>>> oc.updateOrder(('zork', 'foo', 'baz'))
>>> oc.keys()
['zork', 'foo', 'baz']
>>> oc.updateOrder(['baz', 'zork'])
Traceback (most recent call last):
...
ValueError: Incompatible key set.
>>> oc.updateOrder(['foo', 'bar', 'baz', 'quux'])
Traceback (most recent call last):
...
ValueError: Incompatible key set.
>>> oc.updateOrder(1)
Traceback (most recent call last):
...
TypeError: order must be a tuple or a list.
>>> oc.updateOrder('bar')
Traceback (most recent call last):
...
TypeError: order must be a tuple or a list.
>>> oc.updateOrder(['baz', 'zork', 'quux'])
Traceback (most recent call last):
...
ValueError: Incompatible key set.
>>> del oc['baz']
>>> del oc['zork']
>>> del oc['foo']
>>> len(oc)
0

values()

See IOrderedContainer.

>>> oc = OrderedContainer()
>>> oc.keys()
[]
>>> oc['foo'] = 'bar'
>>> oc.values()
['bar']
>>> oc['baz'] = 'quux'
>>> oc.values()
['bar', 'quux']
>>> int(len(oc._order) == len(oc._data))
1

Sample

Sample container implementation.

This is primarily for testing purposes.

It might be useful as a mix-in for some classes, but many classes will need a very different implementation.

class zope.container.sample.SampleContainer

Bases: Contained

Sample container implementation suitable for testing.

It is not suitable, directly as a base class unless the subclass overrides _newContainerData to return a persistent mapping object.

get(key, default=None)

See interface IReadContainer

has_key(key)

See interface IReadContainer

items()

See interface IReadContainer

keys()

See interface IReadContainer

values()

See interface IReadContainer

Size

Adapters that give the size of an object.

class zope.container.size.ContainerSized(container)

Bases: object

Implements zope.size.interfaces.ISize for zope.container.interfaces.IReadContainer

sizeForDisplay()

See ISized

sizeForSorting()

See ISized

Traversal

Traversal components for containers

class zope.container.traversal.ContainerTraversable(container)

Bases: object

Traverses containers via getattr and get.

class zope.container.traversal.ContainerTraverser(container, request)

Bases: object

A traverser that knows how to look up objects by name in a container.

browserDefault(request)

See zope.publisher.browser.interfaces.IBrowserPublisher

publishTraverse(request, name)

See zope.publisher.interfaces.IPublishTraverse

class zope.container.traversal.ItemTraverser(container, request)

Bases: ContainerTraverser

A traverser that knows how to look up objects by name in an item container.

publishTraverse(request, name)

See zope.publisher.interfaces.IPublishTraverse