Merge branch 'f-role' into 'dev'

Opt-in linkahead package to mypy type checking

See merge request !140

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `Entity.update_acl` now supports optional `**kwargs` that are passed to the
   `Entity.update` method that is called internally, thus allowing, e.g.,
   updating the ACL despite possible naming collisions with `unique=False`.
+* a `role` argument for `get_entity_by_name` and `get_entity_by_id`
 
 ### Changed ###
 

src/linkahead/utils/get_entity.py

@@ -21,29 +21,33 @@
 
 """Convenience functions to retrieve a specific entity."""
 
-from typing import Union
+from typing import Union, Optional
 
 from ..common.models import Entity, execute_query
 from .escape import escape_squoted_text
 
 
-def get_entity_by_name(name: str) -> Entity:
+def get_entity_by_name(name: str, role: Optional[str] = None) -> Entity:
     """Return the result of a unique query that uses the name to find the correct entity.
 
     Submits the query "FIND ENTITY WITH name='{name}'".
     """
     name = escape_squoted_text(name)
+    if role is None:
+        role = "ENTITY"
     # type hint can be ignored, it's a unique query, so never Container or int
-    return execute_query(f"FIND ENTITY WITH name='{name}'", unique=True)  # type: ignore
+    return execute_query(f"FIND {role} WITH name='{name}'", unique=True)  # type: ignore
 
 
-def get_entity_by_id(eid: Union[str, int]) -> Entity:
+def get_entity_by_id(eid: Union[str, int], role: Optional[str] = None) -> Entity:
     """Return the result of a unique query that uses the id to find the correct entity.
 
     Submits the query "FIND ENTITY WITH id='{eid}'".
     """
+    if role is None:
+        role = "ENTITY"
     # type hint can be ignored, it's a unique query
-    return execute_query(f"FIND ENTITY WITH id='{eid}'", unique=True)  # type: ignore
+    return execute_query(f"FIND {role} WITH id='{eid}'", unique=True)  # type: ignore
 
 
 def get_entity_by_path(path: str) -> Entity: