Add info to docstrings that type can be used as selector for object_tree module (#56)

* Fix comment inside _is_matching function
* Add information to docstring that type is supported as a selector
* Update doc string squape/object_tree.py
* Clarify doc strings for object_tree module
* Update squape/object_tree.py doc string

Co-authored-by: Jakub <[email protected]>

Author: pawtom

squape/object_tree.py

@@ -26,11 +26,16 @@ def children(object_or_name: any, selector: dict) -> tuple:
         object_or_name (any): symbolic name, real name, or object reference.
 
         selector (dict): The selector is a dictionary of key-value pairs,
-            where a key is a property of an object, and value is expected value.
+            The selector is a dictionary consisting of key-value pairs.
+            In this dictionary:  
+            - Each key represents a property of an object.  
+            - Each value can either be an expected value for that property
+            or a function that takes exactly one argument.
+
+            Additionally, the dictionary can have a key 'type'
+            where the value should be the expected object type.
             An object will pass verification
             if the object's property value matches the selector value.
-            Selectors may include functions.
-            The passed functions must accept exactly one argument.
 
     Returns:
         Children objects that met the selector criteria.
@@ -62,11 +67,11 @@ def find(object_or_name: any, selector: dict = None, max_depth: int = None) -> t
         object_or_name (any): symbolic name, real name, or object reference.
 
         selector (dict, optional): The selector is a dictionary of key-value pairs,
-            where a key is a property of an object, and value is expected value.
+            where a key is a property of an object  and value is expected value
+            or function. The passed functions must accept exactly one argument.
+            Accepted key is also 'type' and then value should by object type.
             An object will pass verification
             if the object's property value matches the selector value.
-            Selectors may include functions.
-            The passed functions must accept exactly one argument.
             Defaults to {}, which means all objects pass the verification.
 
         max_depth (int): defines maximum depth in the object structure that should be
@@ -122,11 +127,11 @@ def find_ancestor(object_or_name: any, selector: dict):
         object_or_name (any): symbolic name, real name, or object reference.
 
         selector (dict): The selector is a dictionary of key-value pairs,
-            where a key is a property of an object, and value is expected value.
+            where a key is a property of an object  and value is expected value
+            or function. The passed functions must accept exactly one argument.
+            Accepted key is also 'type' and then value should by object type.
             An object will pass verification
             if the object's property value matches the selector value.
-            Selectors may include functions.
-            The passed functions must accept exactly one argument.
 
     Returns:
         (Squish object / None): The ancestor object that matches the selector.
@@ -168,11 +173,11 @@ def siblings(object_or_name: any, selector: dict = None) -> tuple:
         object_or_name (any): symbolic name, real name, or object reference.
 
         selector (dict, optional): The selector is a dictionary of key-value pairs,
-            where a key is a property of an object, and value is expected value.
+            where a key is a property of an object  and value is expected value
+            or function. The passed functions must accept exactly one argument.
+            Accepted key is also 'type' and then value should by object type.
             An object will pass verification
             if the object's property value matches the selector value.
-            Selectors may include functions.
-            The passed functions must accept exactly one argument.
             Defaults to {}, which means all objects pass the verification.
 
     Returns:
@@ -213,11 +218,11 @@ def _is_matching(object_or_name: any, selector: dict) -> bool:
         object_or_name (any): symbolic name, real name, or object reference.
 
         selector (dict, optional): The selector is a dictionary of key-value pairs,
-            where a key is a property of an object, and value is expected value.
+            where a key is a property of an object  and value is expected value
+            or function. The passed functions must accept exactly one argument.
+            Accepted key is also 'type' and then value should by object type.
             An object will pass verification
             if the object's property value matches the selector value.
-            Selectors may include functions.
-            The passed functions must accept exactly one argument.
             Defaults to {}, which means all objects pass the verification.
 
     Returns:
@@ -241,7 +246,7 @@ def _is_matching(object_or_name: any, selector: dict) -> bool:
             # object has given attribute
             attr = getattr(object_reference, key)
             if isinstance(expected_value, types.FunctionType):
-                # The key is a lambda function
+                # The expected_value is a lambda function
                 lambda_function = expected_value
                 lambda_result = lambda_function(attr)
                 if not isinstance(lambda_result, bool):