ENH: add new member function filter to Container class

Summary

Allow Container objects to be filtered using ID, name or Entity.

Focus

We use a function that is already used by ParentList and PropertyList

Test Environment

pipelines

Check List for the Author

Please, prepare your MR for a review. Be sure to write a summary and a focus and create gitlab comments for the reviewer. They should guide the reviewer through the changes, explain your changes and also point out open questions. For further good practices have a look at our review guidelines

• All automated tests pass
• Reference related issues
• Up-to-date CHANGELOG.md (or not necessary)
• Up-to-date JSON schema (or not necessary)
• Appropriate user and developer documentation (or not necessary)
  • How do I use the software? Assume "stupid" users.
  • How do I develop or debug the software? Assume novice developers.
• Annotations in code (Gitlab comments)
  • Intent of new code
  • Problems with old code
  • Why this implementation?

Check List for the Reviewer

• I understand the intent of this MR
• All automated tests pass
• Up-to-date CHANGELOG.md (or not necessary)
• Appropriate user and developer documentation (or not necessary)
• The test environment setup works and the intended behavior is reproducible in the test environment
• In-code documentation and comments are up-to-date.
• Check: Are there specifications? Are they satisfied?

For further good practices have a look at our review guidelines.

src/doc/tutorials/complex_data_models.rst

@@ -78,7 +78,7 @@ Examples
 
 
 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:
@@ -100,7+100,7 @@
    properties = r.properties
 
    # As r only has one property with id 101, this returns a list containing only p1_1
    properties.filter(pid=101)
    # 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]
 
@@ -126,7+126,7 @@
    # Result: [p2_1]
 
 The filter function of ParentList works analogously.
+
+Finding entities in a Container
+-------------------------------
+In the same way as described above, Container can be filtered.
+A short example:
+
+.. code-block:: python3
+
+   import linkahead as db
+
+   # Setup a record with six properties
+   p1 = db.Property(id=101, name="Property 1")
+   p2 = db.Property(name="Property 2")
+   c = db.Container().extend([p1,p2])
+   c.filter(name="Property 1")
+   # Result: [p1]