Merge branch 'main' into bugfix/update-installation-chatgpt

9and3 · web-flow · commit 7bc71d4cf84a · 2026-04-29T17:39:06.000+02:00
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "cwapi3d"
-version = "32.443.7"
+version = "32.443.8"
 authors = [{ name = "Cadwork", email = "it@cadwork.ca" }]
 requires-python = ">= 3.12"
 description = 'Python bindings for CwAPI3D'
diff --git a/src/attribute_controller/__init__.pyi b/src/attribute_controller/__init__.pyi
@@ -1,3 +1,13 @@
+"""Non-geometric properties and classification of elements.
+
+Covers everything that describes an element without changing its shape:
+identification and labelling (name, group, comment, production data),
+user-defined attributes and their lists, element-type classification
+(beam, panel, auxiliary, wall, roof, floor, drilling, export-solid, ...),
+and the configuration of how these attributes are displayed in the
+different views of the application.
+"""
+
 from cadwork.api_types import *
 from cadwork.attribute_display_settings import attribute_display_settings
 from cadwork.element_grouping_type import element_grouping_type
diff --git a/src/bim_controller/__init__.pyi b/src/bim_controller/__init__.pyi
@@ -1,3 +1,13 @@
+"""Building Information Modeling (BIM) workflows.
+
+Covers the IFC ecosystem and the building-structural metadata that
+goes with it: IFC import/export in its supported schema versions,
+configuration of IFC export options (properties, project data,
+aggregation, element combination), and assignment of building and
+storey information to elements. The module to use whenever the model
+needs to interoperate with IFC-based BIM tooling.
+"""
+
 from cadwork.ifc_2x3_element_type import ifc_2x3_element_type
 from cadwork.ifc_options import ifc_options
 from cadwork.ifc_predefined_type import ifc_predefined_type
diff --git a/src/cadwork/__init__.pyi b/src/cadwork/__init__.pyi
@@ -1,14 +1,12 @@
-"""cadwork Python API type definitions.
+"""Core data model of the cadwork API.
 
-This module re-exports all cadwork data types, enumerations, and utility classes.
-
-Usage::
-
-    from cadwork import point_3d, element_type
-
-    # or
-    import cadwork
-    p = cadwork.point_3d(0.0, 0.0, 0.0)
+Defines the foundational types, enums, and value objects shared across
+all controller modules: geometric primitives, identifier types (elements,
+materials, end-types, multi-layer sets, etc.), classification enums
+(element types, IFC types, machine and BTL versions, multi-layer kinds,
+display options), and the configurable option/property objects passed
+into controllers. This module describes *what things are* in cadwork;
+the controller modules describe *what you can do with them*.
 """
 
 # --- Type aliases ---
diff --git a/src/connector_axis_controller/__init__.pyi b/src/connector_axis_controller/__init__.pyi
@@ -1,3 +1,12 @@
+"""Fastener and connector axes.
+
+Domain of the linear assemblies that represent bolts, screws, dowels
+and similar connectors: their creation, validation, the catalog items
+attached to them (bolt, nut, washer, ...), per-item user fields, and
+the configuration UI for connector axes. Distinct from connector
+*nodes* and from drillings, which live in element_controller.
+"""
+
 from cadwork.point_3d import point_3d
 from cadwork.api_types import *
 from cadwork.vba_catalog_item_type import vba_catalog_item_type
diff --git a/src/dimension_controller/__init__.pyi b/src/dimension_controller/__init__.pyi
@@ -1,3 +1,12 @@
+"""3D dimension annotations on the model.
+
+Domain of dimension elements as first-class objects in the model:
+their creation on a defined plane, the points they measure, their
+formatting and orientation, and visualisation options such as
+overall dimensions. Distinct from shop-drawing dimensions, which
+are produced as part of 2D output.
+"""
+
 from cadwork.point_3d import point_3d
 from cadwork.dimension_base_format import dimension_base_format
 from cadwork.api_types import *
diff --git a/src/element_controller/__init__.pyi b/src/element_controller/__init__.pyi
@@ -1,3 +1,14 @@
+"""Lifecycle and structural manipulation of model elements.
+
+Domain of element existence: creation of every kind of element from
+parameters or geometry, duplication and mirroring, deletion, type
+conversion between element kinds, selection and identification, GUID
+management, grouping into details/containers, and high-level structural
+edits (processes, end-profile cuts, joinery operations). This is the
+entry point for any operation that adds, removes, or fundamentally
+transforms what exists in the model.
+"""
+
 from cadwork.edge_list import edge_list
 from cadwork.element_module_properties import element_module_properties
 from cadwork.facet_list import facet_list
diff --git a/src/endtype_controller/__init__.pyi b/src/endtype_controller/__init__.pyi
@@ -1,3 +1,12 @@
+"""End-type joinery: profiled cuts at element faces.
+
+Domain of named joinery profiles (tenons, mortises, dovetails,
+custom shapes, ...) applied to the start, end or arbitrary faces
+of an element. Covers the catalog (creation, lookup by name and
+id), assignment to specific element faces, retrieval of currently
+applied end-types, and the interactive selection dialog.
+"""
+
 from cadwork.api_types import *
 
 def get_endtype_id(name: str) -> EndtypeId:
diff --git a/src/file_controller/__init__.pyi b/src/file_controller/__init__.pyi
@@ -1,3 +1,12 @@
+"""Interchange with external 3D and CAD file formats.
+
+Handles import and export of geometry between cadwork and third-party
+formats (3DC, STEP, SAT, Rhino, BTL, BXF, DXF, DSTV, FBX, OBJ, STL,
+GLB, WebGL, variants, ...). Concerned only with neutral-format data
+exchange — BIM-specific (IFC) workflows live in bim_controller, and
+shop-drawing 2D exports live in shop_drawing_controller.
+"""
+
 from cadwork.import_3dc_options import import_3dc_options
 from cadwork.point_3d import point_3d
 from cadwork.bim_team_upload_result import bim_team_upload_result
diff --git a/src/geometry_controller/__init__.pyi b/src/geometry_controller/__init__.pyi
@@ -1,3 +1,13 @@
+"""Spatial and metric properties of elements.
+
+Concerned with the pure geometry of an element: its dimensions,
+volumes, areas, weights, local coordinate system (axes and reference
+points), facets and edges, and rigid transformations applied to the
+element's own frame (axis flips and rotations). Use this module to
+*measure* or *reorient* an element's geometry; use element_controller
+to create or destroy it.
+"""
+
 from cadwork.api_types import ElementId, UnsignedInt
 from cadwork.facet_list import facet_list
 from cadwork.point_3d import point_3d
diff --git a/src/list_controller/__init__.pyi b/src/list_controller/__init__.pyi
@@ -1,3 +1,12 @@
+"""Tabular list exports for production and quantity takeoff.
+
+Generates the structured lists used in fabrication and project
+management: production lists, part lists, and cover (wall / roof /
+floor) lists, with optional external settings files to control
+formatting and content. Concerned with *aggregated tabular data*
+about the model, not with geometric or drawing exports.
+"""
+
 from cadwork.api_types import ElementId, UnsignedInt
 
 def export_production_list(element_id_list: list[ElementId], file_path: str) -> None:
diff --git a/src/machine_controller/__init__.pyi b/src/machine_controller/__init__.pyi
@@ -1,3 +1,12 @@
+"""CNC and woodworking-machine output.
+
+Covers the calculation and export of machine data for fabrication:
+BTL / BTLx in their supported versions, the Hundegger family and
+its variants (with optional preset files and silent operation),
+and the inspection of per-element machine processings. The bridge
+between the cadwork model and the shop floor.
+"""
+
 from cadwork import vertex_list
 from cadwork.api_types import ElementId
 from cadwork.btl_version import btl_version
diff --git a/src/material_controller/__init__.pyi b/src/material_controller/__init__.pyi
@@ -1,3 +1,13 @@
+"""Materials and the color-to-material mapping system.
+
+Covers the catalog of materials available in the project — creation,
+naming, grouping, and physical/structural properties — and the
+mapping table that ties cadwork's color numbers to materials per
+element category (beams, panels, drillings, surfaces, nodes,
+standard and MEP axes, auxiliaries). Element-level material
+*assignment* by name lives in attribute_controller.
+"""
+
 from cadwork.api_types import MaterialId, UnsignedInt
 
 def create_material(name: str) -> MaterialId:
diff --git a/src/menu_controller/__init__.pyi b/src/menu_controller/__init__.pyi
@@ -1,3 +1,13 @@
+"""Custom in-application menus driven by scripts.
+
+Provides the means to surface script-driven choices to the user
+through cadwork's native menu UI and to capture the user's
+selection. The complement to utility_controller's prompts and
+dialogs when a list-of-options interaction fits better than a
+modal form.
+"""
+
+
 def display_simple_menu(menu_items: list[str]) -> str:
     """Displays a simple menu.
 
diff --git a/src/multi_layer_cover_controller/__init__.pyi b/src/multi_layer_cover_controller/__init__.pyi
@@ -1,3 +1,13 @@
+"""Multi-layer build-ups for walls, roofs and floors.
+
+Covers the definition and management of layered cover assemblies
+(walls — solid, framed, log; floors — solid, framed; roofs and
+generic cover types): creating sets, naming them, and composing
+them from ordered layers with type, material and thickness. The
+template/library side of multi-layer construction; instantiation
+of these covers as elements is done elsewhere in the API.
+"""
+
 from cadwork import multi_layer_cover_type
 from cadwork.api_types import *
 from cadwork.multi_layer_type import multi_layer_type
diff --git a/src/roof_controller/__init__.pyi b/src/roof_controller/__init__.pyi
@@ -1,3 +1,13 @@
+"""Roof-surface specific queries and operations.
+
+Concerned with information that only makes sense for roof
+surfaces: roof-specific edge classifications (ridge, eave, hip,
+valley, ...), profile and edge measurements, and other
+analyses that depend on a surface having been designated as a
+roof. Conversion of generic surfaces into roof surfaces lives in
+element_controller.
+"""
+
 from cadwork.api_types import ElementId
 
 def get_profile_length(element_id: ElementId) -> float:
diff --git a/src/scene_controller/__init__.pyi b/src/scene_controller/__init__.pyi
@@ -1,3 +1,12 @@
+"""Scenes: named, organisable views of element subsets.
+
+Manages the collection of saved scenes in the project — their
+creation and removal, their membership of elements, their grouping
+into folders/tabs, and their activation. Scenes are persistent
+named selections; transient visibility belongs to
+visualization_controller.
+"""
+
 from cadwork.api_types import *
 
 def add_scene(name: str) -> bool:
diff --git a/src/shop_drawing_controller/__init__.pyi b/src/shop_drawing_controller/__init__.pyi
@@ -1,3 +1,12 @@
+"""2D shop and workshop drawing generation.
+
+Covers the production of 2D drawings from the 3D model: wireframe
+and hidden-line views, layout-based and clipboard-based outputs,
+section and detail generation (wall sections and similar), and
+export-solid handling for shop-drawing workflows. The 2D-output
+counterpart to file_controller's neutral 3D exports.
+"""
+
 from cadwork.point_3d import point_3d
 from cadwork.api_types import *
 
diff --git a/src/utility_controller/__init__.pyi b/src/utility_controller/__init__.pyi
@@ -1,3 +1,13 @@
+"""Application environment and user interaction.
+
+The bridge between scripts and the surrounding cadwork application:
+filesystem and version information, language and locale, user-facing
+dialogs and prompts, status messages and progress indicators, GUID
+generation, project metadata, and access to the host window itself.
+General-purpose helpers that don't belong to any specific modelling
+domain.
+"""
+
 from cadwork.api_types import ElementId
 from cadwork.point_3d import point_3d
 from cadwork.window_geometry import window_geometry
diff --git a/src/visualization_controller/__init__.pyi b/src/visualization_controller/__init__.pyi
@@ -1,3 +1,12 @@
+"""On-screen presentation and viewing state.
+
+Controls how the model is displayed without altering the underlying
+data: visibility and activation of elements, view modes and camera
+orientation, color overrides, and the saving/restoring of viewing
+states. Strictly visual — nothing in this module changes element
+properties or geometry persistently.
+"""
+
 from cadwork.camera_data import camera_data
 from cadwork.point_3d import point_3d
 from cadwork.api_types import *
