From 136ae52c8e6505d594f1bc4f0d83f344352a6de6 Mon Sep 17 00:00:00 2001
From: Andrej730 <azhilenkov@gmail.com>
Date: Tue, 14 Jul 2026 18:42:42 +0500
Subject: [PATCH] file.get_inverse: document `with_attribute_indices` overload

(cherry picked from commit 1b1da821f1cf2590a4952606da4437cc8e543a36)
---
 src/ifcopenshell-python/ifcopenshell/file.py | 15 +++++++++++--
 src/ifcopenshell-python/test/typing_tests.py | 22 ++++++++++++++++++++
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/src/ifcopenshell-python/ifcopenshell/file.py b/src/ifcopenshell-python/ifcopenshell/file.py
index cd161cf63c..0eb42993fd 100644
--- a/src/ifcopenshell-python/ifcopenshell/file.py
+++ b/src/ifcopenshell-python/ifcopenshell/file.py
@@ -773,9 +773,16 @@ class file_mixin:
         self,
         inst: ifcopenshell.entity_instance,
         allow_duplicate: Literal[True],
-        with_attribute_indices: bool = False,
+        with_attribute_indices: Literal[False] = False,
     ) -> list[ifcopenshell.entity_instance]: ...
     @overload
+    def get_inverse(
+        self,
+        inst: ifcopenshell.entity_instance,
+        allow_duplicate: Literal[True],
+        with_attribute_indices: Literal[True],
+    ) -> list[tuple[ifcopenshell.entity_instance, int]]: ...
+    @overload
     def get_inverse(
         self,
         inst: ifcopenshell.entity_instance,
@@ -787,7 +794,11 @@ class file_mixin:
         inst: ifcopenshell.entity_instance,
         allow_duplicate: bool = False,
         with_attribute_indices: bool = False,
-    ) -> Union[list[ifcopenshell.entity_instance], set[ifcopenshell.entity_instance]]:
+    ) -> (
+        list[ifcopenshell.entity_instance]
+        | set[ifcopenshell.entity_instance]
+        | list[tuple[ifcopenshell.entity_instance, int]]
+    ):
         """Return a list of entities that reference this entity
 
         Warning: this is a slow function, especially when there is a large
diff --git a/src/ifcopenshell-python/test/typing_tests.py b/src/ifcopenshell-python/test/typing_tests.py
index ccf007fa62..48dd93b057 100644
--- a/src/ifcopenshell-python/test/typing_tests.py
+++ b/src/ifcopenshell-python/test/typing_tests.py
@@ -39,3 +39,25 @@ def ifcopenshell_open_test(str_: str, bool_: bool):
     assert_type(ifc_file, ifcopenshell.stream)
 
     ifc_file = ifcopenshell.open(str_, readonly=True)
+
+
+def get_inverse_test(ifc_file: ifcopenshell.file, inst: ifcopenshell.entity_instance, bool_: bool):
+    # Default: allow_duplicate=False, with_attribute_indices=False
+    result = ifc_file.get_inverse(inst)
+    assert_type(result, set[ifcopenshell.entity_instance])
+
+    # Explicit allow_duplicate=False
+    result = ifc_file.get_inverse(inst, allow_duplicate=False)
+    assert_type(result, set[ifcopenshell.entity_instance])
+
+    # allow_duplicate=True without indices
+    result = ifc_file.get_inverse(inst, allow_duplicate=True)
+    assert_type(result, list[ifcopenshell.entity_instance])
+
+    # allow_duplicate=True with indices
+    result = ifc_file.get_inverse(inst, allow_duplicate=True, with_attribute_indices=True)
+    assert_type(result, list[tuple[ifcopenshell.entity_instance, int]])
+
+    # Dynamic bool values (falls back to generic overload)
+    result = ifc_file.get_inverse(inst, allow_duplicate=bool_)
+    assert_type(result, list[ifcopenshell.entity_instance] | set[ifcopenshell.entity_instance])