Author: jmorliaguet
Date: Tue Jun  6 13:10:54 2006
New Revision: 3335

Modified:
   cpsskins/branches/paris-sprint-2006/relations/README.txt
   cpsskins/branches/paris-sprint-2006/storage/relations.py
   cpsskins/branches/paris-sprint-2006/tests/test_relations.py

Log:

- expanded the README.txt



Modified: cpsskins/branches/paris-sprint-2006/relations/README.txt
==============================================================================
--- cpsskins/branches/paris-sprint-2006/relations/README.txt    (original)
+++ cpsskins/branches/paris-sprint-2006/relations/README.txt    Tue Jun  6 
13:10:54 2006
@@ -1,14 +1,67 @@
 
 $id$
 
-This package contains the definition of relations, including
+=========
+RELATIONS
+=========
 
-- relates
+This package provides basic definitions for creating relations between objects.
 
-- predicates (simple and compound predicates)
+Anything that is relatable can be set in relation with other objects.
 
-- monadic, dyadic, triadic relations
+A relatable object only needs to have a string representation:
 
+    >>> from zope.interface import implements
+    >>> from cpsskins.relations.interfaces import IRelatable
 
-It also provides a tool for accessing and querying a relation storage.
+    >>> class Relate(object):
+    ...     implements(IRelatable)
+    ...     def __init__(self, name=u''):
+    ...         self.name = name
+    ...     def __str__(self):
+    ...         return name
 
+Even string objects are relatable.
+
+A relation consists of a 'predicate' and a collection of related objects
+called the 'relates'.
+
+There are three basic forms of relations:
+
+    - 'monadic relations' that connect an object with itself using monadic
+    predicates.
+
+    - 'dyadic relations' that connect a first object with a second object
+      using dyadic predicates.
+
+    - 'triadic relations' that connect a first object with a second object
+      through a third object using triadic predicates.
+
+
+The string representation of predicates contains underscores (_) to represent
+the related objects:
+
+    >>> from cpsskins.relations import Predicate
+
+    >>> p = Predicate(u'_ is in relation with _')
+    >>> print p
+    _ is in relation with _
+
+We can get the number of objects that the predicate can connect:
+
+    >>> len(p)
+    2
+
+To create a relation we need to specify a predicate and a set of relates:
+
+    >>> from cpsskins.relations import DyadicRelation
+
+    >>> relation = DyadicRelation(predicate=p, first=u'A', second=u'B')
+    >>> print repr(relation)
+    <Dyadic relation: 'u'A' is in relation with u'B''>
+
+    >>> print relation.first
+    A
+
+    >>> print relation.second
+    B

Modified: cpsskins/branches/paris-sprint-2006/storage/relations.py
==============================================================================
--- cpsskins/branches/paris-sprint-2006/storage/relations.py    (original)
+++ cpsskins/branches/paris-sprint-2006/storage/relations.py    Tue Jun  6 
13:10:54 2006
@@ -87,10 +87,19 @@
     True
 
     >>> storage = RelationStorage()
-    >>> from cpsskins.relations import TestRelate as Relate, \
-        Predicate, MonadicRelation, DyadicRelation, TriadicRelation
+
+    >>> from cpsskins.relations import Predicate, MonadicRelation
+    >>> from cpsskins.relations import DyadicRelation, TriadicRelation
     >>> from cpsskins.relations.interfaces import IRelatable
 
+    >>> class Relate:
+    ...     implements(IRelatable)
+    ...     def __init__(self, name=u''):
+    ...         self.name = name
+    ...     def __str__(self):
+    ...         return self.name
+
+    >>> first = Relate('snow')
     >>> first = Relate(u'this')
     >>> second = Relate(u'that')
     >>> predicate = Predicate(u'_ depends on _')

Modified: cpsskins/branches/paris-sprint-2006/tests/test_relations.py
==============================================================================
--- cpsskins/branches/paris-sprint-2006/tests/test_relations.py (original)
+++ cpsskins/branches/paris-sprint-2006/tests/test_relations.py Tue Jun  6 
13:10:54 2006
@@ -19,12 +19,13 @@
 
 import unittest
 
-from zope.testing.doctestunit import DocTestSuite
+from zope.testing.doctestunit import DocTestSuite, DocFileSuite
 
 def test_suite():
     return unittest.TestSuite((
         DocTestSuite('cpsskins.relations.relations'),
         DocTestSuite('cpsskins.relations.predicates'),
+        DocFileSuite('../relations/README.txt'),
         ))
 
 if __name__ == '__main__':
-- 
http://lists.nuxeo.com/mailman/listinfo/z3lab-checkins

Reply via email to