Add API docs for constraint module

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

@@ -20,13 +20,29 @@ import ifcopenshell
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, objective=None):
+        """Add a new metric benchmark
+
+        Qualitative constraints may have a series of quantitative benchmarks
+        linked to it known as metrics. Metrics may be parametrically linked to
+        computed model properties or quantities. Metrics need to be satisfied
+        to meet the objective of the constraint.
+
+        :param objective: The IfcObjective that this metric is a benchmark of.
+        :type objective: ifcopenshell.entity_instance.entity_instance
+        :return: The newly created IfcMetric entity
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            objective = ifcopenshell.api.run("constraint.add_objective", model)
+            metric = ifcopenshell.api.run("constraint.add_metric", model,
+                objective=objective)
+        """
         self.file = file
         self.settings = {
-            "objective": None,
+            "objective": objective,
         }
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         metric = self.file.create_entity(

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

@@ -20,11 +20,29 @@ import ifcopenshell
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file):
+        """Add a new objective constraint
+
+        Parametric constraints may be defined by the user. The constraint is defined
+        by first creating an objective describing the purpose of the constraint and
+        whether it is a hard or soft constraint. Later on, metrics may be added to
+        check whether the constraint has been met by connecting it to properties and
+        quantities. See ifcopenshell.api.constraint.add_metric for more information.
+
+        :return: The newly created IfcObjective entity
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            # Create a new objective for code compliance requirements
+            objective = ifcopenshell.api.run("constraint.add_objective", model)
+            objective.ConstraintGrade = "ADVISORY"
+            objective.ObjectiveQualifier = "CODECOMPLIANCE"
+            # Note: the objective right now is purely qualitative and for
+            # information purposes. You may wish to add quantiative metrics.
+        """
         self.file = file
         self.settings = {}
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         return self.file.create_entity(

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

@@ -20,14 +20,30 @@ import ifcopenshell
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, product=None, constraint=None):
+        """Assigns a constraint to a product
+
+        This assigns a relationship between a product and a constraint, so that
+        when a product's properties and quantities do not match the requirements
+        of the constraint's metrics, results can be flagged.
+
+        It is assumed (but not explicit in the IFC documentation) that
+        constraints are inherited from the type. This way, it is not necessary
+        to create lots of constraint assignments.
+
+        :param product: The product the constraint applies to. This is anything
+            which can have properties or quantities.
+        :type product: ifcopenshell.entity_instance.entity_instance
+        :param constraint: The IfcObjective constraint
+        :type constraint: ifcopenshell.entity_instance.entity_instance
+        :return: The new or updated IfcRelAssociatesConstraint relationship
+        :rtype: ifcopenshell.entity_instance.entity_instance
+        """
         self.file = file
         self.settings = {
-            "product": None,
+            "product": product,
-            "constraint": None,
+            "constraint": constraint,
         }
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         rel = self.get_constraint_rel()

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

@@ -18,11 +18,29 @@
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, metric=None, attributes=None):
+        """Edit the attributes of a metric
+
+        For more information about the attributes and data types of an
+        IfcMetric, consult the IFC documentation.
+
+        :param metric: The IfcMetric you want to edit.
+        :type metric: ifcopenshell.entity_instance.entity_instance
+        :param attributes: a dictionary of attribute names and values.
+        :type attributes: dict, optional
+        :return: None
+        :rtype: None
+
+        Example::
+
+            objective = ifcopenshell.api.run("constraint.add_objective", model)
+            metric = ifcopenshell.api.run("constraint.add_metric", model,
+                objective=objective)
+            ifcopenshell.api.run("constraint.edit_metric", model,
+                metric=metric, attributes={"ConstraintGrade": "HARD"})
+        """
         self.file = file
-        self.settings = {"metric": None, "attributes": {}}
+        self.settings = {"metric": metric, "attributes": attributes or {}}
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         for name, value in self.settings["attributes"].items():

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

@@ -18,11 +18,27 @@
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, objective=None, attributes=None):
+        """Edit the attributes of a objective
+
+        For more information about the attributes and data types of an
+        IfcObjective, consult the IFC documentation.
+
+        :param objective: The IfcObjective you want to edit.
+        :type objective: ifcopenshell.entity_instance.entity_instance
+        :param attributes: a dictionary of attribute names and values.
+        :type attributes: dict, optional
+        :return: None
+        :rtype: None
+
+        Example::
+
+            objective = ifcopenshell.api.run("constraint.add_objective", model)
+            ifcopenshell.api.run("constraint.edit_objective", model,
+                objective=objective, attributes={"ConstraintGrade": "HARD"})
+        """
         self.file = file
-        self.settings = {"objective": None, "attributes": {}}
+        self.settings = {"objective": objective, "attributes": attributes or {}}
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         for name, value in self.settings["attributes"].items():

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

@@ -18,11 +18,27 @@
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, constraint=None):
+        """Remove a constraint (typically an objective)
+
+        Removes a constraint definition and all of its associations to any
+        products. Typically this would be an IfcObjective, although technically
+        you can associate IfcMetrics ith products too, though the meaning may be
+        unclear.
+
+        :param constraint: The IfcObjective you want to remove.
+        :type constraint: ifcopenshell.entity_instance.entity_instance
+        :return: None
+        :rtype: None
+
+        Example::
+
+            objective = ifcopenshell.api.run("constraint.add_objective", model)
+            ifcopenshell.api.run("constraint.remove_constraint", model,
+                constraint=objective)
+        """
         self.file = file
-        self.settings = {"constraint": None}
+        self.settings = {"constraint": constraint}
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         self.file.remove(self.settings["constraint"])

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

@@ -18,11 +18,27 @@
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, metric=None):
+        """Remove a metric benchmark
+
+        Removes a metric benchmark and all of its associations to any products
+        and objectives.
+
+        :param metric: The IfcMetric you want to remove.
+        :type metric: ifcopenshell.entity_instance.entity_instance
+        :return: None
+        :rtype: None
+
+        Example::
+
+            objective = ifcopenshell.api.run("constraint.add_objective", model)
+            metric = ifcopenshell.api.run("constraint.add_metric", model,
+                objective=objective)
+            ifcopenshell.api.run("constraint.remove_metric", model,
+                metric=metric)
+        """
         self.file = file
-        self.settings = {"metric": None}
+        self.settings = {"metric": metric}
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         self.file.remove(self.settings["metric"])

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

@@ -18,14 +18,24 @@
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, product=None, constraint=None):
+        """Unassigns a constraint to a product
+
+        The constraint will not be deleted and is available to be assigned to
+        other products.
+
+        :param product: The product the constraint applies to.
+        :type product: ifcopenshell.entity_instance.entity_instance
+        :param constraint: The IfcObjective constraint
+        :type constraint: ifcopenshell.entity_instance.entity_instance
+        :return: None
+        :rtype: None
+        """
         self.file = file
         self.settings = {
-            "product": None,
+            "product": product,
-            "constraint": None,
+            "constraint": constraint,
         }
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         for rel in self.settings["product"].HasAssociations: