schooltool.relationship is a library for managing arbitrary many-to-many binary relationships.
This package lets you define arbitrary many-to-many relationship schemas and use them to relate arbitrary components (that are annotatable or have an adapter to IRelationshipLinks).
Usage example:
# Establish a relationship
Membership(member=frog, group=frogpond)
# Find all related objects for a given role (URIGroup in this case)
for group in getRelatedObjects(frog, URIGroup):
print group
Membership.unlink(member=frog, group=frogpond)
You can also define relationship properties in your component classes, and rewrite the example above as:
# Establish a relationship
frogpond.members.add(frog) # or frog.groups.add(frogpond)
# Find all related objects for a given role (URIGroup in this case)
for group in frogpond.members:
print group
# Remove a relationship
frogpond.members.remove(frog) # or frog.groups.remove(frogpond)
Relationship types and roles are identified by URIs (the idea was borrowed from XLink and RDF). You can use strings containing those URIs directly, or you can use introspectable URI objects that also have an optional short name and a description in addition to the URI itself.
>>> from schooltool.relationship import URIObject
For example, a generic group membership relationship can be defined with the following URIs:
>>> URIMembership = URIObject('http://schooltool.org/ns/membership',
... 'Membership', 'The membership relationship.')
>>> URIGroup = URIObject('http://schooltool.org/ns/membership/group',
... 'Group', 'A role of a containing group.')
>>> URIMember = URIObject('http://schooltool.org/ns/membership/member',
... 'Member', 'A group member role.')
To demonstrate relationships we need some objects that can be related. Any object that has an adapter to IRelationshipLinks can be used in relationships. Since schooltool.relationship provides a default adapter from IAnnotatable to IRelationshipLinks, it is enough to declare that our objects are IAttributeAnnotatable.
>>> from zope.interface import implements
>>> from zope.annotation.interfaces import IAttributeAnnotatable
>>> class SomeObject(object):
... implements(IAttributeAnnotatable)
... def __init__(self, name):
... self._name = name
... def __repr__(self):
... return self._name
We need some setup to make Zope 3 annotations work.
>>> from zope.app.testing import setup
>>> setup.placelessSetUp()
>>> setup.setUpAnnotations()
We need to define the adapter from IAnnotatable to IRelationshipLinks. In real life you would include the ZCML configuration of the schooltool.relationship package via Zope 3 package includes. In a test you can use setUpRelationships from schooltool.relationship.tests.
>>> from schooltool.relationship.tests import setUpRelationships
>>> setUpRelationships()
You can create relationships by calling the relate function
>>> from schooltool.relationship import relate
>>> frogs = SomeObject('frogs')
>>> frogger = SomeObject('frogger')
>>> relate(URIMembership, (frogs, URIGroup), (frogger, URIMember))
Since you will always want to use a particular set of roles for a given relationship type, you can define a relationship schema and use it as a shortcut:
>>> from schooltool.relationship import RelationshipSchema
>>> Membership = RelationshipSchema(URIMembership, group=URIGroup,
... member=URIMember)
>>> lilfroggy = SomeObject('lilfroggy')
>>> Membership(member=lilfroggy, group=frogs)
If you try to create the same relationship between the same objects more than once, you will get a DuplicateRelationship exception.
>>> Membership(member=lilfroggy, group=frogs)
Traceback (most recent call last):
...
DuplicateRelationship
You can query relationships by calling the getRelatedObjects function. It returns a list of objects in undefined order, so we’ll define a function to sort them alphabetically:
>>> def sorted(list):
... items = [(repr(item), item) for item in list]
... items.sort()
... return [row[-1] for row in items]
For example, you can get a list of all members of the “frogs” group like this:
>>> from schooltool.relationship import getRelatedObjects
>>> sorted(getRelatedObjects(frogs, URIMember))
[frogger, lilfroggy]
The relationship is bidirectional, so you can ask an object what groups it belongs to
>>> getRelatedObjects(frogger, URIGroup)
[frogs]
You can also explicitly say that you want all URIGroup‘s that participate in a URIMembership relationship.
>>> getRelatedObjects(frogger, URIGroup, URIMembership)
[frogs]
>>> getRelatedObjects(frogger, URIGroup, 'example:Groupship')
[]
In general, avoid reusing the same role for different relationship types.
You can remove relationships by calling the unrelate function:
>>> from schooltool.relationship import unrelate
>>> unrelate(URIMembership, (frogs, URIGroup), (frogger, URIMember))
>>> getRelatedObjects(frogger, URIGroup)
[]
>>> getRelatedObjects(frogs, URIMember)
[lilfroggy]
If you try to remove a relationship that does not exist, you will get an exception
>>> unrelate(URIMembership, (frogs, URIMember), (frogger, URIGroup))
Traceback (most recent call last):
...
NoSuchRelationship
If you have a relationship schema, you can call its unlink method, as a shortcut for the full unrelate call.
>>> Membership.unlink(member=lilfroggy, group=frogs)
>>> getRelatedObjects(frogs, URIMember)
[]
There is also an unrelateAll function that removes all relationships of an object. It is useful if you want to break all relationships when deleting an object.
You can define a property in a class and use it instead of explicitly calling global functions and passing roles around:
>>> from schooltool.relationship import RelationshipProperty
>>> class Group(SomeObject):
... members = RelationshipProperty(URIMembership, URIGroup, URIMember)
>>> class Member(SomeObject):
... groups = RelationshipProperty(URIMembership, URIMember, URIGroup)
Usage example:
>>> fido = Member('fido')
>>> dogs = Group('dogs')
>>> list(fido.groups)
[]
>>> list(dogs.members)
[]
>>> bool(fido.groups)
False
>>> dogs.members.add(fido)
>>> list(fido.groups)
[dogs]
>>> list(dogs.members)
[fido]
>>> bool(fido.groups)
True
>>> len(fido.groups)
1
>>> fido.groups.remove(dogs)
>>> list(fido.groups)
[]
>>> list(dogs.members)
[]
>>> import zope.event
>>> old_subscribers = zope.event.subscribers
>>> zope.event.subscribers = []
Before you establish a relationship, a BeforeRelationshipEvent is sent out. You can implement constraints by raising an exception in an event subscriber:
>>> from zope.interface import Interface, directlyProvides
>>> class IFrog(Interface):
... pass
>>> from schooltool.relationship.interfaces import IBeforeRelationshipEvent
>>> def no_toads(event):
... if (IBeforeRelationshipEvent.providedBy(event) and
... event.rel_type == URIMembership and
... event[URIGroup] is frogs and
... not IFrog.providedBy(event[URIMember])):
... raise Exception("Only frogs can be members of the frogs group")
>>> zope.event.subscribers.append(no_toads)
>>> toady = SomeObject('toady')
>>> Membership(member=toady, group=frogs)
Traceback (most recent call last):
...
Exception: Only frogs can be members of the frogs group
When you establish a relationship, a RelationshipAddedEvent is sent out:
>>> from schooltool.relationship.interfaces import IRelationshipAddedEvent
>>> def my_subscriber(event):
... if IRelationshipAddedEvent.providedBy(event):
... print 'Relationship %s added between %s (%s) and %s (%s)' % (
... event.rel_type.name,
... event.participant1, event.role1.name,
... event.participant2, event.role2.name)
... if event.extra_info:
... print '(BTW, %s)' % event.extra_info
>>> zope.event.subscribers.append(my_subscriber)
>>> kermit = SomeObject('kermit')
>>> directlyProvides(kermit, IFrog)
>>> Membership(member=kermit, group=frogs)
Relationship Membership added between kermit (Member) and frogs (Group)
Before you break a relationship, a BeforeRemovingRelationshipEvent is sent out. You can implement constraints by raising exceptions in the subscriber (e.g. prevent members from leaving a group before they do something they have to do).
When you break a relationship, a RelationshipRemovedEvent is sent out:
>>> from schooltool.relationship.interfaces \
... import IBeforeRemovingRelationshipEvent
>>> from schooltool.relationship.interfaces \
... import IRelationshipRemovedEvent
>>> def my_subscriber(event):
... if IBeforeRemovingRelationshipEvent.providedBy(event):
... if (event.rel_type == URIMembership
... and event[URIMember] is kermit):
... print "Please don't leave us!"
... if IRelationshipRemovedEvent.providedBy(event):
... print 'Relationship %s between %s (%s) and %s (%s) removed' % (
... event.rel_type.name,
... event.participant1, event.role1.name,
... event.participant2, event.role2.name)
... if event.extra_info:
... print '(BTW, %s)' % event.extra_info
>>> zope.event.subscribers.append(my_subscriber)
>>> Membership.unlink(member=kermit, group=frogs)
Please don't leave us!
Relationship Membership between kermit (Member) and frogs (Group) removed
Symmetric relationships work too:
>>> URIFriendship = URIObject('example:Friendship', 'Friendship')
>>> URIFriend = URIObject('example:Friend', 'Friend')
>>> Friendship = RelationshipSchema(URIFriendship,
... one=URIFriend, other=URIFriend)
>>> Friendship(one=fido, other=kermit)
Relationship Friendship added between kermit (Friend) and fido (Friend)
>>> class FriendlyObject(SomeObject):
... friends = RelationshipProperty(URIFriendship, URIFriend, URIFriend)
>>> neko = FriendlyObject('neko')
>>> neko.friends.add(kermit)
Relationship Friendship added between neko (Friend) and kermit (Friend)
>>> list(neko.friends)
[kermit]
>>> sorted(getRelatedObjects(kermit, URIFriend))
[fido, neko]
Note that if you use symmetric relationships, you cannot use __getitem__ on IBeforeRelationshipEvent‘s.
Sometimes you may want to attach some extra information to a relationship (e.g. a label). You can do so by passing an extra argument to relate and unrelate:
>>> relate(URIFriendship, (kermit, URIFriend), (frogger, URIFriend),
... 'kermit and frogger know each other for years')
Relationship Friendship added between kermit (Friend) and frogger (Friend)
(BTW, kermit and frogger know each other for years)
This extra argument should be either a read-only object, or a subclass of persistent.Persistent, because references to this object will be stored from both relationship sides.
You can access this extra information from relationship links directly:
>>> from schooltool.relationship.interfaces import IRelationshipLinks
>>> for link in IRelationshipLinks(kermit):
... if link.extra_info:
... print link.extra_info
kermit and frogger know each other for years
Since this is very inconvenient, I expect you will write your own access properties that mimic RelationshipProperty, and override the __iter__ method. For example:
>>> from schooltool.relationship.relationship import BoundRelationshipProperty
>>> class FriendshipProperty(object):
... def __get__(self, instance, owner):
... if instance is None: return self
... return BoundFriendshipProperty(instance)
>>> class BoundFriendshipProperty(BoundRelationshipProperty):
... def __init__(self, this):
... BoundRelationshipProperty.__init__(self, this, URIFriendship,
... URIFriend, URIFriend)
... def __iter__(self):
... for link in IRelationshipLinks(self.this):
... if link.role == self.other_role and link.rel_type == self.rel_type:
... yield link.target, link.extra_info
You can then use it like this:
>>> class Friend(SomeObject):
... friends = FriendshipProperty()
>>> fluffy = Friend('fluffy')
>>> fluffy.friends.add(kermit,
... 'fluffy just met kermit, but fluffy is very friendly')
Relationship Friendship added between fluffy (Friend) and kermit (Friend)
(BTW, fluffy just met kermit, but fluffy is very friendly)
>>> for friend, extra_info in fluffy.friends:
... print '%s: %s' % (friend, extra_info)
kermit: fluffy just met kermit, but fluffy is very friendly
As you see, the extra info is accessible to all event handlers
>>> fluffy.friends.remove(kermit)
Relationship Friendship between fluffy (Friend) and kermit (Friend) removed
(BTW, fluffy just met kermit, but fluffy is very friendly)
When you delete objects, you should remove all relationships for those objects. If you use Zope 3 objects events, you can register the unrelateOnDeletion event handler from schooltool.relationship.objectevents. configure.zcml of schooltool.relationship does that.
When you copy objects (e.g. using Zope’s IObjectCopier), you should take care to ensure that you do not duplicate just one half of relationship links. It is tricky. locationCopy from zope.location.pickling performs deep copies of all objects that are located within the object you are copying. It works if all relationships are within this subtree (or outside it). You will get problems if you have a relationship between an object that is copied and another object that is not copied.
You can register the unrelateOnCopy event handler from schooltool.relationship.objectevents to solve part of the problem (configure.zcml of schooltool.relationship does that). This event handler removes all relationships from the copy of the object that you are copying. It does not traverse the whole deply-copied subtree, therefore if you have subobjects that participate in relationships with objects outside of the subtree, you will have problems.
An alternative solution is to disallow copying of objects that may have subobjects related with other objects that are not located within the original object. To do so, declare and IObjectCopier adapter for the object and make the copyable method return False.