compare entities and parent/property lists

redo !155 (diffs)

src/doc/tutorials/complex_data_models.rst

@@ -51,18 +51,18 @@ Examples
    # Very complex part of the data model:
    # Case 1: File added to another file
    f2.add_property(p1, value=f1)  # this adds a file property with value first file
-		                  # to the second file
+                          # to the second file
 
    # Case 2: Property added to a property
    p2.add_property(p3, value=27)  # this adds an integer property with value 27 to the
-		                  # double property
+                          # double property
 
    # Case 3: Reference property added to a property
    # The property p2 now has two sub properties, one is pointing to
    # record p2 which itself has the property p2, therefore this can be
    # considered a loop in the data model.
    p2.add_property(p4, value=r2)  # this adds a reference property pointing to
-		                  # record 2 to the double property
+                          # record 2 to the double property
 
    # Insert a container containing all the newly created entities:
    c = db.Container().extend([rt1, rt2, r1, r2, f1, p1, p2, p3, f2, p4])
@@ -87,46 +87,42 @@ entities. A short example:
 
    import linkahead as db
 
-   # Setup a record with four properties
+   # Setup a record with six properties
    r = db.Record()
-   p1 = db.Property(id=101, name="Property 1")
-   p2 = db.Property(id=102, name="Property 2")
-   p3_1 = db.Property(id=103, name="Property 3")
-   p3_2 = db.Property(id=103, name="Property 3")
-   p4 = db.Property(name="Property")
-   p5 = db.Property(name="Property")
-   r.add_property(p1).add_property(p2).add_property(p3_1)
-   r.add_property(p3_2).add_property(p4).add_property(p5)
+   p1_1 = db.Property(id=101, name="Property 1")
+   p1_2 = db.Property(name="Property 1")
+   p2_1 = db.Property(id=102, name="Property 2")
+   p2_2 = db.Property(id=102)
+   p2_3 = db.Property(id=102, name="Other Property")
+   p3 = db.Property(id=104, name="Other Property")
+   r.add_property(p1_1).add_property(p1_2).add_property(p2_1)
+   r.add_property(p2_2).add_property(p2_3).add_property(p3)
    properties = r.properties
 
-   # As r only has one property with id 101, this returns a list containing only p1
+   # As r only has one property with id 101, this returns a list containing only p1_1
    properties.filter(pid=101)
-   # Result: [p1]
-
-   # Filtering with name="Property" returns both p4 and p5, as they share their name
-   properties.filter(name="Property")
-   # Result: [p4, p5]
-
-   # Filtering with name="Property 1" and id=102 returns both p1 and p2, because
-   # any property matching either criterion is returned:
-   properties.filter(name="Property 1", pid="102")
-   # Result: [p1, p2]
-
-   p6 = db.Property(name="Property 2")
-   r.add_property(p6)
-   # If we want to find properties matching one specific property, we can also filter using
-   # the entity itself. In this case, only properties matching both name and id are returned,
-   # as long as both are set.
-   properties.filter(p2)
-   # Result: [p2]
-   # As p6 does not have an id yet, both candidates matching its name are returned
-   properties.filter(p6)
-   # Result: [p2, p6]
-   # Similarly if we match using name and id parameters, all candidates matching either are returned
-   properties.filter(name=p2.name, pid=p2.id)
-   # Result: [p2, p6], because p2 and p6 share a name
-   # And if both name and id match, there may also be several results when matching an entity
-   properties.filter(p3_1)
-   # Result: [p3_1, p3_2], because they share both their name and id
+   # Result: [p1_1]
+
+   # Filtering with name="Property 1" returns both p1_1 and p1_2, as they share their name
+   properties.filter(name="Property 1")
+   # Result: [p1_1, p1_2]
+
+   #  If both name and pid are given, matching is based only on pid for all entities that have an id
+   properties.filter(pid="102", name="Other Property")
+   # Result: [p2_1, p2_2, p2_3]
+
+   # However, filtering with name="Property 1" and id=101 returns both p1_1 and p1_2, because
+   # p1_2 does not have an id and matches the name
+   properties.filter(pid="101", name="Property 1")
+   # Result: [p1_1, p1_2]
+
+   # We can also filter using an entity, in which case the name and id of the entity are used:
+   properties.filter(pid="102", name="Property 2") == properties.filter(p2_1)
+   # Result: True
+
+   # If we only need properties that match both id and name, we can set the parameter
+   # conjunction to True:
+   properties.filter(pid="102", name="Property 2", conjunction=True)
+   # Result: [p2_1]
 
 The filter function of ParentList works analogously.