Merge branch 'f-enh-143-xlsx-export-with-props' into 'dev'

FEAT: `resolve_references` parameter

See merge request !188

CHANGELOG.md

@@ -10,7 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added ###
 
 - convenience functions `value_matches_versionid`, `get_id_from_versionid` and `get_versionid`
-- Parameter for high level API serialization to output a plain JSON.
+- High level API: Parameter for serialization to output a plain JSON.
+- High level API: Parameter to resolve references when converting to Python object.
 
 ### Changed ###
 

src/linkahead/high_level_api.py

@@ -4,9 +4,10 @@
 #
 # Copyright (C) 2018 Research Group Biomedical Physics,
 # Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+# Copyright (C) 2020-2022,2025 IndiScale GmbH <info@indiscale.com>
 # Copyright (C) 2020 Timm Fitschen <t.fitschen@indiscale.com>
-# Copyright (C) 2020-2022 IndiScale GmbH <info@indiscale.com>
 # Copyright (C) 2022 Alexander Schlemmer <alexander.schlemmer@ds.mpg.de>
+# Copyright (C) 2025 Daniel Hornung <d.hornung@indiscale.com>
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Affero General Public License as
@@ -21,8 +22,7 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program. If not, see <https://www.gnu.org/licenses/>.
 #
-# ** end header
-#
+
 # type: ignore
 """
 A high level API for accessing LinkAhead entities from within python.
@@ -974,26 +974,32 @@ def convert_to_entity(python_object):
 def convert_to_python_object(entity: Union[db.Container, db.Entity],
                              references: Optional[db.Container] = None,
                              visited: Optional[Dict[int,
-                                                    "CaosDBPythonEntity"]] = None):
+                                                    "CaosDBPythonEntity"]] = None,
+                             resolve_references: Optional[bool] = False,
+                             ):
     """
     Convert either a container of CaosDB entities or a single CaosDB entity
     into the high level representation.
 
-    The optional second parameter can be used
+    The optional ``references`` parameter can be used
     to resolve references that occur in the converted entities and resolve them
     to their correct representations. (Entities that are not found remain as
-    CaosDBPythonUnresolvedReferences.)
+    CaosDBPythonUnresolvedReferences, unless ``resolve_references`` is given and True.)
     """
     if isinstance(entity, db.Container):
         # Create a list of objects:
-        return [convert_to_python_object(i, references, visited) for i in entity]
+        return [convert_to_python_object(ent, references=references, visited=visited,
+                                         resolve_references=resolve_references) for ent in entity]
 
     # TODO: recursion problems?
-    return _single_convert_to_python_object(
+    converted = _single_convert_to_python_object(
         high_level_type_for_standard_type(entity)(),
         entity,
         references,
         visited)
+    if resolve_references:
+        converted.resolve_references(True, references)
+    return converted
 
 
 def new_high_level_entity(entity: db.RecordType,
@@ -1077,8 +1083,6 @@ def query(query: str,
 
     """
     res = db.execute_query(query)
-    objects = convert_to_python_object(res)
-    if resolve_references:
-        for obj in objects:
-            obj.resolve_references(True, references)
+    objects = convert_to_python_object(res, references=references,
+                                       resolve_references=resolve_references)
     return objects