Draft: refactor compare_entities and enhance test coverage

Summary

So far the compare_entities function was experimental. This MR removes that flag after refactoring and adding tests.

Focus

• Please pay attention to in code documentation: Is it easy to understand? Is it up to date?
• Please check out the test coverage. Do you think it is sufficient?

Test Environment

unit and integration tests

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 #206 (closed)
• 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

@@ -75,55 +75,3 @@ 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 = db.Property(name="Property")
-   p4 = db.Property(name="Property")
-   r.add_property(p1).add_property(p2).add_property(p3).add_property(p4)
-   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 p3 and p4, as they share their name
-   properties.filter(name="Property")
-   # Result: [p3, p4]
-
-   # 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]
-
-   # 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:
-   p5 = db.Property(name="Property 2")
-   r.add_property(p5)
-   properties.filter(p5)
-   # Result: [p5]
-   properties.filter(name=p5.name, pid=p5.id)
-   # Result: [p2, p5], because p2 and p5 share a name
-   properties.filter(p3)
-   # Result: [p3, p4], because p3 and p4 share both their name and id
-
-   # However, if you want to retrieve only instances of the property itself, this can be
-   # done using the parameter check_equality, which enforces that all entities in the returned
-   # list are equal to the parameter.
-   properties.filter(p3, check_equality=True)
-   # Result: [p3]
-
-The filter function of ParentList works analogously.