Fix ability to run tests and segfaulting test

it was creating new applications and users every time `ifcopenshell.api.owner.settings.get_user` or `ifcopenshell.api.owner.settings.get_application` was called

src/blenderbim/Makefile

@@ -151,8 +151,10 @@ endif
 	cd dist/working && wget https://github.com/IfcOpenShell/IfcOpenShell/archive/v0.7.0.zip
 	cd dist/working && unzip v0.7.0.zip
 	# IfcOpenBot sometimes lags behind, so we hotfix the Python utilities
-	cp -r dist/working/IfcOpenShell-0.7.0/src/ifcopenshell-python/ifcopenshell/util/* dist/blenderbim/libs/site/packages/ifcopenshell/util/
-	cp -r dist/working/IfcOpenShell-0.7.0/src/ifcopenshell-python/ifcopenshell/api/* dist/blenderbim/libs/site/packages/ifcopenshell/api/
+	rm -rf dist/blenderbim/libs/site/packages/ifcopenshell/util/
+	rm -rf dist/blenderbim/libs/site/packages/ifcopenshell/api/
+	cp -r dist/working/IfcOpenShell-0.7.0/src/ifcopenshell-python/ifcopenshell/util dist/blenderbim/libs/site/packages/ifcopenshell/
+	cp -r dist/working/IfcOpenShell-0.7.0/src/ifcopenshell-python/ifcopenshell/api dist/blenderbim/libs/site/packages/ifcopenshell/
 	cp dist/working/IfcOpenShell-0.7.0/src/ifcopenshell-python/ifcopenshell/*.py dist/blenderbim/libs/site/packages/ifcopenshell/
 	cp dist/working/IfcOpenShell-0.7.0/src/ifcopenshell-python/ifcopenshell/express/rule_executor.py dist/blenderbim/libs/site/packages/ifcopenshell/express/
 	# Provides bcf functionality

src/blenderbim/blenderbim/__init__.py

@@ -18,7 +18,13 @@
 
 import os
 import sys
-import site
+import bpy
+import platform
+import traceback
+import subprocess
+import webbrowser
+import addon_utils
+from collections import deque
 
 bl_info = {
     "name": "BlenderBIM",
@@ -32,16 +38,150 @@ bl_info = {
     "category": "System",
 }
 
+last_error = None
+last_actions: deque = deque(maxlen=10)
+
+
+def get_debug_info():
+    version = ".".join(
+        [
+            str(x)
+            for x in [
+                addon.bl_info.get("version", (-1, -1, -1))
+                for addon in addon_utils.modules()
+                if addon.bl_info["name"] == "BlenderBIM"
+            ][0]
+        ]
+    )
+    return {
+        "os": platform.system(),
+        "os_version": platform.version(),
+        "python_version": platform.python_version(),
+        "architecture": platform.architecture(),
+        "machine": platform.machine(),
+        "processor": platform.processor(),
+        "blender_version": bpy.app.version_string,
+        "blenderbim_version": version,
+        "last_actions": last_actions,
+        "last_error": last_error,
+    }
+
+
+def format_debug_info(info: dict):
+    last_actions = ""
+    for action in info["last_actions"]:
+        last_actions += f"\n# {action['type']}: {action['name']}"
+        if settings := action.get("settings"):
+            last_actions += f"\n>>> {settings}"
+    info["last_actions"] = last_actions
+    text = "\n".join(f"{k}: {v}" for k, v in info.items())
+    return text.strip()
+
+
 if sys.modules.get("bpy", None):
     # Process *.pth in /libs/site/packages to setup globally importable modules
     # This is 3 levels deep as required by the static RPATH of ../../ from dependencies taken from Anaconda
     # site.addsitedir(os.path.join(os.path.dirname(os.path.realpath(__file__)), "libs", "site", "packages"))
     sys.path.insert(0, os.path.join(os.path.dirname(os.path.realpath(__file__)), "libs", "site", "packages"))
 
-    import blenderbim.bim
+    try:
+        import blenderbim.bim
+        import ifcopenshell.api
 
-    def register():
-        blenderbim.bim.register()
+        def log_api(usecase_path, ifc_file, settings):
+            last_actions.append(
+                {
+                    "type": "ifcopenshell.api",
+                    "name": usecase_path,
+                    "settings": ifcopenshell.api.serialise_settings(settings),
+                }
+            )
 
-    def unregister():
-        blenderbim.bim.unregister()
+        ifcopenshell.api.add_pre_listener("*", "action_logger", log_api)
+
+        def register():
+            blenderbim.bim.register()
+
+        def unregister():
+            blenderbim.bim.unregister()
+
+    except:
+        last_error = traceback.format_exc()
+
+        print(last_error)
+        print(format_debug_info(get_debug_info()))
+        print("\nFATAL ERROR: Unable to load the BlenderBIM Add-on")
+
+        class BIM_PT_fatal_error(bpy.types.Panel):
+            bl_label = "BlenderBIM Fatal Error"
+            bl_idname = "SCENE_PT_error_message"
+            bl_space_type = "PROPERTIES"
+            bl_region_type = "WINDOW"
+            bl_context = "scene"
+
+            def draw(self, context):
+                layout = self.layout
+                layout.label(text="BlenderBIM could not load.", icon="ERROR")
+                layout.label(text="View the console for full logs.", icon="CONSOLE")
+                box = layout.box()
+                info = get_debug_info()
+                py = ".".join(info["python_version"].split(".")[0:2])
+                b3d = ".".join(info["blender_version"].split(".")[0:2])
+                box.label(text=f"Blender {b3d} {info['os']} {info['machine']}", icon="BLENDER")
+                box.label(text=f"Python {py} BBIM {info['blenderbim_version']}", icon="SCRIPTPLUGINS")
+                layout.operator("bim.copy_debug_information", text="Copy Error Message To Clipboard")
+                op = layout.operator("bim.open_uri", text="How Can I Fix This?")
+                op.uri = "https://docs.blenderbim.org/users/troubleshooting.html#installation-issues"
+
+        class OpenUri(bpy.types.Operator):
+            bl_idname = "bim.open_uri"
+            bl_label = "Open URI"
+            uri: bpy.props.StringProperty()
+
+            def execute(self, context):
+                webbrowser.open(self.uri)
+                return {"FINISHED"}
+
+        class CopyDebugInformation(bpy.types.Operator):
+            bl_idname = "bim.copy_debug_information"
+            bl_label = "Copy Debug Information"
+            bl_description = "Copies debugging information to your clipboard for use in bugreports"
+
+            def execute(self, context):
+                info = format_debug_info(get_debug_info())
+
+                if platform.system() == "Windows":
+                    command = "echo | set /p nul=" + info
+                elif platform.system() == "Darwin":  # for MacOS
+                    command = 'printf "' + info.replace("\n", "\\n").replace('"', "") + '" | pbcopy'
+                else:  # Linux
+                    command = 'printf "' + info.replace("\n", "\\n").replace('"', "") + '" | xclip -selection clipboard'
+                subprocess.run(command, shell=True, check=True)
+                return {"FINISHED"}
+
+        class HiddenPanel:
+            @classmethod
+            def false_poll(cls, context):
+                return False
+
+        def register():
+            # Only show our error panel and nothing else in the scene tab
+            for item_name in dir(bpy.types):
+                item = getattr(bpy.types, item_name)
+                if not hasattr(item, "bl_rna") or not isinstance(item.bl_rna, bpy.types.Panel):
+                    continue
+                if getattr(item, "bl_context", None) != "scene":
+                    continue
+
+                # Reregister scene panel with a new poll to hide it
+                item.poll = HiddenPanel.false_poll
+                bpy.utils.unregister_class(item)
+                bpy.utils.register_class(item)
+            bpy.utils.register_class(BIM_PT_fatal_error)
+            bpy.utils.register_class(CopyDebugInformation)
+            bpy.utils.register_class(OpenUri)
+
+        def unregister():
+            bpy.utils.unregister_class(OpenUri)
+            bpy.utils.unregister_class(CopyDebugInformation)
+            bpy.utils.unregister_class(BIM_PT_fatal_error)

src/blenderbim/blenderbim/bim/__init__.py

@@ -17,11 +17,11 @@
 # along with BlenderBIM Add-on.  If not, see <http://www.gnu.org/licenses/>.
 
 import os
-from pathlib import Path
 import bpy
 import bpy.utils.previews
 import blenderbim
 import importlib
+from pathlib import Path
 from . import handler, ui, prop, operator, helper
 from typing import Callable, Union
 
@@ -103,6 +103,7 @@ classes = [
     operator.BIM_OT_select_object,
     operator.BIM_OT_show_description,
     operator.ClippingPlaneCutWithCappings,
+    operator.CloseError,
     operator.EditBlenderCollection,
     operator.FileAssociate,
     operator.FileUnassociate,

src/blenderbim/blenderbim/bim/ifc.py

@@ -22,9 +22,11 @@ import uuid
 import hashlib
 import zipfile
 import tempfile
+import traceback
 import ifcopenshell
 import ifcopenshell.geom
 import ifcopenshell.ifcopenshell_wrapper
+import blenderbim
 import blenderbim.bim.handler
 import blenderbim.tool as tool
 from pathlib import Path
@@ -37,19 +39,19 @@ IFC_CONNECTED_TYPE = Union[bpy.types.Material, bpy.types.Object]
 
 class IfcStore:
     path: str = ""
-    file: ifcopenshell.file = None
-    schema: ifcopenshell.ifcopenshell_wrapper.schema_definition = None
-    cache: ifcopenshell.ifcopenshell_wrapper.HdfSerializer = None
-    cache_path: str = None
+    file: Optional[ifcopenshell.file] = None
+    schema: Optional[ifcopenshell.ifcopenshell_wrapper.schema_definition] = None
+    cache: Optional[ifcopenshell.ifcopenshell_wrapper.HdfSerializer] = None
+    cache_path: Optional[str] = None
     id_map: dict[int, IFC_CONNECTED_TYPE] = {}
     guid_map: dict[str, IFC_CONNECTED_TYPE] = {}
     edited_objs: Set[bpy.types.Object] = set()
     pset_template_path: str = ""
-    pset_template_file: ifcopenshell.file = None
+    pset_template_file: Optional[ifcopenshell.file] = None
     classification_path: str = ""
-    classification_file: ifcopenshell.file = None
+    classification_file: Optional[ifcopenshell.file] = None
     library_path: str = ""
-    library_file: ifcopenshell.file = None
+    library_file: Optional[ifcopenshell.file] = None
     current_transaction = ""
     last_transaction = ""
     history = []
@@ -329,6 +331,7 @@ class IfcStore:
 
     @staticmethod
     def execute_ifc_operator(operator: bpy.types.Operator, context: bpy.types.Context, is_invoke=False):
+        blenderbim.last_actions.append({"type": "operator", "name": operator.bl_idname})
         bpy.context.scene.BIMProperties.is_dirty = True
         is_top_level_operator = not bool(IfcStore.current_transaction)
 
@@ -343,10 +346,14 @@ class IfcStore:
         else:
             operator.transaction_key = IfcStore.current_transaction
 
-        if is_invoke:
-            result = getattr(operator, "_invoke")(context, None)
-        else:
-            result = getattr(operator, "_execute")(context)
+        try:
+            if is_invoke:
+                result = getattr(operator, "_invoke")(context, None)
+            else:
+                result = getattr(operator, "_execute")(context)
+        except:
+            blenderbim.last_error = traceback.format_exc()
+            raise
 
         if is_top_level_operator:
             if tool.Ifc.get():

src/blenderbim/blenderbim/bim/import_ifc.py

@@ -702,15 +702,17 @@ class IfcImporter:
             mat = np.array(
                 ([m[0], m[3], m[6], m[9]], [m[1], m[4], m[7], m[10]], [m[2], m[5], m[8], m[11]], [0, 0, 0, 1])
             )
-            point = np.array(
+            point = mat @ np.array(
                 (
-                    shape.geometry.verts[0] / self.unit_scale,
-                    shape.geometry.verts[1] / self.unit_scale,
-                    shape.geometry.verts[2] / self.unit_scale,
+                    shape.geometry.verts[0],
+                    shape.geometry.verts[1],
+                    shape.geometry.verts[2],
                     0.0,
                 )
             )
-            return mat @ point
+            point = point / self.unit_scale
+            if self.is_point_far_away(point, is_meters=False):
+                return point
 
     def does_element_likely_have_geometry_far_away(self, element):
         for representation in element.Representation.Representations:
@@ -1500,10 +1502,9 @@ class IfcImporter:
         project_collection = bpy.context.view_layer.layer_collection.children[self.project["blender"].name]
         types_collection = project_collection.children[self.type_collection.name]
         types_collection.hide_viewport = False
-        for obj in types_collection.collection.objects: #turn off all objects inside Types collection.
+        for obj in types_collection.collection.objects:  # turn off all objects inside Types collection.
             obj.hide_set(True)
 
-
     def clean_mesh(self):
         obj = None
         last_obj = None
@@ -1912,11 +1913,7 @@ class IfcImporter:
                 and geometry.verts
                 and self.is_point_far_away((geometry.verts[0], geometry.verts[1], geometry.verts[2]))
             ):
-                m = shape.transformation.matrix.data
-                mat = np.array(
-                    ([m[0], m[3], m[6], m[9]], [m[1], m[4], m[7], m[10]], [m[2], m[5], m[8], m[11]], [0, 0, 0, 1])
-                )
-                offset_point = np.linalg.inv(mat) @ np.array(
+                offset_point = np.array(
                     (
                         float(props.blender_eastings),
                         float(props.blender_northings),
@@ -1924,6 +1921,12 @@ class IfcImporter:
                         0.0,
                     )
                 )
+                if geometry != shape:
+                    m = shape.transformation.matrix.data
+                    mat = np.array(
+                        ([m[0], m[3], m[6], m[9]], [m[1], m[4], m[7], m[10]], [m[2], m[5], m[8], m[11]], [0, 0, 0, 1])
+                    )
+                    offset_point = np.linalg.inv(mat) @ offset_point
                 verts = [None] * len(geometry.verts)
                 for i in range(0, len(geometry.verts), 3):
                     verts[i], verts[i + 1], verts[i + 2] = ifcopenshell.util.geolocation.enh2xyz(

src/blenderbim/blenderbim/bim/module/attribute/operator.py

@@ -20,6 +20,7 @@ import bpy
 import json
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.guid
 import blenderbim.bim.helper
 import blenderbim.bim.handler
 import blenderbim.tool as tool

src/blenderbim/blenderbim/bim/module/debug/operator.py

@@ -24,7 +24,6 @@ import random
 import logging
 import platform
 import subprocess
-import addon_utils
 import ifcopenshell
 import ifcopenshell.api
 import ifcopenshell.util.element
@@ -34,7 +33,7 @@ import blenderbim.tool as tool
 import blenderbim.core.debug as core
 import blenderbim.bim.handler
 import blenderbim.bim.import_ifc as import_ifc
-import blenderbim.tool as tool
+from blenderbim import get_debug_info, format_debug_info
 from blenderbim.bim.ifc import IfcStore
 
 
@@ -44,28 +43,7 @@ class CopyDebugInformation(bpy.types.Operator):
     bl_description = "Copies debugging information to your clipboard for use in bugreports"
 
     def execute(self, context):
-        version = ".".join(
-            [
-                str(x)
-                for x in [
-                    addon.bl_info.get("version", (-1, -1, -1))
-                    for addon in addon_utils.modules()
-                    if addon.bl_info["name"] == "BlenderBIM"
-                ][0]
-            ]
-        )
-        info = {
-            "os": platform.system(),
-            "os_version": platform.version(),
-            "python_version": platform.python_version(),
-            "architecture": platform.architecture(),
-            "machine": platform.machine(),
-            "processor": platform.processor(),
-            "blender_version": bpy.app.version_string,
-            "blenderbim_version": version,
-            "ifc": False,
-        }
-
+        info = get_debug_info()
         if tool.Ifc.get():
             info.update(
                 {
@@ -76,16 +54,18 @@ class CopyDebugInformation(bpy.types.Operator):
                 }
             )
 
-        # Format it in a readable way
-        text = "\n".join(f"{k}: {v}" for k, v in info.items())
+        text = format_debug_info(info)
+
+        print("-" * 80)
         print(text)
+        print("-" * 80)
 
         if platform.system() == "Windows":
-            command = "echo | set /p nul=" + text.strip()
+            command = "echo | set /p nul=" + text
         elif platform.system() == "Darwin":  # for MacOS
-            command = 'printf "' + text.strip().replace("\n", "\\n").replace('"', "") + '" | pbcopy'
+            command = 'printf "' + text.replace("\n", "\\n").replace('"', "") + '" | pbcopy'
         else:  # Linux
-            command = 'printf "' + text.strip().replace("\n", "\\n").replace('"', "") + '" | xclip -selection clipboard'
+            command = 'printf "' + text.replace("\n", "\\n").replace('"', "") + '" | xclip -selection clipboard'
         subprocess.run(command, shell=True, check=True)
         return {"FINISHED"}
 

src/blenderbim/blenderbim/bim/module/geometry/operator.py

@@ -926,7 +926,7 @@ class OverrideDuplicateMove(bpy.types.Operator):
                     if r.is_a("IfcRelAssignsToGroup")
                     if "BBIM_Linked_Aggregate" in r.RelatingGroup.Name
                 ]
-                tool.Ifc.run("group.unassign_group", group=linked_aggregate_group[0], product=new[0])
+                tool.Ifc.run("group.unassign_group", group=linked_aggregate_group[0], products=[new[0]])
 
 
 class OverrideDuplicateMoveLinkedMacro(bpy.types.Macro):

src/blenderbim/blenderbim/bim/module/project/operator.py

@@ -21,6 +21,7 @@ import bpy
 import time
 import logging
 import tempfile
+import traceback
 import subprocess
 import numpy as np
 import ifcopenshell
@@ -674,19 +675,23 @@ class LoadProject(bpy.types.Operator, IFCFileSelector):
             return self.finish_loading_project(context)
 
     def finish_loading_project(self, context):
-        if not self.is_existing_ifc_file():
-            return {"FINISHED"}
+        try:
+            if not self.is_existing_ifc_file():
+                return {"FINISHED"}
 
-        if tool.Blender.is_default_scene():
-            for obj in bpy.data.objects:
-                bpy.data.objects.remove(obj)
+            if tool.Blender.is_default_scene():
+                for obj in bpy.data.objects:
+                    bpy.data.objects.remove(obj)
 
-        context.scene.BIMProperties.ifc_file = self.get_filepath()
-        context.scene.BIMProjectProperties.is_loading = True
-        context.scene.BIMProjectProperties.total_elements = len(tool.Ifc.get().by_type("IfcElement"))
-        tool.Blender.register_toolbar()
-        if not self.is_advanced:
-            bpy.ops.bim.load_project_elements()
+            context.scene.BIMProperties.ifc_file = self.get_filepath()
+            context.scene.BIMProjectProperties.is_loading = True
+            context.scene.BIMProjectProperties.total_elements = len(tool.Ifc.get().by_type("IfcElement"))
+            tool.Blender.register_toolbar()
+            if not self.is_advanced:
+                bpy.ops.bim.load_project_elements()
+        except:
+            blenderbim.last_error = traceback.format_exc()
+            raise
         return {"FINISHED"}
 
     def invoke(self, context, event):

src/blenderbim/blenderbim/bim/module/root/data.py

@@ -185,6 +185,8 @@ class IfcClassData:
         if element:
             if element.is_a("IfcOpeningElement") or element.is_a("IfcOpeningStandardCase"):
                 return False
+            if element.is_a() in ("IfcWindowStyle", "IfcDoorStyle"): #see https://github.com/IfcOpenShell/IfcOpenShell/issues/4622#issuecomment-2095676368
+                return True
             for product in cls.ifc_products():
                 if element.is_a(product[0]):
                     return True

src/blenderbim/blenderbim/bim/module/search/operator.py

@@ -20,6 +20,7 @@ import re
 import bpy
 import json
 import ifcopenshell
+import ifcopenshell.guid
 import ifcopenshell.util.element
 import ifcopenshell.util.selector
 from ifcopenshell.util.selector import Selector

src/blenderbim/blenderbim/bim/operator.py

@@ -90,6 +90,15 @@ class OpenUri(bpy.types.Operator):
         return {"FINISHED"}
 
 
+class CloseError(bpy.types.Operator):
+    bl_idname = "bim.close_error"
+    bl_label = "Close Error"
+
+    def execute(self, context):
+        blenderbim.last_error = None
+        return {"FINISHED"}
+
+
 class SelectURIAttribute(bpy.types.Operator):
     bl_idname = "bim.select_uri_attribute"
     bl_label = "Select URI Attribute"

src/blenderbim/blenderbim/bim/ui.py

@@ -29,8 +29,9 @@ from ifcopenshell.util.doc import (
     get_attribute_doc,
 )
 from . import ifc
-import blenderbim.tool as tool
+from blenderbim import get_debug_info
 import blenderbim.bim
+import blenderbim.tool as tool
 from blenderbim.bim.helper import IfcHeaderExtractor
 from blenderbim.bim.prop import Attribute
 
@@ -402,6 +403,17 @@ class BIM_PT_tabs(Panel):
 
             row = self.layout.row(align=True)
             row.prop(aprops, "tab", text="")
+
+            if blenderbim.last_error:
+                box = self.layout.box()
+                row = box.row(align=True)
+                row.label(text="BlenderBIM experienced an error :(", icon="ERROR")
+                row.operator("bim.close_error", text="", icon="CANCEL")
+                box.label(text="View the console for full logs.", icon="CONSOLE")
+                box.operator("bim.copy_debug_information", text="Copy Error Message To Clipboard")
+                op = box.operator("bim.open_uri", text="How Can I Fix This?")
+                op.uri = "https://docs.blenderbim.org/users/troubleshooting.html"
+
         except:
             pass  # Prior to load_post, we may not have any area properties setup
 

src/blenderbim/blenderbim/tool/brick.py

@@ -19,6 +19,7 @@
 import os
 import bpy
 import ifcopenshell
+import ifcopenshell.guid
 import ifcopenshell.util.brick
 import blenderbim.core.tool
 import blenderbim.tool as tool
@@ -604,4 +605,4 @@ class BrickStore:
     def set_last_saved(cls):
         save = os.path.getmtime(BrickStore.path)
         save = datetime.datetime.fromtimestamp(save)
-        BrickStore.last_saved = f"{save.year}-{save.month}-{save.day} {save.hour}:{save.minute}"
+        BrickStore.last_saved = f"{save.year}-{save.month}-{save.day} {save.hour}:{save.minute}"

src/blenderbim/blenderbim/tool/geometry.py

@@ -24,6 +24,7 @@ import logging
 import numpy as np
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.guid
 import ifcopenshell.util.element
 import ifcopenshell.util.system
 import blenderbim.core.tool

src/blenderbim/blenderbim/tool/search.py

@@ -3,6 +3,7 @@ import json
 import lark
 import blenderbim.core.tool
 import blenderbim.tool as tool
+import ifcopenshell.guid
 import ifcopenshell.util.selector
 from ifcopenshell.util.selector import Selector
 from blenderbim.bim.prop import BIMFacet

src/blenderbim/blenderbim/tool/spatial.py

@@ -111,16 +111,17 @@ class Spatial(blenderbim.core.tool.Spatial):
         for rel in parent.IsDecomposedBy or []:
             related_objects = []
             for element in rel.RelatedObjects:
+                # skip objects without placements
+                if not element.is_a("IfcProduct"):
+                    continue
                 related_objects.append((element, ifcopenshell.util.placement.get_storey_elevation(element)))
             related_objects = sorted(related_objects, key=lambda e: e[1])
-            for element in related_objects:
-                element = element[0]
+            for element, _ in related_objects:
                 new = props.containers.add()
                 new.name = element.Name or "Unnamed"
                 new.long_name = element.LongName or ""
                 new.has_decomposition = bool(element.IsDecomposedBy)
                 new.ifc_definition_id = element.id()
-                new.elevation = element[1]
 
     @classmethod
     def run_root_copy_class(cls, obj=None):

src/blenderbim/docs/_static/custom.css

@@ -16,6 +16,7 @@ a {
 }
 .sidebar-brand-text {
     font-size: 1rem;
+    text-align: center;
 }
 .blockbutton {
     max-width: 500px;

src/blenderbim/docs/conf.py

@@ -95,7 +95,10 @@ html_theme_options = {
         "color-background-border": "#cfd0cb",
         "color-foreground-primary": "#2e3436",
         "color-sidebar-item-background--hover": "#f7f7f6",
+        "color-link": "#39b54a",
+        "color-link--visited": "#39b54a",
         "color-link--hover": "#d98014",
+        "color-link--visited--hover": "#d98014",
         "font-stack": "Nunito, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji"
     },
     "dark_css_variables": {
@@ -106,7 +109,10 @@ html_theme_options = {
         "color-background-border": "#2e3436",
         "color-foreground-primary": "#eeeeec",
         "color-sidebar-item-background--hover": "#2e3436",
+        "color-link": "#39b54a",
+        "color-link--visited": "#39b54a",
         "color-link--hover": "#d98014",
+        "color-link--visited--hover": "#d98014",
         "font-stack": "Nunito, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji"
     },
 

src/blenderbim/docs/devs/installation.rst

@@ -13,14 +13,14 @@ Unstable installation
 
 **Unstable installation** is almost the same as **Stable installation**, except
 that they are typically updated every day. Simply download a daily build from
-the `Github releases page
-<https://github.com/IfcOpenShell/IfcOpenShell/releases>`__, then follow the same
-instructions as the **Stable installation**.
+the `GitHub releases page
+<https://github.com/IfcOpenShell/IfcOpenShell/releases>`__, then follow the
+usual :doc:`installation instructions</users/installation>`.
 
 You will need to choose which build to download.
 
 - If you are on Blender >=4.1, choose py311
-- If you are on Blender >=3.1 and <=4.0, choose py10
+- If you are on Blender >=3.1 and <=4.0, choose py310
 - If you are on Blender >=2.93 and <3.1, choose py39
 - Choose ``linux``, ``macos`` (Apple Intel), ``macosm1`` (Apple Silicon), or
   ``win`` depending on your operating system
@@ -92,13 +92,14 @@ For Linux or Mac:
     $ ln -s $PWD/src/blenderbim/blenderbim/tool $BLENDER_ADDON_PATH/tool
     $ ln -s $PWD/src/blenderbim/blenderbim/bim $BLENDER_ADDON_PATH/bim
 
-    # Remove the IfcOpenShell dependency Python code
-    $ rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifcopenshell/api
-    $ rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifcopenshell/util
+    # Copy over compiled IfcOpenShell files
+    $ cp $BLENDER_ADDON_PATH/libs/site/packages/ifcopenshell/*_wrapper* $PWD/src/ifcopenshell-python/ifcopenshell/
+    
+    # Remove the IfcOpenShell dependency
+    $ rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifcopenshell
 
     # Replace them with links to the Git repository
-    $ ln -s $PWD/src/ifcopenshell-python/ifcopenshell/api $BLENDER_ADDON_PATH/libs/site/packages/ifcopenshell/api
-    $ ln -s $PWD/src/ifcopenshell-python/ifcopenshell/util $BLENDER_ADDON_PATH/libs/site/packages/ifcopenshell/util
+    $ ln -s $PWD/src/ifcopenshell-python/ifcopenshell $BLENDER_ADDON_PATH/libs/site/packages/ifcopenshell
 
     # Remove and link other IfcOpenShell utilities
     $ rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifccsv.py
@@ -153,21 +154,19 @@ Before running it follow the instructions descibed after `rem` tags.
     rd /S /Q "%blenderbim%\tool\"
     rd /S /Q "%blenderbim%\bim\"
 
-
     echo Replacing them with links to the Git repository...
     mklink /D "%blenderbim%\core" "%cd%\src\blenderbim\blenderbim\core"
     mklink /D "%blenderbim%\tool" "%cd%\src\blenderbim\blenderbim\tool"
     mklink /D "%blenderbim%\bim" "%cd%\src\blenderbim\blenderbim\bim"
 
+    echo Copy over compiled IfcOpenShell files...
+    copy "%blenderbim%\libs\site\packages\ifcopenshell\*_wrapper*" "%cd%\src\ifcopenshell-python\ifcopenshell\"
 
-    echo Remove the IfcOpenShell dependency Python code...
-    rd /S /Q "%blenderbim%\libs\site\packages\ifcopenshell\api"
-    rd /S /Q "%blenderbim%\libs\site\packages\ifcopenshell\util"
+    echo Remove the IfcOpenShell dependency...
+    rd /S /Q "%blenderbim%\libs\site\packages\ifcopenshell"
 
-
-    echo Replacing them with links to the Git repository...
-    mklink /D "%blenderbim%\libs\site\packages\ifcopenshell\api" "%cd%\src\ifcopenshell-python\ifcopenshell\api"
-    mklink /D "%blenderbim%\libs\site\packages\ifcopenshell\util" "%cd%\src\ifcopenshell-python\ifcopenshell\util"
+    echo Replace them with links to the Git repository...
+    mklink /D "%blenderbim%\libs\site\packages\ifcopenshell" "%cd%\src\ifcopenshell-python\ifcopenshell"
 
     echo Remove and link other IfcOpenShell utilities...
     del "%blenderbim%\libs\site\packages\ifccsv.py"

src/blenderbim/docs/devs/writing_docs.rst

@@ -16,9 +16,12 @@ You can press the edit button on the top right on any documentation page to
 quickly edit their content.
 
 You can link to `external websites
-<https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html>`_.
-You can also link to sections on the same page, like `Writing technical
-documentation`_. You can link to other pages, like :doc:`Hello
+<https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html>`_
+(note the space between the url and the link text).  You can also link to
+sections on the same page, like :ref:`devs/writing_docs:Writing technical
+documentation` or with :ref:`custom text<devs/writing_docs:writing technical
+documentation>`. Traditional references like `Writing technical documentation`_
+work too but are discouraged. You can link to other pages, like :doc:`Hello
 World<hello_world>` or sections within other pages, like
 :ref:`devs/installation:unstable installation`. We have ``autosectionlabel``
 enabled so it is not necessary to manually create labels.

src/blenderbim/docs/index.rst

@@ -32,6 +32,7 @@ Learn how to model a small building and create simple architectural plans, secti
    users/git_support
    users/other_addons
    users/general_usage
+   users/troubleshooting
 
 .. toctree::
    :hidden:

src/blenderbim/docs/users/installation.rst

@@ -58,6 +58,32 @@ You can enable add-ons permanently by using ``Save User Settings`` from the Addo
 
 .. _where is the add-on installed:
 
+Updating
+--------
+
+First follow the `Uninstalling`_ section below, then install the latest version.
+
+Uninstalling
+------------
+
+Navigate to ``Edit > Preferences > Add-ons``. Due to a limitation in Blender,
+you have to **first disable the BlenderBIM Add-on in your Blender preferences**
+by pressing the checkbox next to the add-on, then **restart Blender**. It is
+critical to follow this sequence of disabling first, and then restarting.
+
+After restarting, you can uninstall the BlenderBIM Add-on by pressing the
+``Remove`` button in the Blender preferences window.
+
+Alternatively, you may uninstall manually by deleting the ``blenderbim``
+directory in :ref:`your Blender add-ons directory<where is the add-on
+installed>`.
+
+.. warning::
+
+    It is important to follow the sequence of disabling, restarting, then removing.
+    If you do not restart Blender, the add-on will fail to remove correctly, and you
+    will need to uninstall manually.
+
 Where is the add-on installed?
 ------------------------------
 
@@ -66,118 +92,44 @@ Upon installation, the BlenderBIM Add-on is stored in the
 folder. However, the location of your Blender configuration folder depends on
 how you have installed Blender.
 
-If you downloaded Blender as a ``.zip`` file without running an installer, you
-will find the Blender configuration folder in the following directory, where
-``X.XX`` is the Blender version:
+If you downloaded Blender as a ``.zip`` file without running an installer, the
+BlenderBIM Add-on will be installed in the following directory, where ``X.XX``
+is the Blender version:
+
 ::
 
-    /path/to/blender/X.XX/
+    /path/to/blender/X.XX/scripts/addons/blenderbim/
 
 Otherwise, if you installed Blender using an installation package, the Blender
 configuration folder depends on which operating system you use.
 
 On Linux, if you are installing the add-on as a user:
+
 ::
 
-    ~/.config/blender/X.XX/
+    ~/.config/blender/X.XX/scripts/addons/blenderbim/
 
 On Linux, if you are deploying the add-on system-wide (this may also depend on
 your Linux distribution):
+
 ::
 
-    /usr/share/blender/X.XX/
+    /usr/share/blender/X.XX/scripts/addons/blenderbim/
 
 On Mac, if you are installing the add-on as a user:
+
 ::
 
-    /Users/{YOUR_USER}/Library/Application Support/Blender/X.XX/
+    /Users/{YOUR_USER}/Library/Application Support/Blender/X.XX/scripts/addons/blenderbim/
 
 On Mac, if you are deploying the add-on system-wide:
 
 ::
 
-    /Library/Application Support/Blender/X.XX/
+    /Library/Application Support/Blender/X.XX/scripts/addons/blenderbim/
 
 On Windows:
+
 ::
 
-    C:\Users\{YOUR_USER}\AppData\Roaming\Blender Foundation\X.XX\
-
-Updating
---------
-
-First uninstall the current BlenderBIM add-on, then install the latest version.
-
-Uninstalling
-------------
-
-Navigate to ``Edit > Preferences > Add-ons``. Due to a limitation in Blender,
-you have to first disable the BlenderBIM Add-on in your Blender preferences by
-pressing the checkbox next to the add-on, then restart Blender. After
-restarting, you can uninstall the BlenderBIM Add-on by pressing the ``Remove``
-button in the Blender preferences window.
-
-Alternatively, you may uninstall manually by deleting the ``blenderbim/``
-directory in your Blender add-ons directory.
-
-.. warning::
-
-    It is important to follow the sequence of disabling, restarting, then removing.
-    If you do not restart Blender, the add-on will fail to remove correctly, and you
-    will need to uninstall manually.
-
-
-FAQ
----
-
-1. **Some other error prevents me from installing or doing basic functions with
-   the add-on. Is it specific to my environment?**
-
-   Sometimes it is helpful to try installing and using the BlenderBIM Add-on on
-   a "clean environment". A clean environment is defined as a fresh Blender
-   installation with no other add-ons enabled with factory settings.
-
-   To quickly test in a clean environment, find your Blender configuration
-   folder based on the `where is the add-on installed`_ section. Rename the
-   folder from ``X.XX`` to something else like ``X.XX_backup``, then restart
-   Blender and try follow the installation instructions again.
-
-   If this fixes your issue, consider disabling other add-ons one by one until
-   you find a conflict as a next step to isolating the issue.
-
-2. **I get an error similar to "ImportError: IfcOpenShell not built for 'linux/64bit/python3.10'"**
-
-   If you are using a Mac, be sure to use the Mac Silicon version if you have a
-   newer Mac. The only exception is if you have installed Blender using Steam
-   on a Mac, in which case you need to use the Mac Intel download.
-
-   For all other scenarios, check the BlenderBIM Add-on zip file which you
-   downloaded. The zip will have either ``py39``, ``py310``, or ``py311`` in
-   the name. See the instructions in the :ref:`devs/installation:unstable
-   installation` section to check that you have installed the correct version.
-
-3. **I am on Ubuntu and get an error similar to "ImportError:
-   /lib/x86_64-linux-gnu/libm.so.6: version GLIBC_2.29 not found"**
-
-   Our latest package which uses IfcOpenShell v0.7.0 is built using Ubuntu 20 LTS.
-   If you have an older Ubuntu version, you can either upgrade to 19.10 or above,
-   or you'll need to compile IfcOpenShell yourself.
-
-4. **I get an error saying "ModuleNotFoundError: No module named 'numpy'"**"
-
-   If you have installed Blender from another source instead of from
-   `Blender.org <https://www.blender.org/download/>`__, such as from your
-   distro's package repositories, then you may be missing some modules like
-   ``numpy``. Try installing it manually like ``apt install python-numpy``.
-
-5. **I get an error similar to RuntimeError: Instance #1234 not found**
-
-   Blender saves and loads projects to a ``.blend`` file. However. the
-   BlenderBIM Add-on works with native IFC, and this means instead of saving
-   and loading ``.blend`` files, you should instead save and load the ``.ifc``
-   project.
-
-   If you have opened a ``.blend`` file, there is a risk that the contents of
-   the ``.blend`` session do not correlate to the contents of the ``.ifc``,
-   which can cause this error. Unless you are an advanced user, only save and
-   load ``.ifc`` files.
+    C:\Users\{YOUR_USER}\AppData\Roaming\Blender Foundation\X.XX\scripts\addons\blenderbim\

src/blenderbim/docs/users/troubleshooting.rst

@@ -0,0 +1,93 @@
+Troubleshooting
+===============
+
+The BlenderBIM Add-on is alpha software. There are many bugs! When something
+goes wrong, you may see some computer code flash up on your screen. You may
+also see an error message:
+
+.. image:: images/error-message.png
+
+**Don't panic!** Click on the button that says **Copy Error Message To
+Clipboard**. You will need to paste this text in a bug report.
+
+If you do not have a GitHub account, you will need to sign up to report a bug.
+In addition to pasting the error message text, please also describe what you
+were doing, and attach your IFC file or screenshots if relevant.
+
+.. container:: blockbutton
+
+    `Report a bug <https://github.com/IfcOpenShell/IfcOpenShell/issues/new>`__
+
+If your issue is particularly complex, you can also chat live with developers
+or other powerusers.
+
+.. container:: blockbutton
+
+    `Chat live with a developer <https://osarch.org/chat>`_
+
+Installation issues
+-------------------
+
+If you are unable to install the BlenderBIM Add-on, make sure you are using
+**Blender 4.1** installed from https://blender.org/ and are installing the
+latest version from https://blenderbim.org.
+
+Other common solutions are listed below. If none of these fix the problem, you
+can `report a bug <https://github.com/ifcopenshell/ifcopenshell/issues>`_ or
+`live chat with a developer <https://osarch.org/chat/>`_.
+
+1. **Some other error prevents me from installing or doing basic functions with
+   the add-on. Is it specific to my environment?**
+
+   Try installing and using the BlenderBIM Add-on on a "clean environment". A
+   clean environment is a fresh Blender installation with no other add-ons
+   enabled with factory settings.
+
+   To quickly test in a clean environment, first :ref:`find your Blender
+   configuration folder<users/installation:where is the add-on installed?>`.
+   Rename the folder from ``X.XX`` to something else like ``X.XX_backup``, then
+   restart Blender and try follow the :doc:`installation
+   instructions<installation>` again.
+
+   If this fixes your issue, consider disabling other add-ons one by one until
+   you find a conflict as a next step to isolating the issue.
+
+2. **I get an error similar to "ImportError: IfcOpenShell not built for 'linux/64bit/python3.10'"**
+
+   If you are using a Mac, be sure to use the Mac Silicon version if you have a
+   newer Mac. The only exception is if you have installed Blender using Steam
+   on a Mac, in which case you need to use the Mac Intel download.
+
+   For all other scenarios, check the BlenderBIM Add-on zip file which you
+   downloaded. The zip will have either ``py39``, ``py310``, or ``py311`` in
+   the name. See the instructions in the :ref:`devs/installation:unstable
+   installation` section to check that you have installed the correct version.
+
+3. **I am on Ubuntu and get an error similar to "ImportError:
+   /lib/x86_64-linux-gnu/libm.so.6: version GLIBC_2.29 not found"**
+
+   Our latest package which uses IfcOpenShell v0.7.0 is built using Ubuntu 20 LTS.
+   If you have an older Ubuntu version, you can either upgrade to 19.10 or above,
+   or you'll need to compile IfcOpenShell yourself.
+
+4. **I get an error saying "ModuleNotFoundError: No module named 'numpy'"**"
+
+   If you have installed Blender from another source instead of from
+   `Blender.org <https://www.blender.org/download/>`__, such as from your
+   distro's package repositories, then you may be missing some modules like
+   ``numpy``. Try installing it manually like ``apt install python-numpy``.
+
+Common issues
+-------------
+
+1. **I get an error similar to RuntimeError: Instance #1234 not found**
+
+   Blender saves and loads projects to a ``.blend`` file. However. the
+   BlenderBIM Add-on works with native IFC, and this means instead of saving
+   and loading ``.blend`` files, you should instead save and load the ``.ifc``
+   project.
+
+   If you have opened a ``.blend`` file, there is a risk that the contents of
+   the ``.blend`` session do not correlate to the contents of the ``.ifc``,
+   which can cause this error. Unless you are an advanced user, only save and
+   load ``.ifc`` files.

src/blenderbim/scripts/classifications/xml_classification.py

@@ -4,6 +4,7 @@
 
 import xml.etree.ElementTree as ET
 import ifcopenshell
+import ifcopenshell.guid
 import os
 
 class IFC4Extractor:

src/blenderbim/scripts/dxf2ifc.py

@@ -17,6 +17,7 @@
 # along with BlenderBIM Add-on.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell
+import ifcopenshell.guid
 import ezdxf
 
 

src/blenderbim/scripts/obj2ifc-meshlab.py

@@ -23,6 +23,7 @@ import pymeshlab
 import ifcopenshell
 import ifcopenshell.api
 import ifcopenshell.api.owner.settings
+import ifcopenshell.guid
 from pathlib import Path
 
 import numpy as np

src/blenderbim/scripts/obj2ifc.py

@@ -23,6 +23,7 @@ import pywavefront
 import ifcopenshell
 import ifcopenshell.api
 import ifcopenshell.api.owner.settings
+import ifcopenshell.guid
 from pathlib import Path
 
 import numpy as np

src/blenderbim/test/tool/test_brick.py

@@ -22,6 +22,7 @@ import brickschema
 import brickschema.persistent
 from brickschema.namespaces import REF, A
 import ifcopenshell
+import ifcopenshell.guid
 import blenderbim.core.tool
 import blenderbim.tool as tool
 from rdflib.namespace import RDF

src/blenderbim/test/tool/test_drawing.py

@@ -21,6 +21,7 @@ from pathlib import Path
 import bpy
 import mathutils
 import ifcopenshell
+import ifcopenshell.guid
 import blenderbim.core.tool
 import blenderbim.tool as tool
 from test.bim.bootstrap import NewFile

src/ifc2ca/_deprecated/ca2ifc.py

@@ -19,6 +19,7 @@
 
 import json
 import ifcopenshell
+import ifcopenshell.guid
 import os
 from datetime import datetime
 

src/ifccityjson/ifccityjson/cityjson2ifc/cityjson2ifc.py

@@ -20,6 +20,7 @@
 import os
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.guid
 from datetime import datetime
 
 from .geometry import GeometryIO

src/ifcfm/ifcfm/basic.py

@@ -72,8 +72,8 @@ def get_facility_data(ifc_file, element):
         "ModelProjectID": ifc_file.by_type("IfcProject")[0].GlobalId,
         "ModelSiteID": getattr(get_facility_parent(element, "IfcSite"), "GlobalId", None),
         "ModelBuildingID": element.GlobalId,
-        "LinearUnits": "millimeters",
-        "AreaUnits": "square meters",
+        "LengthUnit": "millimeters",
+        "AreaUnit": "square meters",
         "Phase": ifc_file.by_type("IfcProject")[0].Phase,
     }
 
@@ -99,7 +99,7 @@ def get_space_data(ifc_file, element):
         "Description": element.LongName,
         "ClassificationIdentification": get_classification_identification(element),
         "ClassificationName": get_classification_name(element),
-        "LevelName": getattr(get_facility_parent(element, "IfcBuildingStorey"), "Name", None),
+        "StoreyName": getattr(get_facility_parent(element, "IfcBuildingStorey"), "Name", None),
         "OrganizationName": get_owner_name(element),
         "CreationDate": get_owner_creation_date(element),
         "ModelSoftware": get_owner_application(element),
@@ -261,8 +261,8 @@ config = {
                 "ModelProjectID",
                 "ModelSiteID",
                 "ModelBuildingID",
-                "LinearUnits",
-                "AreaUnits",
+                "LengthUnit",
+                "AreaUnit",
                 "Phase",
             ],
             "colours": "ppppreeeeesss",
@@ -295,7 +295,7 @@ config = {
                 "Description",
                 "ClassificationIdentification",
                 "ClassificationName",
-                "LevelName",
+                "StoreyName",
                 "OrganizationName",
                 "CreationDate",
                 "ModelSoftware",
@@ -305,7 +305,7 @@ config = {
                 "NetFloorArea",
             ],
             "colours": "ppprreeess",
-            "sort": [{"name": "LevelName", "order": "ASC"}, {"name": "Name", "order": "ASC"}],
+            "sort": [{"name": "StoreyName", "order": "ASC"}, {"name": "Name", "order": "ASC"}],
             "get_category_elements": get_spaces,
             "get_element_data": get_space_data,
         },

src/ifcfm/ifcfm/cobie24legacy.py

@@ -17,6 +17,7 @@
 # along with IfcFM.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell
+import ifcopenshell.guid
 import ifcopenshell.util.fm
 import ifcopenshell.util.date
 import ifcopenshell.util.system

src/ifcopenshell-python/docs/_autoapi_templates/index.rst

@@ -0,0 +1,16 @@
+Python API Reference
+====================
+
+This page contains auto-generated API reference documentation [#f1]_.
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   {% for page in pages %}
+   {% if page.top_level_object and page.display %}
+   {{ page.include_path }}
+   {% endif %}
+   {% endfor %}
+
+.. [#f1] Created with `sphinx-autoapi <https://github.com/readthedocs/sphinx-autoapi>`_

src/ifcopenshell-python/docs/_autoapi_templates/python/module.rst

@@ -0,0 +1,114 @@
+{% if not obj.display %}
+:orphan:
+
+{% endif %}
+:py:mod:`{{ obj.name }}`
+=========={{ "=" * obj.name|length }}
+
+.. py:module:: {{ obj.name }}
+
+{% if obj.docstring %}
+.. autoapi-nested-parse::
+
+   {{ obj.docstring|indent(3) }}
+
+{% endif %}
+
+{% block subpackages %}
+{% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
+{% if visible_subpackages %}
+Subpackages
+-----------
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+{% for subpackage in visible_subpackages %}
+   {{ subpackage.short_name }}/index.rst
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+{% block submodules %}
+{% set visible_submodules = obj.submodules|selectattr("display")|list %}
+{% if visible_submodules %}
+Submodules
+----------
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+{% for submodule in visible_submodules %}
+   {{ submodule.short_name }}/index.rst
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+{% block content %}
+{% if obj.all is not none %}
+{% set visible_children = obj.children|selectattr("short_name", "in", obj.all)|list %}
+{% elif obj.type is equalto("package") %}
+{% set visible_children = obj.children|selectattr("display")|list %}
+{% else %}
+{% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %}
+{% endif %}
+{% if visible_children %}
+{{ obj.type|title }} Contents
+{{ "-" * obj.type|length }}---------
+
+{% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %}
+{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %}
+{% set visible_attributes = visible_children|selectattr("type", "equalto", "data")|list %}
+{% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %}
+{% block classes scoped %}
+{% if visible_classes %}
+Classes
+~~~~~~~
+
+.. autoapisummary::
+
+{% for klass in visible_classes %}
+   {{ klass.id }}
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+
+{% block functions scoped %}
+{% if visible_functions %}
+Functions
+~~~~~~~~~
+
+.. autoapisummary::
+
+{% for function in visible_functions %}
+   {{ function.id }}
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+
+{% block attributes scoped %}
+{% if visible_attributes %}
+Attributes
+~~~~~~~~~~
+
+.. autoapisummary::
+
+{% for attribute in visible_attributes %}
+   {{ attribute.id }}
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+{% endif %}
+{% for obj_item in visible_children %}
+{{ obj_item.render()|indent(0) }}
+{% endfor %}
+{% endif %}
+{% endblock %}

src/ifcopenshell-python/docs/_static/custom.css

@@ -8,6 +8,9 @@ h1, h2, h3, h4 {
     -webkit-background-clip: text;
     -webkit-text-fill-color: transparent;
 }
+h1 code.literal {
+    background: none;
+}
 a {
     text-decoration: none;
 }
@@ -16,6 +19,7 @@ a {
 }
 .sidebar-brand-text {
     font-size: 1rem;
+    text-align: center;
 }
 .blockbutton {
     max-width: 500px;
@@ -47,14 +51,32 @@ section img {
     box-shadow: rgba(0, 0, 0, 0.24) 0px 3px 8px;
     border-radius: 5px;
 }
+
+/* Make it clearer which signatures are part of a class */
 .py.class {
-    /* Make it clearer which signatures are part of a class */
     border-left: 3px solid var(--color-brand-primary);
 }
-.py.function, .py.method {
-    /* Make it clearer which signatures are part of a method or function */
-    border-left: 3px solid var(--color-background-item);
+.py.class > .sig {
+    background: var(--color-brand-primary) !important;
+    margin: 0;
+    border-radius: 0;
 }
+.py.class > .sig * {
+    color: #2e3436 !important;
+}
+.py.class > .sig a {
+    color: #fff;
+}
+
+/* Make it easier to spot functions and methods */
+.py.function, .py.method {
+    border-top: 1px solid var(--color-background-item);
+}
+dl.py.property, dl.py.attribute, dl.py.method, dl.py.function {
+    padding-top: 10px;
+    padding-bottom: 10px;
+}
+
 .field-list > dt {
     /* Clearly distinguish parameters otherwise it looks like a wall of text */
     color: var(--color-brand-content);

src/ifcopenshell-python/docs/conf.py

@@ -74,6 +74,9 @@ autoapi_dirs = ['../ifcopenshell', '../../bcf/src', '../../bsdd', '../../ifccsv'
 # These are auto-generated based on the IFC schema, so exclude them
 autoapi_ignore = ['*ifcopenshell/express/rules*']
 
+# Custom autoapi templates to make it easier to read our docs
+autoapi_template_dir = "_autoapi_templates"
+
 # autoapi_options doesn't have show-module-summary, as it tends to create one
 # page per function which contradicts the presentation of showing all functions
 # as a list. This creates two possible locations where a function is documented
@@ -81,7 +84,7 @@ autoapi_ignore = ['*ifcopenshell/express/rules*']
 # ifcopenshell.file is imported from ifcopenshell.file.file, but it gets pretty
 # confusing to see the docs again in multiple places (seriously,
 # ifcopenshell.file.file is everywhere).
-autoapi_options = ['members', 'undoc-members', 'private-members', 'special-members', 'show-inheritance']
+autoapi_options = ['members', 'undoc-members', 'show-inheritance', 'imported-members']
 
 # This option is set to both to allow both class docstrings and __init__ docstrings.
 autoapi_python_class_content = 'both'
@@ -130,7 +133,10 @@ html_theme_options = {
         "color-background-border": "#cfd0cb",
         "color-foreground-primary": "#2e3436",
         "color-sidebar-item-background--hover": "#f7f7f6",
+        "color-link": "#39b54a",
+        "color-link--visited": "#39b54a",
         "color-link--hover": "#d98014",
+        "color-link--visited--hover": "#d98014",
         "font-stack": "Nunito, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji"
     },
     "dark_css_variables": {
@@ -141,7 +147,10 @@ html_theme_options = {
         "color-background-border": "#2e3436",
         "color-foreground-primary": "#eeeeec",
         "color-sidebar-item-background--hover": "#2e3436",
+        "color-link": "#39b54a",
+        "color-link--visited": "#39b54a",
         "color-link--hover": "#d98014",
+        "color-link--visited--hover": "#d98014",
         "font-stack": "Nunito, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji"
     },
 

src/ifcopenshell-python/docs/introduction/how_to_contribute.rst

@@ -21,14 +21,15 @@ Python API documentation is autogenerated from docstrings present in the source
 code of the respective Python module.
 
 If you want to build the documentation locally, the documentation system uses
-`Sphinx <https://www.sphinx-doc.org/en/master/>`_. First, install the theme and
-theme dependencies:
+`Sphinx <https://www.sphinx-doc.org/en/master/>`_. First, install Sphinx and
+dependencies:
 
 .. code-block:: console
 
-    $ pip install furo
+    $ pip install sphinx
     $ pip install sphinx-autoapi
     $ pip install sphinx-copybutton
+    $ pip install furo
 
 Now you can generate the documentation:
 

src/ifcopenshell-python/ifcopenshell/__init__.py

@@ -16,32 +16,51 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
-"""The entry module for IfcOpenShell
+"""Welcome to IfcOpenShell! IfcOpenShell provides a way to read and write IFCs.
 
-Typically used for opening an IFC via a filepath, or accessing one of the
-submodules.
+IfcOpenShell can open IFC files, read entities (such as walls, buildings,
+properties, systems, etc), edit attributes, write out ``.ifc`` files and more.
+
+This module provides primitive functions to interact with IFC, including:
+
+- For most users, you can open and read IFC models, see docs for :func:`open`.
+  This returns an :class:`file` object representing the IFC model. You can then
+  query the model to filter elements.
+- For developers, you can query the schema itself, see docs for
+  :func:`schema_by_name`. This returns a schema object which you can use to
+  analyse the definitions of IFC classes and data types.
+
+You may also be interested in:
+
+- For model authoring and editing operations, see :mod:`ifcopenshell.api`.
+- For extracting information from models, see :mod:`ifcopenshell.util`.
+- For processing geometry, see :mod:`ifcopenshell.geom`.
+
+
+For more details, consult https://docs.ifcopenshell.org/
 
 Example:
 
 .. code:: python
 
     import ifcopenshell
-    print(ifcopenshell.version) # v0.7.0-1b1fd1e6
-    model = ifcopenshell.open("/path/to/model.ifc")
-"""
 
-from __future__ import absolute_import
-from __future__ import division
-from __future__ import print_function
+    print(ifcopenshell.version) # v0.7.0-1b1fd1e6
+
+    model = ifcopenshell.open("/path/to/model.ifc")
+    walls = model.by_type("IfcWall")
+
+    for wall in walls:
+        print(wall.Name)
+"""
 
 import os
 import sys
-import tempfile
 import zipfile
+import tempfile
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Union
 
-import ifcopenshell.util.file
 
 if hasattr(os, "uname"):
     platform_system = os.uname()[0].lower()
@@ -60,22 +79,29 @@ sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "lib", p
 
 try:
     from . import ifcopenshell_wrapper
-except Exception as e:
-    if int(python_version_tuple[0]) == 2:
-        # Only for py2, as py3 has exception chaining
-        import traceback
-
-        traceback.print_exc()
-        print("-" * 64)
+except Exception:
     raise ImportError("IfcOpenShell not built for '%s'" % python_distribution)
 
-from . import guid
 from .file import file
 from .entity_instance import entity_instance, register_schema_attributes
 from .sql import sqlite, sqlite_entity
+
+# explicitly specify available imported symbols
+# (it's a requirement for a typed library)
+__all__ = [
+    "ifcopenshell_wrapper",
+    "file",
+    "entity_instance",
+    "sqlite",
+    "sqlite_entity",
+    "stream",
+    "stream_entity",
+]
+
 try:
     from .stream import stream, stream_entity
-except: pass
+except:
+    pass
 
 READ_ERROR = ifcopenshell_wrapper.file_open_status.READ_ERROR
 NO_HEADER = ifcopenshell_wrapper.file_open_status.NO_HEADER
@@ -84,19 +110,22 @@ UNSUPPORTED_SCHEMA = ifcopenshell_wrapper.file_open_status.UNSUPPORTED_SCHEMA
 
 class Error(Exception):
     """Error used when a generic problem occurs"""
+
     pass
 
 
 class SchemaError(Error):
     """Error used when an IFC schema related problem occurs"""
+
     pass
 
 
-def open(path: "os.PathLike | str", format: str = None, should_stream: bool = False) -> file:
+def open(path: Union[os.PathLike, str], format: Optional[str] = None, should_stream: bool = False) -> file:
     """Loads an IFC dataset from a filepath
 
-    You can specify a file format. If no format is given, it is guessed from its extension.
-    Currently supported specified format : .ifc | .ifcZIP | .ifcXML
+    You can specify a file format. If no format is given, it is guessed from
+    its extension. Currently supported specified format: .ifc | .ifcZIP |
+    .ifcXML.
 
     You can then filter by element ID, class, etc, and subscript by id or guid.
 
@@ -114,7 +143,7 @@ def open(path: "os.PathLike | str", format: str = None, should_stream: bool = Fa
     """
     path = Path(path)
     if format is None:
-        format = ifcopenshell.util.file.guess_format(path)
+        format = guess_format(path)
     if format == ".ifcXML":
         f = ifcopenshell_wrapper.parse_ifcxml(str(path.absolute()))
         if f:
@@ -141,8 +170,7 @@ def open(path: "os.PathLike | str", format: str = None, should_stream: bool = Fa
             NO_HEADER: (Error, "Unable to parse IFC SPF header"),
             UNSUPPORTED_SCHEMA: (
                 SchemaError,
-                "Unsupported schema: %s"
-                % ",".join(f.header.file_schema.schema_identifiers),
+                "Unsupported schema: %s" % ",".join(f.header.file_schema.schema_identifiers),
             ),
         }[f.good().value()]
         raise exc(msg)
@@ -152,7 +180,7 @@ def create_entity(type, schema="IFC4", *args, **kwargs):
     """Creates a new IFC entity that does not belong to an IFC file object
 
     Note that it is more common to create entities within a existing file
-    object. See :meth:`ifcopenshell.file.file.create_entity`.
+    object. See :meth:`ifcopenshell.file.create_entity`.
 
     :param type: Case insensitive name of the IFC class
     :type type: string
@@ -161,7 +189,7 @@ def create_entity(type, schema="IFC4", *args, **kwargs):
     :param args: The positional arguments of the IFC class
     :param kwargs: The keyword arguments of the IFC class
     :returns: An entity instance
-    :rtype: ifcopenshell.entity_instance.entity_instance
+    :rtype: ifcopenshell.entity_instance
 
     Example:
 
@@ -226,4 +254,35 @@ def schema_by_name(
     return ifcopenshell_wrapper.schema_by_name(schema)
 
 
-from .main import *
+def guess_format(path: Path) -> Union[str | None]:
+    """Guesses the IFC format using file extension
+
+    IFCs may be serialised as different formats. The most common is a ``.ifc``
+    file, which is plaintext and stores data using the STEP Physical File
+    format. IFC can also be stored as a Zipfile, XML, JSON, or SQL.
+
+    This will return the canonical form of the format. For example, if a path
+    has the extension of .xml or .ifcxml (case insensitive), it will return
+    .ifcXML.
+
+    Users generally won't call this function. The :func:`open` function uses
+    this internally to guess the file format.
+
+    :return: Either .ifc, .ifcZIP, .ifcXML, .ifcJSON, .ifcSQLite, or None.
+    """
+    suffix = path.suffix.lower()
+    if suffix == ".ifc":
+        return ".ifc"
+    elif suffix in (".ifczip", ".zip"):
+        return ".ifcZIP"
+    elif suffix in (".ifcxml", ".xml"):
+        return ".ifcXML"
+    elif suffix in (".ifcjson", ".json"):
+        return ".ifcJSON"
+    elif suffix in (".ifcsqlite", ".sqlite", ".db"):
+        return ".ifcSQLite"
+    return None
+
+
+version = ifcopenshell_wrapper.version()
+get_log = ifcopenshell_wrapper.get_log

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

@@ -16,21 +16,39 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
-"""High level user-oriented IFC authoring capabilities"""
+"""High level IFC authoring and editing functions
+
+Authoring, editing, and deleting IFC data requires a detailed understanding of
+the rules of the IFC schema. This API module provides simple to use authoring
+functions that hide this complexity from you. Things like managing differences
+between IFC versions, tracking owernship changes, or cleaning up after orphaned
+relationships are all handled automatically.
+
+If you're new to IFC authoring, start by looking at the following APIs:
+
+- See :func:`ifcopenshell.api.project.create_file` to create a new IFC.
+- See :func:`ifcopenshell.api.root.create_entity` to create new entities, like
+  the mandatory IfcProject, and then an IfcSite, IfcWall, etc.
+- See :func:`ifcopenshell.api.aggregate.assign_object` to create a spatial
+  hierarchy.
+- See :func:`ifcopenshell.api.spatial.assign_container` to place physical
+  elements (e.g. walls) inside spatial elements (e.g. building storeys).
+
+Also see how to `create a simple model from scratch
+<https://docs.ifcopenshell.org/ifcopenshell-python/code_examples.html#create-a-simple-model-from-scratch>`_.
+"""
 
 import json
 import numpy
-import pkgutil
 import inspect
 import importlib
 import ifcopenshell
-import ifcopenshell.api
 from typing import Callable, Any, Optional
 from functools import partial
 
 
-pre_listeners = {}
-post_listeners = {}
+pre_listeners: dict[str, dict] = {}
+post_listeners: dict[str, dict] = {}
 
 
 def batching_argument_deprecation(
@@ -128,8 +146,8 @@ ARGUMENTS_DEPRECATION = {
 }
 
 
-CACHED_USECASE_CLASSES = {}
-CACHED_USECASES = {}
+CACHED_USECASE_CLASSES: dict[str, Callable] = {}
+CACHED_USECASES: dict[str, Callable] = {}
 
 
 def run(
@@ -152,34 +170,6 @@ def run(
         for listener in pre_listeners.get(usecase_path, {}).values():
             listener(usecase_path, ifc_file, settings)
 
-    # see #4531
-    if usecase_path in ARGUMENTS_DEPRECATION:
-        usecase_path, settings = ARGUMENTS_DEPRECATION[usecase_path](usecase_path, settings)
-
-    # TODO: settings serialization for client-server systems
-    # def serialise_entity_instance(entity):
-    #     return {"cast_type": "entity_instance", "value": entity.id(), "Name": getattr(entity, "Name", None)}
-    # vcs_settings = settings.copy()
-    # for key, value in settings.items():
-    #     if isinstance(value, ifcopenshell.entity_instance):
-    #         vcs_settings[key] = serialise_entity_instance(value)
-    #     elif isinstance(value, numpy.ndarray):
-    #         vcs_settings[key] = {"cast_type": "ndarray", "value": value.tolist()}
-    #     elif isinstance(value, list) and value and isinstance(value[0], ifcopenshell.entity_instance):
-    #         vcs_settings[key] = [serialise_entity_instance(i) for i in value]
-    if "add_representation" in usecase_path:
-        pass
-        # print(usecase_path, "{ ... settings too complex right now ... }")
-    elif "owner." in usecase_path:
-        pass
-    else:
-        pass
-        # print(vcs_settings)
-        # try:
-        #    print(usecase_path, json.dumps(vcs_settings))
-        # except:
-        #    print(usecase_path, vcs_settings)
-
     usecase_class = CACHED_USECASE_CLASSES.get(usecase_path)
     if usecase_class is None:
         importlib.import_module(f"ifcopenshell.api.{usecase_path}")
@@ -250,8 +240,6 @@ def extract_docs(module, usecase):
     import typing
     import collections
 
-    results = []
-
     inputs = collections.OrderedDict()
 
     function_init = getattr(getattr(ifcopenshell.api, module), usecase).Usecase.__init__
@@ -295,23 +283,55 @@ def extract_docs(module, usecase):
     return node_data
 
 
+def serialise_settings(settings):
+    def serialise_entity_instance(entity):
+        return {"cast_type": "entity_instance", "value": entity.id(), "Name": getattr(entity, "Name", None)}
+
+    vcs_settings = settings.copy()
+    for key, value in settings.items():
+        if isinstance(value, ifcopenshell.entity_instance):
+            vcs_settings[key] = serialise_entity_instance(value)
+        elif isinstance(value, numpy.ndarray):
+            vcs_settings[key] = {"cast_type": "ndarray", "value": value.tolist()}
+        elif isinstance(value, list) and value and isinstance(value[0], ifcopenshell.entity_instance):
+            vcs_settings[key] = [serialise_entity_instance(i) for i in value]
+        else:
+            try:
+                vcs_settings[key] = str(value)
+            except:
+                vcs_settings[key] = "n/a"
+    try:
+        return json.dumps(vcs_settings)
+    except:
+        return str(vcs_settings)
+
+
 def wrap_usecase(usecase_path, usecase):
     """Wraps an API function in pre/post listeners."""
 
     def wrapper(*args, should_run_listeners: bool = True, **settings):
         ifc_file = args[0] if args else None
+        nonlocal usecase_path
         if should_run_listeners:
-            for listener in pre_listeners.get(usecase_path, {}).values():
+            listeners = list(pre_listeners.get(usecase_path, {}).values())
+            listeners += pre_listeners.get("*", {}).values()
+            for listener in listeners:
                 listener(usecase_path, ifc_file, settings)
 
+        # see #4531
+        if usecase_path in ARGUMENTS_DEPRECATION:
+            usecase_path, settings = ARGUMENTS_DEPRECATION[usecase_path](usecase_path, settings)
+
         try:
             result = usecase(*args, **settings)
         except TypeError as e:
-            msg = f"Incorrect function arguments provided for {usecase_path}\n{str(e)}. You specified args {args} and settings {settings}\n\nCorrect signature is {inspect.signature(Usecase.__init__)}\nSee help(ifcopenshell.api.{usecase_path}) for documentation."
+            msg = f"Incorrect function arguments provided for {usecase_path}\n{str(e)}. You specified args {args} and settings {settings}\n\nCorrect signature is {inspect.signature(usecase)}\nSee help(ifcopenshell.api.{usecase_path}) for documentation."
             raise TypeError(msg) from e
 
         if should_run_listeners:
-            for listener in post_listeners.get(usecase_path, {}).values():
+            listeners = list(post_listeners.get(usecase_path, {}).values())
+            listeners += post_listeners.get("*", {}).values()
+            for listener in listeners:
                 listener(usecase_path, ifc_file, settings)
 
         return result
@@ -322,50 +342,16 @@ def wrap_usecase(usecase_path, usecase):
     return wrapper
 
 
-# Expose all submodules. This means that the user can just type `import ifcopenshell.api`.
-import ifcopenshell.api.aggregate as aggregate
-import ifcopenshell.api.attribute as attribute
-import ifcopenshell.api.boundary as boundary
-import ifcopenshell.api.classification as classification
-import ifcopenshell.api.constraint as constraint
-import ifcopenshell.api.context as context
-import ifcopenshell.api.control as control
-import ifcopenshell.api.cost as cost
-import ifcopenshell.api.document as document
-import ifcopenshell.api.drawing as drawing
-import ifcopenshell.api.geometry as geometry
-import ifcopenshell.api.georeference as georeference
-import ifcopenshell.api.grid as grid
-import ifcopenshell.api.group as group
-import ifcopenshell.api.layer as layer
-import ifcopenshell.api.library as library
-import ifcopenshell.api.material as material
-import ifcopenshell.api.nest as nest
-import ifcopenshell.api.owner as owner
-import ifcopenshell.api.profile as profile
-import ifcopenshell.api.project as project
-import ifcopenshell.api.pset as pset
-import ifcopenshell.api.pset_template as pset_template
-import ifcopenshell.api.resource as resource
-import ifcopenshell.api.root as root
-import ifcopenshell.api.sequence as sequence
-import ifcopenshell.api.spatial as spatial
-import ifcopenshell.api.structural as structural
-import ifcopenshell.api.style as style
-import ifcopenshell.api.system as system
-import ifcopenshell.api.type as type  # Whoohoo!
-import ifcopenshell.api.unit as unit
-import ifcopenshell.api.void as void
+def wrap_usecases(path, name):
+    """This developer feature wraps an API module's usecases with listeners."""
+    import sys
+    import pkgutil
 
-# Wrap all submodule usecases with listeners.
-# This for loop also conveniently ensures that the above imports are comprehensive.
-for loader, module_name, is_pkg in pkgutil.iter_modules(__path__, __name__ + "."):
-    # Check if it's a direct child (only one level deep)
-    if module_name.count(".") == __name__.count(".") + 1:
-        module_name = module_name.split(".")[-1]
-        module = globals()[module_name]
-        for usecase_name in vars(module):
-            usecase = getattr(module, usecase_name)
-            if callable(usecase):
-                usecase_path = f"{module_name}.{usecase_name}"
-                setattr(module, usecase_name, wrap_usecase(usecase_path, usecase))
+    module_name = name.split(".")[-1]
+    module = sys.modules[name]
+    for loader, usecase_name, is_pkg in pkgutil.iter_modules(path):
+        # We may not be able to get the usecase if we are missing a dependency.
+        usecase = getattr(module, usecase_name, None)
+        if callable(usecase):
+            usecase_path = f"{module_name}.{usecase_name}"
+            setattr(module, usecase_name, wrap_usecase(usecase_path, usecase))

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

@@ -16,12 +16,15 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Aggregates are the concept of breaking down larger wholes into smaller parts.
+"""Aggregates is the concept of breaking down larger wholes into smaller parts.
 
-One common use is spatial elements, such as how a site has multiple buildings,
-and a building has multiple storeys. Another is for regular elements, such as
-how a wall is made out of members and coverings.
+For example, spatial elements such as sites are broken down into one or more
+buildings, and a building is broken down into storeys. Another example is for
+physical elements, such as how a wall is made out of members and coverings.
 """
 
+from .. import wrap_usecases
 from .assign_object import assign_object
 from .unassign_object import unassign_object
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/aggregate/assign_object.py

@@ -18,6 +18,7 @@
 
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.guid
 import ifcopenshell.util.element
 import ifcopenshell.util.placement
 from typing import Union

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

@@ -16,4 +16,14 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Basic modification of the attributes of an element.
+
+All IFC entities have attributes. Some of these attributes contain rules about
+inheritance and what they are allowed to contain. These usecases make sure that
+any editing complies with these rules.
+"""
+
+from .. import wrap_usecases
 from .edit_attributes import edit_attributes
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/attribute/edit_attributes.py

@@ -17,9 +17,11 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell.api
+import ifcopenshell.util.element
+from typing import Any
 
 
-def edit_attributes(file, product=None, attributes=None) -> None:
+def edit_attributes(file: ifcopenshell.file, product: ifcopenshell.entity_instance, attributes: dict[str, Any]) -> None:
     """Edit the attributes of a product
 
     All IFC entities have attributes. Normally they can be edited directly,
@@ -31,7 +33,7 @@ def edit_attributes(file, product=None, attributes=None) -> None:
         entity.
     :type product: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

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

@@ -18,9 +18,15 @@
 
 """Boundaries are primarily used for representing virtual interfaces between
 spaces for energy analysis.
+
+Boundaries may be associated with spaces or physical elements that enclose
+spaces such as walls, doors, and windows.
 """
 
+from .. import wrap_usecases
 from .assign_connection_geometry import assign_connection_geometry
 from .copy_boundary import copy_boundary
 from .edit_attributes import edit_attributes
 from .remove_boundary import remove_boundary
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/boundary/assign_connection_geometry.py

@@ -17,17 +17,18 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell.util.unit
+from typing import Optional
 
 
 def assign_connection_geometry(
-    file,
-    rel_space_boundary=None,
-    outer_boundary=None,
-    inner_boundaries=None,
-    location=None,
-    axis=None,
-    ref_direction=None,
-    unit_scale=None,
+    file: ifcopenshell.file,
+    rel_space_boundary: ifcopenshell.entity_instance,
+    outer_boundary: list[tuple[float, float]],
+    location: tuple[float, float, float],
+    axis: tuple[float, float, float],
+    ref_direction: tuple[float, float, float],
+    inner_boundaries: Optional[list[list[tuple[float, float]]]] = None,
+    unit_scale: Optional[float] = None,
 ) -> None:
     """Create and assign a connection geometry to a space boundary relationship
 
@@ -44,24 +45,24 @@ def assign_connection_geometry(
         polyline.  The last point will connect to the first point. Each
         point is represented by an interable of 2 floats. The coordinates of
         the points are relative to the positional matrix arguments.
-    :type outer_boundary: list[list[float]]
+    :type outer_boundary: list[tuple[float, float]]
     :param inner_boundaries: A list of zero or more inner boundaries to use
         for the plane. Each boundary is represented by an open polyline, as
         defined by the outer_boundary argument.
-    :type inner_boundaries: list[list[list[float]]], optional
+    :type inner_boundaries: list[list[tuple[float, float]]], optional
     :param location: The local origin of the connection geometry, defined as
         an XYZ coordinate relative to the placement of the space that is
         being bounded.
-    :type location: list[float]
+    :type location: tuple[float, float, float]
     :param axis: The local X axis of the connection geometry, defined as an
         XYZ vector relative to the placement of the space that is being
         bounded.
-    :type axis: list[float]
+    :type axis: tuple[float, float, float]
     :param ref_direction: The local Z axis of the connection geometry,
         defined as an XYZ vector relative to the placement of the space that
         is being bounded. The Y vector is automatically derived using the
         right hand rule.
-    :type ref_direction: list[float]
+    :type ref_direction: tuple[float, float, float]
     :param unit_scale: The unit scale as calculated by
         ifcopenshell.util.unit.calculate_unit_scale. If not provided, it
         will be automatically calculated for you.

src/ifcopenshell-python/ifcopenshell/api/boundary/copy_boundary.py

@@ -19,13 +19,13 @@
 import ifcopenshell.util.element
 
 
-def copy_boundary(file, boundary=None) -> None:
+def copy_boundary(file: ifcopenshell.file, boundary: ifcopenshell.entity_instance) -> ifcopenshell.entity_instance:
     """Copies a space boundary
 
     :param boundary: The IfcRelSpaceBoundary you want to copy.
     :type boundary: ifcopenshell.entity_instance
-    :return: None
-    :rtype: None
+    :return: Duplicate of the IfcRelSpaceBoundary
+    :rtype: ifcopenshell.entity_instance
 
     Example:
 

src/ifcopenshell-python/ifcopenshell/api/boundary/edit_attributes.py

@@ -15,15 +15,17 @@
 #
 # 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 ifcopenshell
+from typing import Optional
 
 
 def edit_attributes(
-    file,
-    entity=None,
-    relating_space=None,
-    related_building_element=None,
-    parent_boundary=None,
-    corresponding_boundary=None,
+    file: ifcopenshell.file,
+    entity: ifcopenshell.entity_instance,
+    relating_space: ifcopenshell.entity_instance,
+    related_building_element: ifcopenshell.entity_instance,
+    parent_boundary: Optional[ifcopenshell.entity_instance] = None,
+    corresponding_boundary: Optional[ifcopenshell.entity_instance] = None,
 ) -> None:
     """Modify the relationships of a space boundary relationship
 

src/ifcopenshell-python/ifcopenshell/api/boundary/remove_boundary.py

@@ -20,7 +20,7 @@ import ifcopenshell
 import ifcopenshell.util.element
 
 
-def remove_boundary(file, boundary=None) -> None:
+def remove_boundary(file: ifcopenshell.file, boundary: ifcopenshell.entity_instance) -> None:
     """Removes a space boundary
 
     The relating space or related building element is untouched. Only the

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

@@ -16,9 +16,23 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Classification systems are a way of categorising objects
+
+Although IFC itself comes with a built-in classification hierarchy (e.g.
+IfcWall and its predefined types of PARTITIONING, etc), there are many external
+or custom classification systems such as Uniclass, Omniclass and more. IFC is
+able to integrate with any external classification system.
+
+This API allows you to manage and assign external classification systems and
+references.
+"""
+
+from .. import wrap_usecases
 from .add_classification import add_classification
 from .add_reference import add_reference
 from .edit_classification import edit_classification
 from .edit_reference import edit_reference
 from .remove_classification import remove_classification
 from .remove_reference import remove_reference
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/classification/add_classification.py

@@ -17,6 +17,7 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell
+import ifcopenshell.guid
 import ifcopenshell.util.schema
 import ifcopenshell.util.date
 from typing import Union

src/ifcopenshell-python/ifcopenshell/api/classification/add_reference.py

@@ -18,6 +18,7 @@
 
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.guid
 import ifcopenshell.util.element
 import ifcopenshell.util.schema
 from typing import Optional, Union

src/ifcopenshell-python/ifcopenshell/api/classification/edit_classification.py

@@ -15,9 +15,13 @@
 #
 # 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 ifcopenshell
+from typing import Any
 
 
-def edit_classification(file, classification=None, attributes=None) -> None:
+def edit_classification(
+    file: ifcopenshell.file, classification: ifcopenshell.entity_instance, attributes: dict[str, Any]
+) -> None:
     """Edits the attributes of an IfcClassification
 
     For more information about the attributes and data types of an
@@ -26,7 +30,7 @@ def edit_classification(file, classification=None, attributes=None) -> None:
     :param classification: The IfcClassification entity you want to edit
     :type classification: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

src/ifcopenshell-python/ifcopenshell/api/classification/edit_reference.py

@@ -15,9 +15,13 @@
 #
 # 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 ifcopenshell
+from typing import Any
 
 
-def edit_reference(file, reference=None, attributes=None) -> None:
+def edit_reference(
+    file: ifcopenshell.file, reference: ifcopenshell.entity_instance, attributes: dict[str, Any]
+) -> None:
     """Edits the attributes of an IfcClassificationReference
 
     For more information about the attributes and data types of an
@@ -26,7 +30,7 @@ def edit_reference(file, reference=None, attributes=None) -> None:
     :param reference: The IfcClassificationReference entity you want to edit
     :type reference: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

src/ifcopenshell-python/ifcopenshell/api/classification/remove_classification.py

@@ -20,7 +20,7 @@ import ifcopenshell
 import ifcopenshell.util.element
 
 
-def remove_classification(file: ifcopenshell.entity_instance, classification: ifcopenshell.entity_instance) -> None:
+def remove_classification(file: ifcopenshell.file, classification: ifcopenshell.entity_instance) -> None:
     """Removes an IfcClassification from the project and all references
 
     The classification and all of its relationships, children references,
@@ -58,15 +58,20 @@ class Usecase:
                 self.file.remove(rel)
                 if history:
                     ifcopenshell.util.element.remove_deep2(self.file, history)
-        for rel in self.file.by_type("IfcExternalReferenceRelationship"):
-            if not rel.RelatingReference:
-                self.file.remove(rel)
 
-    def get_references(self, classification):
+        if self.file.schema != "IFC2X3":
+            for rel in self.file.by_type("IfcExternalReferenceRelationship"):
+                if not rel.RelatingReference:
+                    self.file.remove(rel)
+
+    def get_references(self, classification: ifcopenshell.entity_instance) -> list[ifcopenshell.entity_instance]:
         results = []
-        if not classification.HasReferences:
-            return results
-        for reference in classification.HasReferences:
-            results.append(reference)
-            results.extend(self.get_references(reference))
+        if self.file.schema == "IFC2X3":
+            for reference in self.file.by_type("IfcClassificationReference"):
+                if reference.ReferencedSource == classification:
+                    results.append(reference)
+        else:
+            for reference in classification.HasReferences:
+                results.append(reference)
+                results.extend(self.get_references(reference))
         return results

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

@@ -16,6 +16,13 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Constraints are an advanced feature allowing you to specify parametric
+limits on properties
+
+Warning: usage of constraints are mostly untested in real life applications.
+"""
+
+from .. import wrap_usecases
 from .add_metric import add_metric
 from .add_metric_reference import add_metric_reference
 from .add_objective import add_objective
@@ -25,3 +32,5 @@ from .edit_objective import edit_objective
 from .remove_constraint import remove_constraint
 from .remove_metric import remove_metric
 from .unassign_constraint import unassign_constraint
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/constraint/add_metric.py

@@ -19,7 +19,7 @@
 import ifcopenshell
 
 
-def add_metric(file, objective=None) -> None:
+def add_metric(file: ifcopenshell.file, objective: ifcopenshell.entity_instance) -> ifcopenshell.entity_instance:
     """Add a new metric benchmark
 
     Qualitative constraints may have a series of quantitative benchmarks
@@ -50,7 +50,7 @@ def add_metric(file, objective=None) -> None:
             "Name": "Unnamed",
             "ConstraintGrade": "NOTDEFINED",
             "Benchmark": "EQUALTO",
-        }
+        },
     )
     if settings["objective"]:
         benchmark_values = list(settings["objective"].BenchmarkValues or [])

src/ifcopenshell-python/ifcopenshell/api/constraint/add_metric_reference.py

@@ -19,16 +19,18 @@
 import ifcopenshell
 
 
-def add_metric_reference(file, metric=None, reference_path=None) -> None:
+def add_metric_reference(
+    file: ifcopenshell.file, metric: ifcopenshell.entity_instance, reference_path: str
+) -> list[ifcopenshell.entity_instance]:
     """
     Adds a chain of references to a metric. The reference path is a string of the form "attribute.attribute.attribute"
     Used to reference a value of an attribute of an instance through a metric objective entity.
     """
     settings = {"metric": metric, "reference_path": reference_path}
 
+    references_created = []
     if settings["reference_path"]:
         attributes = settings["reference_path"].split(".")
-        references_created = []
         for i in range(len(attributes)):
             if i == 0:
                 reference = file.create_entity("IfcReference")
@@ -40,4 +42,4 @@ def add_metric_reference(file, metric=None, reference_path=None) -> None:
                 reference.AttributeIdentifier = attributes[i]
                 references_created[i - 1].InnerReference = reference
                 references_created.append(reference)
-        return references_created
+    return references_created

src/ifcopenshell-python/ifcopenshell/api/constraint/add_objective.py

@@ -19,7 +19,7 @@
 import ifcopenshell
 
 
-def add_objective(file) -> None:
+def add_objective(file: ifcopenshell.file) -> ifcopenshell.entity_instance:
     """Add a new objective constraint
 
     Parametric constraints may be defined by the user. The constraint is defined

src/ifcopenshell-python/ifcopenshell/api/constraint/assign_constraint.py

@@ -18,6 +18,7 @@
 
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.guid
 from typing import Union
 
 

src/ifcopenshell-python/ifcopenshell/api/constraint/edit_metric.py

@@ -15,9 +15,11 @@
 #
 # 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 ifcopenshell
+from typing import Any
 
 
-def edit_metric(file, metric=None, attributes=None) -> None:
+def edit_metric(file: ifcopenshell.file, metric: ifcopenshell.entity_instance, attributes: dict[str, Any]) -> None:
     """Edit the attributes of a metric
 
     For more information about the attributes and data types of an
@@ -26,7 +28,7 @@ def edit_metric(file, metric=None, attributes=None) -> None:
     :param metric: The IfcMetric you want to edit.
     :type metric: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

src/ifcopenshell-python/ifcopenshell/api/constraint/edit_objective.py

@@ -15,9 +15,13 @@
 #
 # 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 ifcopenshell
+from typing import Any
 
 
-def edit_objective(file, objective=None, attributes=None) -> None:
+def edit_objective(
+    file: ifcopenshell.file, objective: ifcopenshell.entity_instance, attributes: dict[str, Any]
+) -> None:
     """Edit the attributes of a objective
 
     For more information about the attributes and data types of an
@@ -26,7 +30,7 @@ def edit_objective(file, objective=None, attributes=None) -> None:
     :param objective: The IfcObjective you want to edit.
     :type objective: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

src/ifcopenshell-python/ifcopenshell/api/constraint/remove_constraint.py

@@ -20,7 +20,7 @@ import ifcopenshell
 import ifcopenshell.util.element
 
 
-def remove_constraint(file, constraint=None) -> None:
+def remove_constraint(file: ifcopenshell.file, constraint: ifcopenshell.entity_instance) -> None:
     """Remove a constraint (typically an objective)
 
     Removes a constraint definition and all of its associations to any

src/ifcopenshell-python/ifcopenshell/api/constraint/remove_metric.py

@@ -15,9 +15,10 @@
 #
 # 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 ifcopenshell
 
 
-def remove_metric(file, metric=None) -> None:
+def remove_metric(file: ifcopenshell.file, metric: ifcopenshell.entity_instance) -> None:
     """Remove a metric benchmark
 
     Removes a metric benchmark and all of its associations to any products

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

@@ -16,6 +16,18 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Contexts allow you to classify when geometry should be used in different
+purposes
+
+For example, a door may have many geometries assigned to it: a 3D body
+geometry, a clearance zone for disabled access and egress, and a 2D top down
+plan view representation annotating swing extents. Each geometry is assigned to
+a context to distinguish its purpose and level of detail.
+"""
+
+from .. import wrap_usecases
 from .add_context import add_context
 from .edit_context import edit_context
 from .remove_context import remove_context
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/context/remove_context.py

@@ -17,9 +17,11 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell
+import ifcopenshell.api
+import ifcopenshell.util.element
 
 
-def remove_context(file: ifcopenshell.entity_instance, context: ifcopenshell.entity_instance) -> None:
+def remove_context(file: ifcopenshell.file, context: ifcopenshell.entity_instance) -> None:
     """Removes an IfcGeometricRepresentationContext
 
     Any representation geometry that is assigned to the context is also

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

@@ -16,5 +16,14 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Processes and costs may be controlled by other entities which indicate
+constraints that determine how they can change
+
+This is an advanced feature mostly used in 4D/5D
+"""
+
+from .. import wrap_usecases
 from .assign_control import assign_control
 from .unassign_control import unassign_control
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/control/assign_control.py

@@ -18,9 +18,15 @@
 
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.guid
+from typing import Union
 
 
-def assign_control(file, relating_control=None, related_object=None) -> None:
+def assign_control(
+    file: ifcopenshell.file,
+    relating_control: ifcopenshell.entity_instance,
+    related_object: ifcopenshell.entity_instance,
+) -> Union[ifcopenshell.entity_instance, None]:
     """Assigns a planning control or constraint to an object
 
     IFC can describe concepts that control other objects. For example, a

src/ifcopenshell-python/ifcopenshell/api/control/unassign_control.py

@@ -19,9 +19,14 @@
 import ifcopenshell
 import ifcopenshell.api
 import ifcopenshell.util.element
+from typing import Union
 
 
-def unassign_control(file, relating_control=None, related_object=None) -> None:
+def unassign_control(
+    file: ifcopenshell.file,
+    relating_control: ifcopenshell.entity_instance,
+    related_object: ifcopenshell.entity_instance,
+) -> Union[ifcopenshell.entity_instance, None]:
     """Unassigns a planning control or constraint to an object
 
     :param relating_control: The IfcControl entity that is creating the

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

@@ -16,6 +16,15 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Manage cost schedules, cost items, cost estimation and parametric quantity
+take-off
+
+IFC supports storing cost schedules and detailed cost breakdown structures,
+including formulas, subtotals, and parametric links to model element
+quantities.
+"""
+
+from .. import wrap_usecases
 from .add_cost_item import add_cost_item
 from .add_cost_item_quantity import add_cost_item_quantity
 from .add_cost_schedule import add_cost_schedule
@@ -35,3 +44,5 @@ from .remove_cost_item_quantity import remove_cost_item_quantity
 from .remove_cost_schedule import remove_cost_schedule
 from .remove_cost_value import remove_cost_value
 from .unassign_cost_item_quantity import unassign_cost_item_quantity
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/cost/add_cost_item.py

@@ -17,22 +17,30 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell.api
+import ifcopenshell.guid
+from typing import Optional
 
 
-def add_cost_item(file, cost_schedule=None, cost_item=None) -> None:
+def add_cost_item(
+    file: ifcopenshell.file,
+    cost_schedule: Optional[ifcopenshell.entity_instance] = None,
+    cost_item: Optional[ifcopenshell.entity_instance] = None,
+) -> ifcopenshell.entity_instance:
     """Add a new cost item
 
     A cost item represents a single line item in a cost schedule. Cost items
     may then be broken down into cost subitems.
 
+    Either `cost_schedule` or `cost_item` must be provided.
+
     :param cost_schedule: If the cost item is to be added as a root or top
         level cost item to a cost schedule, the IfcCostSchedule may be
         specified. This is mutually exlclusive to the cost_item parameter.
-    :type cost_schedule: ifcopenshell.entity_instance
+    :type cost_schedule: ifcopenshell.entity_instance, optional.
     :param cost_item: If the cost item is to be added as a subitem to an
         existing cost item, the parent IfcCostItem may be specified. This is
         mutually exclusive to the cost_schedule parameter.
-    :type cost_item: ifcopenshell.entity_instance
+    :type cost_item: ifcopenshell.entity_instance, optional
     :return: The newly created IfcCostItem
     :rtype: ifcopenshell.entity_instance
 
@@ -61,7 +69,7 @@ def add_cost_item(file, cost_schedule=None, cost_item=None) -> None:
                 "OwnerHistory": ifcopenshell.api.run("owner.create_owner_history", file),
                 "RelatedObjects": [cost_item],
                 "RelatingControl": settings["cost_schedule"],
-            }
+            },
         )
     elif settings["cost_item"]:
         ifcopenshell.api.run(

src/ifcopenshell-python/ifcopenshell/api/cost/add_cost_item_quantity.py

@@ -19,7 +19,9 @@
 import ifcopenshell.api
 
 
-def add_cost_item_quantity(file, cost_item=None, ifc_class="IfcQuantityCount") -> None:
+def add_cost_item_quantity(
+    file: ifcopenshell.file, cost_item: ifcopenshell.entity_instance, ifc_class: str = "IfcQuantityCount"
+) -> ifcopenshell.entity_instance:
     """Adds a new quantity associated with a cost item
 
     Cost items calculate their subtotal by multiplying the sum of the cost

src/ifcopenshell-python/ifcopenshell/api/cost/add_cost_schedule.py

@@ -19,9 +19,10 @@
 import ifcopenshell.api
 import ifcopenshell.util.date
 from datetime import datetime
+from typing import Optional
 
 
-def add_cost_schedule(file, name=None, predefined_type="NOTDEFINED") -> None:
+def add_cost_schedule(file: ifcopenshell.file, name: Optional[str] = None, predefined_type="NOTDEFINED") -> None:
     """Add a new cost schedule
 
     A cost schedule is a group of cost items which typically represent a
@@ -61,5 +62,17 @@ def add_cost_schedule(file, name=None, predefined_type="NOTDEFINED") -> None:
         predefined_type=settings["predefined_type"],
         name=settings["name"],
     )
-    cost_schedule.UpdateDate = ifcopenshell.util.date.datetime2ifc(datetime.now(), "IfcDateTime")
+    if file.schema == "IFC2X3":
+        cost_schedule.UpdateDate = createIfcDateAndTime(file, datetime.now())
+    else:
+        cost_schedule.UpdateDate = ifcopenshell.util.date.datetime2ifc(datetime.now(), "IfcDateTime")
     return cost_schedule
+
+
+def createIfcDateAndTime(file: ifcopenshell.file, dt: datetime):
+    ifc_dt = file.create_entity("IfcDateAndTime")
+    ifc_dt.DateComponent = file.create_entity(
+        "IfcCalendarDate", **ifcopenshell.util.date.datetime2ifc(dt, "IfcCalendarDate")
+    )
+    ifc_dt.TimeComponent = file.create_entity("IfcLocalTime", **ifcopenshell.util.date.datetime2ifc(dt, "IfcLocalTime"))
+    return ifc_dt

src/ifcopenshell-python/ifcopenshell/api/cost/add_cost_value.py

@@ -15,9 +15,10 @@
 #
 # 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 ifcopenshell
 
 
-def add_cost_value(file, parent=None) -> None:
+def add_cost_value(file: ifcopenshell.file, parent: ifcopenshell.entity_instance) -> ifcopenshell.entity_instance:
     """Adds a new value or subvalue to a cost item
 
     A cost item's subtotal can be specified in two ways.

src/ifcopenshell-python/ifcopenshell/api/cost/assign_cost_item_quantity.py

@@ -17,9 +17,15 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell.api
+from typing import Optional
 
 
-def assign_cost_item_quantity(file, cost_item=None, products=None, prop_name="") -> None:
+def assign_cost_item_quantity(
+    file: ifcopenshell.file,
+    cost_item: ifcopenshell.entity_instance,
+    products: list[ifcopenshell.entity_instance],
+    prop_name: Optional[str] = "",
+) -> None:
     """Adds a cost item quantity that is parametrically connected to a product
 
     A cost item may have its subtotal calculated by multiplying a unit value

src/ifcopenshell-python/ifcopenshell/api/cost/assign_cost_value.py

@@ -19,7 +19,9 @@
 import ifcopenshell.api
 
 
-def assign_cost_value(file, cost_item=None, cost_rate=None) -> None:
+def assign_cost_value(
+    file: ifcopenshell.file, cost_item: ifcopenshell.entity_instance, cost_rate: ifcopenshell.entity_instance
+) -> None:
     """Assigns a cost value to a cost item from a schedule of rates
 
     Instead of assigning cost values from scratch for each cost item in a

src/ifcopenshell-python/ifcopenshell/api/cost/calculate_cost_item_resource_value.py

@@ -21,7 +21,7 @@ import ifcopenshell.util.date
 import ifcopenshell.util.resource
 
 
-def calculate_cost_item_resource_value(file, cost_item=None) -> None:
+def calculate_cost_item_resource_value(file: ifcopenshell.file, cost_item: ifcopenshell.entity_instance) -> None:
     """Calculates the total cost of all resources associated with a cost item
 
     A cost item may have construction resources (e.g. equipment, material,

src/ifcopenshell-python/ifcopenshell/api/cost/copy_cost_item.py

@@ -19,9 +19,14 @@
 import ifcopenshell
 import ifcopenshell.api
 import ifcopenshell.util.element
+from typing import Union
 
 
-def copy_cost_item(file, cost_item=None) -> None:
+def copy_cost_item(
+    file: ifcopenshell.file, cost_item: ifcopenshell.entity_instance
+) -> Union[ifcopenshell.entity_instance, list[ifcopenshell.entity_instance]]:
+    # TODO: currently it never returns list of duplicated cost items
+    # though it is stated in the docs
     """Copies all cost items and related relationships
 
     The following relationships are also duplicated:
@@ -33,7 +38,7 @@ def copy_cost_item(file, cost_item=None) -> None:
     :param cost_item: The cost item to be duplicated
     :type cost_item: ifcopenshell.entity_instance
     :return: The duplicated cost item or the list of duplicated cost items if the latter has children
-    :rtype: ifcopenshell.entity_instance or list of ifcopenshell.entity_instance
+    :rtype: ifcopenshell.entity_instance or list[ifcopenshell.entity_instance]
 
     Example:
     .. code:: python
@@ -55,7 +60,7 @@ def copy_cost_item(file, cost_item=None) -> None:
 class Usecase:
     def execute(self):
         self.new_cost_items = []
-        self.duplicate_cost_item(self.settings["cost_item"])
+        return self.duplicate_cost_item(self.settings["cost_item"])
 
     def duplicate_cost_item(self, cost_item):
         new_cost_item = ifcopenshell.util.element.copy_deep(self.file, cost_item)

src/ifcopenshell-python/ifcopenshell/api/cost/copy_cost_item_values.py

@@ -20,7 +20,9 @@ import ifcopenshell.util.element
 import ifcopenshell.api
 
 
-def copy_cost_item_values(file, source=None, destination=None) -> None:
+def copy_cost_item_values(
+    file: ifcopenshell.file, source: ifcopenshell.entity_instance, destination: ifcopenshell.entity_instance
+) -> None:
     """Copies all cost values from one cost item to another
 
     Any previously existing values will be removed. The entire value is

src/ifcopenshell-python/ifcopenshell/api/cost/edit_cost_item.py

@@ -15,9 +15,13 @@
 #
 # 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 ifcopenshell
+from typing import Any
 
 
-def edit_cost_item(file, cost_item=None, attributes=None) -> None:
+def edit_cost_item(
+    file: ifcopenshell.file, cost_item: ifcopenshell.entity_instance, attributes: dict[str, Any]
+) -> None:
     """Edits the attributes of an IfcCostItem
 
     For more information about the attributes and data types of an
@@ -26,7 +30,7 @@ def edit_cost_item(file, cost_item=None, attributes=None) -> None:
     :param cost_item: The IfcCostItem entity you want to edit
     :type cost_item: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

src/ifcopenshell-python/ifcopenshell/api/cost/edit_cost_item_quantity.py

@@ -15,9 +15,13 @@
 #
 # 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 ifcopenshell
+from typing import Any
 
 
-def edit_cost_item_quantity(file, physical_quantity=None, attributes=None) -> None:
+def edit_cost_item_quantity(
+    file: ifcopenshell.file, physical_quantity: ifcopenshell.entity_instance, attributes: dict[str, Any]
+) -> None:
     """Edits the attributes of an IfcPhysicalQuantity
 
     For more information about the attributes and data types of an
@@ -26,7 +30,7 @@ def edit_cost_item_quantity(file, physical_quantity=None, attributes=None) -> No
     :param physical_quantity: The IfcPhysicalQuantity entity you want to edit
     :type physical_quantity: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

src/ifcopenshell-python/ifcopenshell/api/cost/edit_cost_schedule.py

@@ -15,9 +15,13 @@
 #
 # 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 ifcopenshell
+from typing import Any
 
 
-def edit_cost_schedule(file, cost_schedule=None, attributes=None) -> None:
+def edit_cost_schedule(
+    file: ifcopenshell.file, cost_schedule: ifcopenshell.entity_instance, attributes: dict[str, Any]
+) -> None:
     """Edits the attributes of an IfcCostSchedule
 
     For more information about the attributes and data types of an
@@ -26,7 +30,7 @@ def edit_cost_schedule(file, cost_schedule=None, attributes=None) -> None:
     :param cost_schedule: The IfcCostSchedule entity you want to edit
     :type cost_schedule: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

src/ifcopenshell-python/ifcopenshell/api/cost/edit_cost_value.py

@@ -19,9 +19,12 @@
 import ifcopenshell
 import ifcopenshell.util.unit
 import ifcopenshell.util.element
+from typing import Any
 
 
-def edit_cost_value(file, cost_value=None, attributes=None) -> None:
+def edit_cost_value(
+    file: ifcopenshell.file, cost_value: ifcopenshell.entity_instance, attributes: dict[str, Any]
+) -> None:
     """Edits the attributes of an IfcCostValue
 
     For more information about the attributes and data types of an
@@ -30,7 +33,7 @@ def edit_cost_value(file, cost_value=None, attributes=None) -> None:
     :param cost_value: The IfcCostValue entity you want to edit
     :type cost_value: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

src/ifcopenshell-python/ifcopenshell/api/cost/edit_cost_value_formula.py

@@ -22,7 +22,7 @@ import ifcopenshell.util.unit
 import ifcopenshell.util.element
 
 
-def edit_cost_value_formula(file, cost_value=None, formula=None) -> None:
+def edit_cost_value_formula(file: ifcopenshell.file, cost_value: ifcopenshell.entity_instance, formula: str) -> None:
     """Sets a cost value based on a formula, similar to formulas in spreadsheets
 
     Costs may be made up of many components (e.g. labour, material, waste

src/ifcopenshell-python/ifcopenshell/api/cost/remove_cost_item.py

@@ -21,7 +21,7 @@ import ifcopenshell.api
 import ifcopenshell.util.element
 
 
-def remove_cost_item(file, cost_item=None) -> None:
+def remove_cost_item(file: ifcopenshell.file, cost_item: ifcopenshell.entity_instance) -> None:
     """Removes a cost item
 
     All associated relationships with the cost item are also removed,

src/ifcopenshell-python/ifcopenshell/api/cost/remove_cost_item_quantity.py

@@ -15,9 +15,12 @@
 #
 # 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 ifcopenshell
 
 
-def remove_cost_item_quantity(file, cost_item=None, physical_quantity=None) -> None:
+def remove_cost_item_quantity(
+    file: ifcopenshell.file, cost_item: ifcopenshell.entity_instance, physical_quantity: ifcopenshell.entity_instance
+) -> None:
     """Removes a quantity assigned to a cost item
 
     If the quantity is part of a product (e.g. wall), then the quantity will

src/ifcopenshell-python/ifcopenshell/api/cost/remove_cost_schedule.py

@@ -21,7 +21,7 @@ import ifcopenshell.api
 import ifcopenshell.util.element
 
 
-def remove_cost_schedule(file, cost_schedule=None) -> None:
+def remove_cost_schedule(file: ifcopenshell.file, cost_schedule: ifcopenshell.entity_instance) -> None:
     """Removes a cost schedule
 
     All associated relationships with the cost schedule are also removed,

src/ifcopenshell-python/ifcopenshell/api/cost/remove_cost_value.py

@@ -15,9 +15,12 @@
 #
 # 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 ifcopenshell
 
 
-def remove_cost_value(file, parent=None, cost_value=None) -> None:
+def remove_cost_value(
+    file: ifcopenshell.file, parent: ifcopenshell.entity_instance, cost_value: ifcopenshell.entity_instance
+) -> None:
     """Removes a cost value
 
     The cost value may be assigned either to a cost item, a construction

src/ifcopenshell-python/ifcopenshell/api/cost/unassign_cost_item_quantity.py

@@ -19,7 +19,9 @@
 import ifcopenshell.api
 
 
-def unassign_cost_item_quantity(file, cost_item=None, products=None) -> None:
+def unassign_cost_item_quantity(
+    file: ifcopenshell.file, cost_item: ifcopenshell.entity_instance, products: list[ifcopenshell.entity_instance]
+) -> None:
     """Removes quantities of a cost item that are calculated on products
 
     A cost item may have quantities that are parametrically calculated on

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

@@ -16,6 +16,15 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Reference external project documents and associate them to model elements
+
+Some project information (drawings, specifications, certificates, reports, etc)
+may be stored in external documents (locally or in a CDE). IFC lets you store a
+register of documents with metadata and associate them with elements (both
+physical and non-physical).
+"""
+
+from .. import wrap_usecases
 from .add_information import add_information
 from .add_reference import add_reference
 from .assign_document import assign_document
@@ -24,3 +33,5 @@ from .edit_reference import edit_reference
 from .remove_information import remove_information
 from .remove_reference import remove_reference
 from .unassign_document import unassign_document
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/document/add_information.py

@@ -17,9 +17,13 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell
+import ifcopenshell.guid
+from typing import Optional
 
 
-def add_information(file, parent=None) -> None:
+def add_information(
+    file: ifcopenshell.file, parent: Optional[ifcopenshell.entity_instance] = None
+) -> ifcopenshell.entity_instance:
     """Adds a new document information to the project
 
     An IFC document information is a document associated with the project.
@@ -52,11 +56,8 @@ def add_information(file, parent=None) -> None:
             attributes={"Identification": "A-GA-6100", "Name": "Overall Plan",
             "Location": "A-GA-6100 - Overall Plan.pdf"})
     """
-    settings = {"parent": parent}
-
     id_attribute = "DocumentId" if file.schema == "IFC2X3" else "Identification"
     information = file.create_entity("IfcDocumentInformation", **{id_attribute: "X", "Name": "Unnamed"})
-    parent = settings["parent"]
     if not parent and file.by_type("IfcProject"):
         parent = file.by_type("IfcProject")[0]
     if parent.is_a("IfcProject") or parent.is_a("IfcContext"):

src/ifcopenshell-python/ifcopenshell/api/document/assign_document.py

@@ -18,6 +18,7 @@
 
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.guid
 import ifcopenshell.util.element
 from typing import Union
 

src/ifcopenshell-python/ifcopenshell/api/document/remove_information.py

@@ -22,7 +22,7 @@ import ifcopenshell.api
 import ifcopenshell.util.element
 
 
-def remove_information(file, information=None) -> None:
+def remove_information(file: ifcopenshell.file, information: ifcopenshell.entity_instance) -> None:
     """Removes a document information
 
     All references and associations are also removed.
@@ -41,23 +41,32 @@ def remove_information(file, information=None) -> None:
         # ... and remove it!
         ifcopenshell.api.run("document.remove_information", model, information=document)
     """
-    settings = {"information": information}
 
-    for reference in settings["information"].HasDocumentReferences or []:
+    if file.schema == "IFC2X3":
+        references = information.DocumentReferences or []
+    else:
+        references = information.HasDocumentReferences
+
+    for reference in references:
         ifcopenshell.api.run("document.remove_reference", file, reference=reference)
 
-    for rel in settings["information"].IsPointer or []:
-        for information in rel.RelatedDocuments:
-            ifcopenshell.api.run("document.remove_information", file, information=information)
+    for rel in information.IsPointer or []:
+        for info in rel.RelatedDocuments:
+            ifcopenshell.api.run("document.remove_information", file, information=info)
 
-    for rel in settings["information"].IsPointedTo or []:
-        if rel.RelatedDocuments == (settings["information"],):
+    for rel in information.IsPointedTo or []:
+        if rel.RelatedDocuments == (information,):
             # This relationship is non-rooted
             file.remove(rel)
 
-    for rel in settings["information"].DocumentInfoForObjects or []:
+    if file.schema == "IFC2X3":
+        rels = [r for r in file.by_type("IfcRelAssociatesDocument") if r.RelatingDocument == information]
+    else:
+        rels = information.DocumentInfoForObjects
+
+    for rel in rels:
         history = rel.OwnerHistory
         file.remove(rel)
         if history:
             ifcopenshell.util.element.remove_deep2(file, history)
-    file.remove(settings["information"])
+    file.remove(information)

src/ifcopenshell-python/ifcopenshell/api/document/remove_reference.py

@@ -38,11 +38,15 @@ def remove_reference(file: ifcopenshell.file, reference: ifcopenshell.entity_ins
         reference = ifcopenshell.api.run("document.add_reference", model, information=document)
         ifcopenshell.api.run("document.remove_reference", model, reference=reference)
     """
-    settings = {"reference": reference}
 
-    for rel in settings["reference"].DocumentRefForObjects or []:
+    if file.schema == "IFC2X3":
+        rels = [r for r in file.get_inverse(reference) if r.is_a("IfcRelAssociatesDocument")]
+    else:
+        rels = reference.DocumentRefForObjects
+
+    for rel in rels:
         history = rel.OwnerHistory
         file.remove(rel)
         if history:
             ifcopenshell.util.element.remove_deep2(file, history)
-    file.remove(settings["reference"])
+    file.remove(reference)

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

@@ -16,6 +16,15 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Create relationships necessary for smart annotations for drawings
+
+Drawings may be generated from modeled elements and annotations. These
+annotations may have relationships which indicate smart data being populated.
+"""
+
+from .. import wrap_usecases
 from .assign_product import assign_product
 from .edit_text_literal import edit_text_literal
 from .unassign_product import unassign_product
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/drawing/assign_product.py

@@ -18,9 +18,14 @@
 
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.guid
 
 
-def assign_product(file, relating_product=None, related_object=None) -> None:
+def assign_product(
+    file: ifcopenshell.file,
+    relating_product: ifcopenshell.entity_instance,
+    related_object: ifcopenshell.entity_instance,
+) -> ifcopenshell.entity_instance:
     """Associates a product and an object, typically for annotation
 
     Warning: this is an experimental API.
@@ -103,7 +108,7 @@ def assign_product(file, relating_product=None, related_object=None) -> None:
                 "OwnerHistory": ifcopenshell.api.run("owner.create_owner_history", file),
                 "RelatedObjects": [settings["related_object"]],
                 "RelatingProduct": settings["relating_product"],
-            }
+            },
         )
 
     if is_grid_axis:

src/ifcopenshell-python/ifcopenshell/api/drawing/edit_text_literal.py

@@ -15,9 +15,13 @@
 #
 # 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 ifcopenshell
+from typing import Any
 
 
-def edit_text_literal(file, text_literal=None, attributes=None) -> None:
+def edit_text_literal(
+    file: ifcopenshell.file, text_literal: ifcopenshell.entity_instance, attributes: dict[str, Any]
+) -> None:
     """Edits the attributes of an IfcTextLiteral
 
     For more information about the attributes and data types of an
@@ -26,7 +30,7 @@ def edit_text_literal(file, text_literal=None, attributes=None) -> None:
     :param reference: The IfcTextLiteral entity you want to edit
     :type reference: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

src/ifcopenshell-python/ifcopenshell/api/drawing/unassign_product.py

@@ -21,7 +21,11 @@ import ifcopenshell.api
 import ifcopenshell.util.element
 
 
-def unassign_product(file, relating_product=None, related_object=None) -> None:
+def unassign_product(
+    file: ifcopenshell.file,
+    relating_product: ifcopenshell.entity_instance,
+    related_object: ifcopenshell.entity_instance,
+) -> None:
     """Unassigns a product and an object (typically an annotation)
 
     Smart annotation objects can be associated with products so that they
@@ -34,8 +38,8 @@ def unassign_product(file, relating_product=None, related_object=None) -> None:
     :param related_object: The object (typically IfcAnnotation) that the
         product is related to
     :type related_object: ifcopenshell.entity_instance
-    :return: The created IfcRelAssignsToProduct relationship
-    :rtype: ifcopenshell.entity_instance
+    :return: None
+    :rtype: None
 
     Example:
 
@@ -68,4 +72,3 @@ def unassign_product(file, relating_product=None, related_object=None) -> None:
         related_objects.remove(settings["related_object"])
         rel.RelatedObjects = related_objects
         ifcopenshell.api.run("owner.update_owner_history", file, **{"element": rel})
-        return rel