compare entities and parent/property lists

redo !155 (diffs)

src/doc/tutorials/complex_data_models.rst

@@ -75,3 +75,58 @@ Examples
    b = input("Press any key to cleanup.")
    # cleanup everything after the user presses any button.
    c.delete()
+
+
+Finding parents and properties
+--------
+To find a specific parent or property of an Entity, its
+ParentList or PropertyList can be filtered using names, ids, or
+entities. A short example:
+
+.. code-block:: python3
+
+   import linkahead as db
+
+   # Setup a record with four 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)
+   properties = r.properties
+
+   # As r only has one property with id 101, this returns a list containing only p1
+   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
+
+The filter function of ParentList works analogously.