Merge pull request #263 from cwapi3d/feature/add-function-docstring-examples

Feature/add function docstring examples

Author: Brunner246

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cwapi3d"
-version = "32.274.0"
+version = "32.296.0"
 authors = [{ name = "Cadwork", email = "it@cadwork.ca" }]
 requires-python = ">= 3.12"
 description = 'Python bindings for CwAPI3D'

src/bim_controller/__init__.pyi

@@ -20,15 +20,17 @@ def get_ifc_guid(element_id: int) -> str:
     Parameters:
         element_id: element_id
 
-    Returns:
-        str
-    """
+    Examples:
+        >>> import element_controller as ec
+        >>> import bim_controller as bc
 
-def clear_errors() -> None:
-    """clear errors
+        >>> selected_elements = ec.get_all_identifiable_element_ids()
+        >>> element = selected_elements[0]
+        >>> ifc_guid = bc.get_ifc_guid(element)
+        >>> print(f"IFC GUID: {ifc_guid}")
 
     Returns:
-        None
+        str
     """
 
 def get_ifc2x3_element_type(element_id: int) -> ifc_2x3_element_type:
@@ -37,6 +39,15 @@ def get_ifc2x3_element_type(element_id: int) -> ifc_2x3_element_type:
     Parameters:
         element_id: element_id
 
+    Examples:
+        >>> import element_controller as ec
+        >>> import bim_controller as bc
+        >>> import cadwork # needed for ifc_2x3_element_type
+
+        >>> selected_elements = ec.get_all_identifiable_element_ids()
+        >>> element = selected_elements[0]
+        >>> ifc_type = bc.get_ifc2x3_element_type(element)
+
     Returns:
         ifc_2x3_element_type
     """
@@ -50,9 +61,14 @@ def set_ifc2x3_element_type(element_i_ds: List[int], ifc_type: ifc_2x3_element_t
         ifc_type: element_type
 
     Examples:
+        >>> import element_controller as ec
+        >>> import bim_controller as bc
+        >>> import cadwork
+
+        >>> selected_elements = ec.get_all_identifiable_element_ids()
         >>> ifc_entity_type = cadwork.ifc_2x3_element_type()
         >>> ifc_entity_type.set_ifc_member()
-        >>> bimc.set_ifc2x3_element_type([element], ifc_entity_type)
+        >>> bc.set_ifc2x3_element_type(selected_elements, ifc_entity_type)
 
     Returns:
         None
@@ -64,6 +80,14 @@ def import_ifc_as_graphical_object(file_path: str) -> bool:
     Parameters:
         file_path: file_path
 
+    Examples:
+        >>> import bim_controller as bc
+
+        >>> ifc_file_path = r"C:/imports/building_model.ifc"
+        >>> success = bc.import_ifc_as_graphical_object(ifc_file_path)
+        >>> if success:
+        >>>     print("IFC imported as graphical object successfully")
+
     Returns:
         bool
     """
@@ -74,6 +98,14 @@ def import_bcf(file_path: str) -> bool:
     Parameters:
         file_path: file_path
 
+    Examples:
+        >>> import bim_controller as bc
+
+        >>> bcf_file_path = r"C:/imports/issues.bcf"
+        >>> success = bc.import_bcf(bcf_file_path)
+        >>> if success:
+        >>>     print("BCF file imported successfully")
+
     Returns:
         bool
     """
@@ -84,6 +116,14 @@ def export_bcf(file_path: str) -> bool:
     Parameters:
         file_path: file_path
 
+    Examples:
+        >>> import bim_controller as bc
+
+        >>> bcf_output_path = r"C:/exports/project_issues.bcf"
+        >>> success = bc.export_bcf(bcf_output_path)
+        >>> if success:
+        >>>     print("BCF file exported successfully")
+
     Returns:
         bool
     """
@@ -95,6 +135,16 @@ def export_ifc(element_i_ds: List[int], file_path: str) -> bool:
         element_i_ds: element_i_ds
         file_path: file_path
 
+    Examples:
+        >>> import element_controller as ec
+        >>> import bim_controller as bc
+
+        >>> selected_elements = ec.get_all_identifiable_element_ids()
+        >>> ifc_output_path = r"C:/exports/building_model.ifc"
+        >>> success = bc.export_ifc(selected_elements, ifc_output_path)
+        >>> if success:
+        >>>     print("IFC file exported successfully")
+
     Returns:
         bool
     """
@@ -117,6 +167,14 @@ def set_storey_height(building: str, storey: str, height: float) -> None:
         storey: storey
         height: height
 
+    Examples:
+        >>> import bim_controller as bc
+
+        >>> building_name = "Building A"
+        >>> storey_name = "Ground Floor"
+        >>> height_millimeters = 3_500
+        >>> bc.set_storey_height(building_name, storey_name, height_millimeters)
+
     Returns:
         None
     """
@@ -212,6 +270,15 @@ def set_building_and_storey(element_id_list: List[int], building: str, storey: s
         building: building
         storey: storey
 
+    Examples:
+        >>> import element_controller as ec
+        >>> import bim_controller as bc
+
+        >>> selected_elements = ec.get_all_identifiable_element_ids()
+        >>> building_name = "Building A"
+        >>> storey_name = "Ground Floor"
+        >>> bc.set_building_and_storey(selected_elements, building_name, storey_name)
+
     Returns:
         None
     """
@@ -325,7 +392,16 @@ def set_ifc_predefined_type(element_i_ds: List[int], predefined_type: ifc_predef
         element_i_ds: element_i_ds
         predefined_type: predefined_type
 
+    Examples:
+        >>> import element_controller as ec
+        >>> import bim_controller as bc
+        >>> import cadwork
+
+        >>> selected_elements = ec.get_all_identifiable_element_ids()
+        >>> predefined_type = cadwork.ifc_predefined_type()
+        >>> predefined_type.set_member()
+        >>> bc.set_ifc_predefined_type(selected_elements, predefined_type)
+
     Returns:
         None
     """
-

src/cadwork/point_3d.pyi

@@ -8,6 +8,9 @@ class point_3d:
             y (float): The y-coordinate of the point.
             z (float): The z-coordinate of the point.
         """
+        self.x = x
+        self.y = y
+        self.z = z
 
     def __add__(self, other: 'point_3d') -> 'point_3d':
         """
@@ -148,99 +151,3 @@ class point_3d:
 
     def invert(self) -> 'point_3d':
         """Return the inverted point (negated coordinates)."""
-    def __sub__(self, other: 'point_3d') -> 'point_3d':
-        """sub
-
-        Parameters:
-            other: other
-
-        Returns:
-            'point_3d'
-        """
-
-    def __truediv__(self, other: float) -> 'point_3d':
-        """truediv
-
-        Parameters:
-            other: other
-
-        Returns:
-            'point_3d'
-        """
-
-    def __iadd__(self, other: 'point_3d') -> 'point_3d':
-        """iadd
-
-        Parameters:
-            other: other
-
-        Returns:
-            'point_3d'
-        """
-
-    def __isub__(self, other: 'point_3d') -> 'point_3d':
-        """isub
-
-        Parameters:
-            other: other
-
-        Returns:
-            'point_3d'
-        """
-
-    def __imul__(self, other: float) -> 'point_3d':
-        """imul
-
-        Parameters:
-            other: other
-
-        Returns:
-            'point_3d'
-        """
-
-    def __itruediv__(self, other: float) -> 'point_3d':
-        """itruediv
-
-        Parameters:
-            other: other
-
-        Returns:
-            'point_3d'
-        """
-
-    def __neg__(self) -> 'point_3d':
-        """neg
-
-        Returns:
-            'point_3d'
-        """
-
-    def __eq__(self, other: object) -> bool:
-        """eq
-
-        Parameters:
-            other: other
-
-        Returns:
-            bool
-        """
-
-    def __ne__(self, other: object) -> bool:
-        """neg
-
-        Parameters:
-            other: other
-
-        Returns:
-            bool
-        """
-
-    def __add__(self, other: 'point_3d') -> 'point_3d':
-        """add
-
-        Parameters:
-            other: other
-
-        Returns:
-            'point_3d'
-        """