project.assign_declaration - support batching #4474

src/ifcopenshell-python/ifcopenshell/api/__init__.py

@@ -117,6 +117,9 @@ ARGUMENTS_DEPRECATION = {
     "constraint.unassign_constraint": partial(
         batching_argument_deprecation, prev_argument="product", new_argument="products"
     ),
+    "project.assign_declaration": partial(
+        batching_argument_deprecation, prev_argument="definition", new_argument="definitions"
+    ),
 }
 
 

src/ifcopenshell-python/ifcopenshell/api/project/append_asset.py

@@ -61,7 +61,7 @@ class Usecase:
             root = ifcopenshell.api.run("root.create_entity", library, ifc_class="IfcProject", name="Demo Library")
             context = ifcopenshell.api.run("root.create_entity", library,
                 ifc_class="IfcProjectLibrary", name="Demo Library")
-            ifcopenshell.api.run("project.assign_declaration", library, definition=context, relating_context=root)
+            ifcopenshell.api.run("project.assign_declaration", library, definitions=[context], relating_context=root)
 
             # Assign units for our example library
             unit = ifcopenshell.api.run("unit.add_si_unit", library,
@@ -80,7 +80,7 @@ class Usecase:
 
             # Mark our wall type as a reusable asset in our library.
             ifcopenshell.api.run("project.assign_declaration", library,
-                definition=wall_type, relating_context=context)
+                definitions=[wall_type], relating_context=context)
 
             # Let's imagine we're starting a new project
             model = ifcopenshell.api.run("project.create_file")

src/ifcopenshell-python/ifcopenshell/api/project/assign_declaration.py

@@ -18,11 +18,18 @@
 
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.util.element
+from typing import Union
 
 
 class Usecase:
-    def __init__(self, file, definition=None, relating_context=None):
-        """Declares an element to the project
+    def __init__(
+        self,
+        file: ifcopenshell.entity_instance,
+        definitions: list[ifcopenshell.entity_instance],
+        relating_context: ifcopenshell.entity_instance,
+    ):
+        """Declares the list of elements to the project
 
         All data in a model must be directly or indirectly related to the
         project. Most data is indirectly related, existing instead within the
@@ -35,13 +42,14 @@ class Usecase:
         project libraries for future use (such as an assets library). Assigning
         a declaration lets you say that an object belongs to a library.
 
-        :param definition: The object you want to declare. Typically an asset.
-        :type definition: ifcopenshell.entity_instance.entity_instance
+        :param definitions: The list of objects you want to declare. Typically a list of assets.
+        :type definitions: list[ifcopenshell.entity_instance.entity_instance]
         :param relating_context: The IfcProject, or more commonly the
             IfcProjectLibrary that you want the object to be part of.
         :type relating_context: ifcopenshell.entity_instance.entity_instance
-        :return: The new IfcRelDeclares relationship
-        :rtype: ifcopenshell.entity_instance.entity_instance
+        :return: The new IfcRelDeclares relationship or None if all definitions
+            were already declared / do not support declaration.
+        :rtype: Union[ifcopenshell.entity_instance.entity_instance, None]
 
         Example:
 
@@ -54,7 +62,7 @@ class Usecase:
                 ifc_class="IfcProjectLibrary", name="Demo Library")
 
             # It's necessary to say our library is part of our project.
-            ifcopenshell.api.run("project.assign_declaration", library, definition=context, relating_context=root)
+            ifcopenshell.api.run("project.assign_declaration", library, definitions=[context], relating_context=root)
 
             # Assign units for our example library
             unit = ifcopenshell.api.run("unit.add_si_unit", library,
@@ -73,45 +81,61 @@ class Usecase:
 
             # Mark our wall type as a reusable asset in our library.
             ifcopenshell.api.run("project.assign_declaration", library,
-                definition=wall_type, relating_context=context)
+                definitions=[wall_type], relating_context=context)
 
             # All done, just for fun let's save our asset library to disk for later use.
             library.write("/path/to/my-library.ifc")
         """
         self.file = file
         self.settings = {
-            "definition": definition,
+            "definitions": definitions,
             "relating_context": relating_context,
         }
 
-    def execute(self):
-        declares = None
-        if self.settings["relating_context"].Declares:
-            declares = self.settings["relating_context"].Declares[0]
+    def execute(self) -> Union[ifcopenshell.entity_instance, None]:
+        relating_context = self.settings["relating_context"]
+        all_declares = relating_context.Declares
+        definitions = set(self.settings["definitions"])
 
-        if not hasattr(self.settings["definition"], "HasContext"):
-            return
+        previous_declares_rels: set[ifcopenshell.entity_instance] = set()
+        objects_without_contexts: list[ifcopenshell.entity_instance] = []
+        objects_with_contexts: list[ifcopenshell.entity_instance] = []
 
-        has_context = None
-        if self.settings["definition"].HasContext:
-            has_context = self.settings["definition"].HasContext[0]
+        # check if there is anything to change
+        for definition in definitions:
+            has_context = getattr(definition, "HasContext", None)
+            if has_context is None:
+                continue
 
-        if has_context and has_context == declares:
-            return
+            object_rel = next(iter(has_context), None)
+            if object_rel is None:
+                objects_without_contexts.append(definition)
+                continue
 
-        if has_context:
-            related_definitions = list(has_context.RelatedDefinitions)
-            related_definitions.remove(self.settings["definition"])
+            # either rel doesn't exist or product is part of different rel
+            if object_rel not in all_declares:
+                previous_declares_rels.add(object_rel)
+                objects_with_contexts.append(definition)
+
+        objects_to_change = objects_without_contexts + objects_with_contexts
+        # nothing to change
+        if not objects_to_change:
+            return None
+
+        for has_context in previous_declares_rels:
+            related_definitions = set(has_context.RelatedDefinitions) - objects_with_contexts
             if related_definitions:
                 has_context.RelatedDefinitions = related_definitions
                 ifcopenshell.api.run("owner.update_owner_history", self.file, **{"element": has_context})
             else:
+                history = has_context.OwnerHistory
                 self.file.remove(has_context)
+                if history:
+                    ifcopenshell.util.element.remove_deep2(self.file, history)
 
+        declares = next(iter(all_declares), None)
         if declares:
-            related_definitions = set(declares.RelatedDefinitions)
-            related_definitions.add(self.settings["definition"])
-            declares.RelatedDefinitions = list(related_definitions)
+            declares.RelatedDefinitions = list(set(declares.RelatedDefinitions) | set(objects_to_change))
             ifcopenshell.api.run("owner.update_owner_history", self.file, **{"element": declares})
         else:
             declares = self.file.create_entity(
@@ -119,8 +143,8 @@ class Usecase:
                 **{
                     "GlobalId": ifcopenshell.guid.new(),
                     "OwnerHistory": ifcopenshell.api.run("owner.create_owner_history", self.file),
-                    "RelatedDefinitions": [self.settings["definition"]],
-                    "RelatingContext": self.settings["relating_context"],
+                    "RelatedDefinitions": list(objects_to_change),
+                    "RelatingContext": relating_context,
                 }
             )
         return declares

src/ifcopenshell-python/ifcopenshell/api/project/unassign_declaration.py

@@ -46,7 +46,7 @@ class Usecase:
                 ifc_class="IfcProjectLibrary", name="Demo Library")
 
             # It's necessary to say our library is part of our project.
-            ifcopenshell.api.run("project.assign_declaration", library, definition=context, relating_context=root)
+            ifcopenshell.api.run("project.assign_declaration", library, definitions=[context], relating_context=root)
 
             # Remove the library from our project
             ifcopenshell.api.run("project.unassign_declaration", library, definition=context, relating_context=root)

src/ifcopenshell-python/ifcopenshell/api/resource/add_resource.py

@@ -105,7 +105,7 @@ class Usecase:
             ifcopenshell.api.run(
                 "project.assign_declaration",
                 self.file,
-                definition=resource,
+                definitions=[resource],
                 relating_context=context,
             )
         return resource

src/ifcopenshell-python/ifcopenshell/api/sequence/add_work_calendar.py

@@ -92,7 +92,7 @@ class Usecase:
         ifcopenshell.api.run(
             "project.assign_declaration",
             self.file,
-            definition=work_calendar,
+            definitions=[work_calendar],
             relating_context=context,
         )
         return work_calendar

src/ifcopenshell-python/ifcopenshell/api/sequence/add_work_plan.py

@@ -84,7 +84,7 @@ class Usecase:
         ifcopenshell.api.run(
             "project.assign_declaration",
             self.file,
-            definition=work_plan,
+            definitions=[work_plan],
             relating_context=context,
         )
         return work_plan

src/ifcopenshell-python/ifcopenshell/api/sequence/add_work_schedule.py

@@ -118,7 +118,7 @@ class Usecase:
             ifcopenshell.api.run(
                 "project.assign_declaration",
                 self.file,
-                definition=work_schedule,
+                definitions=[work_schedule],
                 relating_context=context,
             )
         return work_schedule

src/ifcopenshell-python/test/api/project/test_assign_declaration.py

@@ -0,0 +1,70 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2021 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
+
+import test.bootstrap
+import ifcopenshell.api
+
+
+# NOTE: supported only in IFC4+
+class TestAssignDeclaration(test.bootstrap.IFC4):
+    def get_declared_definitions(self, project: ifcopenshell.entity_instance) -> set[ifcopenshell.entity_instance]:
+        definitions = set()
+        for declares in project.Declares:
+            definitions.update(declares.RelatedDefinitions)
+        return definitions
+
+    def test_assign_a_declaration(self):
+        element_type = ifcopenshell.api.run("root.create_entity", self.file, ifc_class="IfcWallType")
+        element_type2 = ifcopenshell.api.run("root.create_entity", self.file, ifc_class="IfcWallType")
+        library = ifcopenshell.api.run("root.create_entity", self.file, ifc_class="IfcProjectLibrary")
+        ifcopenshell.api.run(
+            "project.assign_declaration",
+            self.file,
+            definitions=[element_type, element_type2],
+            relating_context=library,
+        )
+        assert self.get_declared_definitions(library) == {element_type, element_type2}
+        assert len(self.file.by_type("IfcRelDeclares")) == 1
+
+    def test_doing_nothing_if_the_library_is_already_assigned(self):
+        element_type = ifcopenshell.api.run("root.create_entity", self.file, ifc_class="IfcWallType")
+        element_type2 = ifcopenshell.api.run("root.create_entity", self.file, ifc_class="IfcWallType")
+        library = ifcopenshell.api.run("root.create_entity", self.file, ifc_class="IfcProjectLibrary")
+        ifcopenshell.api.run(
+            "project.assign_declaration", self.file, definitions=[element_type, element_type2], relating_context=library
+        )
+        total_elements = len([e for e in self.file])
+        ifcopenshell.api.run(
+            "project.assign_declaration", self.file, definitions=[element_type, element_type2], relating_context=library
+        )
+        assert len([e for e in self.file]) == total_elements
+
+    def test_that_old_relationships_are_updated_if_they_still_contain_elements(self):
+        element_type = ifcopenshell.api.run("root.create_entity", self.file, ifc_class="IfcWallType")
+        library = ifcopenshell.api.run("root.create_entity", self.file, ifc_class="IfcProjectLibrary")
+        ifcopenshell.api.run(
+            "project.assign_declaration", self.file, definitions=[element_type], relating_context=library
+        )
+        rel = self.file.by_type("IfcRelDeclares")[0]
+
+        element_type2 = ifcopenshell.api.run("root.create_entity", self.file, ifc_class="IfcWallType")
+        element_type3 = ifcopenshell.api.run("root.create_entity", self.file, ifc_class="IfcWallType")
+        ifcopenshell.api.run(
+            "project.assign_declaration", self.file, definitions=[element_type2, element_type3], relating_context=library
+        )
+        assert len(rel.RelatedDefinitions) == 3

src/ifcopenshell-python/test/api/test_api.py

@@ -303,11 +303,26 @@ class TestTemporarySupportForDeprecatedAPIArguments(test.bootstrap.IFC4):
     def test_unassigning_a_constraint(self):
         constraint = ifcopenshell.api.run("constraint.add_objective", self.file)
         element = ifcopenshell.api.run("root.create_entity", self.file, ifc_class="IfcWall")
-        ifcopenshell.api.run(
-            "constraint.assign_constraint", self.file, product=element, constraint=constraint
-        )
-        ifcopenshell.api.run(
-            "constraint.unassign_constraint", self.file, product=element, constraint=constraint
-        )
+        ifcopenshell.api.run("constraint.assign_constraint", self.file, product=element, constraint=constraint)
+        ifcopenshell.api.run("constraint.unassign_constraint", self.file, product=element, constraint=constraint)
         assert ifcopenshell.util.constraint.get_constrained_elements(element) == set()
         assert len(self.file.by_type("IfcRelAssociatesConstraint")) == 0
+
+    @deprecation_check
+    def test_assign_a_declaration(self):
+        def get_declared_definitions(project: ifcopenshell.entity_instance) -> set[ifcopenshell.entity_instance]:
+            definitions = set()
+            for declares in project.Declares:
+                definitions.update(declares.RelatedDefinitions)
+            return definitions
+
+        element_type = ifcopenshell.api.run("root.create_entity", self.file, ifc_class="IfcWallType")
+        library = ifcopenshell.api.run("root.create_entity", self.file, ifc_class="IfcProjectLibrary")
+        ifcopenshell.api.run(
+            "project.assign_declaration",
+            self.file,
+            definition=element_type,
+            relating_context=library,
+        )
+        assert get_declared_definitions(library) == {element_type}
+        assert len(self.file.by_type("IfcRelDeclares")) == 1