Generate functions for all API usecases for better static code features. See #2693.

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

@@ -15,3 +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/>.
+
+from .add_metric import add_metric
+from .add_metric_reference import add_metric_reference
+from .add_objective import add_objective
+from .assign_constraint import assign_constraint
+from .edit_metric import edit_metric
+from .edit_objective import edit_objective
+from .remove_constraint import remove_constraint
+from .remove_metric import remove_metric
+from .unassign_constraint import unassign_constraint

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

@@ -19,44 +19,41 @@
 import ifcopenshell
 
 
-class Usecase:
-    def __init__(self, file, objective=None):
-        """Add a new metric benchmark
+def add_metric(file, objective=None) -> 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.
+    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
-        :return: The newly created IfcMetric entity
-        :rtype: ifcopenshell.entity_instance
+    :param objective: The IfcObjective that this metric is a benchmark of.
+    :type objective: ifcopenshell.entity_instance
+    :return: The newly created IfcMetric entity
+    :rtype: ifcopenshell.entity_instance
 
-        Example:
+    Example:
 
-        .. code:: python
+    .. code:: python
 
-            objective = ifcopenshell.api.run("constraint.add_objective", model)
-            metric = ifcopenshell.api.run("constraint.add_metric", model,
-                objective=objective)
-        """
-        self.file = file
-        self.settings = {
-            "objective": objective,
+        objective = ifcopenshell.api.run("constraint.add_objective", model)
+        metric = ifcopenshell.api.run("constraint.add_metric", model,
+            objective=objective)
+    """
+    settings = {
+        "objective": objective,
+    }
+
+    metric = file.create_entity(
+        "IfcMetric",
+        **{
+            "Name": "Unnamed",
+            "ConstraintGrade": "NOTDEFINED",
+            "Benchmark": "EQUALTO",
         }
-
-    def execute(self):
-        metric = self.file.create_entity(
-            "IfcMetric",
-            **{
-                "Name": "Unnamed",
-                "ConstraintGrade": "NOTDEFINED",
-                "Benchmark": "EQUALTO",
-            }
-        )
-        if self.settings["objective"]:
-            benchmark_values = list(self.settings["objective"].BenchmarkValues or [])
-            benchmark_values.append(metric)
-            self.settings["objective"].BenchmarkValues = benchmark_values
-        return metric
+    )
+    if settings["objective"]:
+        benchmark_values = list(settings["objective"].BenchmarkValues or [])
+        benchmark_values.append(metric)
+        settings["objective"].BenchmarkValues = benchmark_values
+    return metric

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

@@ -18,28 +18,26 @@
 
 import ifcopenshell
 
-class Usecase:
-    def __init__(self, file, metric=None, reference_path=None):
-        """
-        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.
-        """
-        self.file = file
-        self.settings = {"metric": metric, "reference_path": reference_path}
 
-    def execute(self):
-        if self.settings["reference_path"]:
-            attributes = self.settings["reference_path"].split(".")
-            references_created = []
-            for i in range(len(attributes)):
-                if i == 0:
-                    reference = self.file.create_entity("IfcReference")
-                    reference.AttributeIdentifier = attributes[i]
-                    self.settings["metric"].ReferencePath = reference
-                    references_created.append(reference)
-                else:
-                    reference = self.file.create_entity("IfcReference")
-                    reference.AttributeIdentifier = attributes[i]
-                    references_created[i-1].InnerReference = reference
-                    references_created.append(reference)
-            return references_created
+def add_metric_reference(file, metric=None, reference_path=None) -> None:
+    """
+    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}
+
+    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")
+                reference.AttributeIdentifier = attributes[i]
+                settings["metric"].ReferencePath = reference
+                references_created.append(reference)
+            else:
+                reference = file.create_entity("IfcReference")
+                reference.AttributeIdentifier = attributes[i]
+                references_created[i - 1].InnerReference = reference
+                references_created.append(reference)
+        return references_created

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

@@ -19,34 +19,31 @@
 import ifcopenshell
 
 
-class Usecase:
-    def __init__(self, file):
-        """Add a new objective constraint
+def add_objective(file) -> None:
+    """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.
+    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
+    :return: The newly created IfcObjective entity
+    :rtype: ifcopenshell.entity_instance
 
-        Example:
+    Example:
 
-        .. code:: python
+    .. code:: python
 
-            # 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 = {}
+        # 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.
+    """
+    settings = {}
 
-    def execute(self):
-        return self.file.create_entity(
-            "IfcObjective", **{"Name": "Unnamed", "ConstraintGrade": "NOTDEFINED", "ObjectiveQualifier": "NOTDEFINED"}
-        )
+    return file.create_entity(
+        "IfcObjective", **{"Name": "Unnamed", "ConstraintGrade": "NOTDEFINED", "ObjectiveQualifier": "NOTDEFINED"}
+    )

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

@@ -21,39 +21,41 @@ import ifcopenshell.api
 from typing import Union
 
 
+def assign_constraint(
+    file: ifcopenshell.file,
+    products: list[ifcopenshell.entity_instance],
+    constraint: ifcopenshell.entity_instance,
+) -> Union[ifcopenshell.entity_instance, None]:
+    """Assigns a constraint to a list of products
+
+    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 products: The list of products the constraint applies to. This is anything
+        which can have properties or quantities.
+    :type products: list[ifcopenshell.entity_instance]
+    :param constraint: The IfcObjective constraint
+    :type constraint: ifcopenshell.entity_instance
+    :return: The new or updated IfcRelAssociatesConstraint relationship
+        or `None` if `products` was an empty list.
+    :rtype: ifcopenshell.entity_instance
+    """
+    usecase = Usecase()
+    usecase.file = file
+    usecase.settings = {
+        "products": products,
+        "constraint": constraint,
+    }
+    return usecase.execute()
+
+
 class Usecase:
-    def __init__(
-        self,
-        file: ifcopenshell.file,
-        products: list[ifcopenshell.entity_instance],
-        constraint: ifcopenshell.entity_instance,
-    ):
-        """Assigns a constraint to a list of products
-
-        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 products: The list of products the constraint applies to. This is anything
-            which can have properties or quantities.
-        :type products: list[ifcopenshell.entity_instance]
-        :param constraint: The IfcObjective constraint
-        :type constraint: ifcopenshell.entity_instance
-        :return: The new or updated IfcRelAssociatesConstraint relationship
-            or `None` if `products` was an empty list.
-        :rtype: ifcopenshell.entity_instance
-        """
-        self.file = file
-        self.settings = {
-            "products": products,
-            "constraint": constraint,
-        }
-
-    def execute(self) -> Union[ifcopenshell.entity_instance, None]:
+    def execute(self):
         products = set(self.settings["products"])
         if not products:
             return

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

@@ -17,33 +17,30 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 
-class Usecase:
-    def __init__(self, file, metric=None, attributes=None):
-        """Edit the attributes of a metric
+def edit_metric(file, metric=None, attributes=None) -> None:
+    """Edit the attributes of a metric
 
-        For more information about the attributes and data types of an
-        IfcMetric, consult the IFC documentation.
+    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
-        :param attributes: a dictionary of attribute names and values.
-        :type attributes: dict, optional
-        :return: None
-        :rtype: 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
+    :return: None
+    :rtype: None
 
-        Example:
+    Example:
 
-        .. code:: python
+    .. code:: python
 
-            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": metric, "attributes": attributes or {}}
+        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"})
+    """
+    settings = {"metric": metric, "attributes": attributes or {}}
 
-    def execute(self):
-        for name, value in self.settings["attributes"].items():
-            setattr(self.settings["metric"], name, value)
+    for name, value in settings["attributes"].items():
+        setattr(settings["metric"], name, value)

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

@@ -17,31 +17,28 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 
-class Usecase:
-    def __init__(self, file, objective=None, attributes=None):
-        """Edit the attributes of a objective
+def edit_objective(file, objective=None, attributes=None) -> None:
+    """Edit the attributes of a objective
 
-        For more information about the attributes and data types of an
-        IfcObjective, consult the IFC documentation.
+    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
-        :param attributes: a dictionary of attribute names and values.
-        :type attributes: dict, optional
-        :return: None
-        :rtype: 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
+    :return: None
+    :rtype: None
 
-        Example:
+    Example:
 
-        .. code:: python
+    .. code:: python
 
-            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": objective, "attributes": attributes or {}}
+        objective = ifcopenshell.api.run("constraint.add_objective", model)
+        ifcopenshell.api.run("constraint.edit_objective", model,
+            objective=objective, attributes={"ConstraintGrade": "HARD"})
+    """
+    settings = {"objective": objective, "attributes": attributes or {}}
 
-    def execute(self):
-        for name, value in self.settings["attributes"].items():
-            setattr(self.settings["objective"], name, value)
+    for name, value in settings["attributes"].items():
+        setattr(settings["objective"], name, value)

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

@@ -20,36 +20,33 @@ import ifcopenshell
 import ifcopenshell.util.element
 
 
-class Usecase:
-    def __init__(self, file, constraint=None):
-        """Remove a constraint (typically an objective)
+def remove_constraint(file, constraint=None) -> 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.
+    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
-        :return: None
-        :rtype: None
+    :param constraint: The IfcObjective you want to remove.
+    :type constraint: ifcopenshell.entity_instance
+    :return: None
+    :rtype: None
 
-        Example:
+    Example:
 
-        .. code:: python
+    .. code:: python
 
-            objective = ifcopenshell.api.run("constraint.add_objective", model)
-            ifcopenshell.api.run("constraint.remove_constraint", model,
-                constraint=objective)
-        """
-        self.file = file
-        self.settings = {"constraint": constraint}
+        objective = ifcopenshell.api.run("constraint.add_objective", model)
+        ifcopenshell.api.run("constraint.remove_constraint", model,
+            constraint=objective)
+    """
+    settings = {"constraint": constraint}
 
-    def execute(self):
-        self.file.remove(self.settings["constraint"])
-        for rel in self.file.by_type("IfcRelAssociatesConstraint"):
-            if not rel.RelatingConstraint:
-                history = rel.OwnerHistory
-                self.file.remove(rel)
-                if history:
-                    ifcopenshell.util.element.remove_deep2(self.file, history)
+    file.remove(settings["constraint"])
+    for rel in file.by_type("IfcRelAssociatesConstraint"):
+        if not rel.RelatingConstraint:
+            history = rel.OwnerHistory
+            file.remove(rel)
+            if history:
+                ifcopenshell.util.element.remove_deep2(file, history)

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

@@ -17,31 +17,34 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 
+def remove_metric(file, metric=None) -> 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
+    :return: None
+    :rtype: None
+
+    Example:
+
+    .. code:: python
+
+        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)
+    """
+    usecase = Usecase()
+    usecase.file = file
+    usecase.settings = {"metric": metric}
+    return usecase.execute()
+
+
 class Usecase:
-    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
-        :return: None
-        :rtype: None
-
-        Example:
-
-        .. code:: python
-
-            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": metric}
-
     def execute(self):
         if self.settings["metric"].ReferencePath:
             reference = self.settings["metric"].ReferencePath

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

@@ -21,31 +21,33 @@ import ifcopenshell.api
 import ifcopenshell.util.element
 
 
+def unassign_constraint(
+    file: ifcopenshell.file,
+    products: list[ifcopenshell.entity_instance],
+    constraint: ifcopenshell.entity_instance,
+) -> None:
+    """Unassigns a constraint from a list of products
+
+    The constraint will not be deleted and is available to be assigned to
+    other products.
+
+    :param products: The list of products the constraint applies to.
+    :type products: list[ifcopenshell.entity_instance]
+    :param constraint: The IfcObjective constraint
+    :type constraint: ifcopenshell.entity_instance
+    :return: None
+    :rtype: None
+    """
+    usecase = Usecase()
+    usecase.file = file
+    usecase.settings = {
+        "products": products,
+        "constraint": constraint,
+    }
+    return usecase.execute()
+
+
 class Usecase:
-    def __init__(
-        self,
-        file: ifcopenshell.file,
-        products: list[ifcopenshell.entity_instance],
-        constraint: ifcopenshell.entity_instance,
-    ):
-        """Unassigns a constraint from a list of products
-
-        The constraint will not be deleted and is available to be assigned to
-        other products.
-
-        :param products: The list of products the constraint applies to.
-        :type products: list[ifcopenshell.entity_instance]
-        :param constraint: The IfcObjective constraint
-        :type constraint: ifcopenshell.entity_instance
-        :return: None
-        :rtype: None
-        """
-        self.file = file
-        self.settings = {
-            "products": products,
-            "constraint": constraint,
-        }
-
     def execute(self):
         products = set(self.settings["products"])
         if not products: