diff --git a/src/ifcopenshell-python/ifcopenshell/api/group/add_group.py b/src/ifcopenshell-python/ifcopenshell/api/group/add_group.py index 4014fbae97..4b353f27af 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/group/add_group.py +++ b/src/ifcopenshell-python/ifcopenshell/api/group/add_group.py @@ -21,14 +21,33 @@ import ifcopenshell.api class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, Name="Unnamed", Description=None): + """Adds a new group + + An IFC group is an arbitrary collection of products, which are typically + physical. It may be used when there is no other more specific group + which may be used. Other types of groups include distribution systems, + which group together products that are connected and circulate a medium + (such as fluid or electricity), or zones, which group together spaces, + or structural load groups, which group together loads for structural + analysis, or inventories, which are groups of assets. + + :param Name: The name of the group. Defaults to "Unnamed" + :type Name: str, optional + :param Description: The description of the purpose of the group. + :type Description: str, optional + :return: The newly created IfcGroup + :rtype: ifcopenshell.entity_instance.entity_instance + + Example:: + + ifcopenshell.api.run("group.add_group", model, Name="Unit 1A") + """ self.file = file self.settings = { - "Name": "Unnamed", - "Description": "", + "Name": Name or "Unnamed", + "Description": Description, } - for key, value in settings.items(): - self.settings[key] = value def execute(self): return self.file.create_entity( diff --git a/src/ifcopenshell-python/ifcopenshell/api/group/assign_group.py b/src/ifcopenshell-python/ifcopenshell/api/group/assign_group.py index bb8d80d414..4edf5a1eee 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/group/assign_group.py +++ b/src/ifcopenshell-python/ifcopenshell/api/group/assign_group.py @@ -21,14 +21,30 @@ import ifcopenshell.api class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, products=None, group=None): + """Assigns products to a group + + If a product is already assigned to the group, it will not be assigned + twice. + + :param products: A list of IfcProduct elements to assign to the group + :type products: list[ifcopenshell.entity_instance.entity_instance] + :param group: The IfcGroup to assign the products to + :type group: ifcopenshell.entity_instance.entity_instance + :return: The IfcRelAssignsToGroup relationship + :rtype: ifcopenshell.entity_instance.entity_instance + + Example:: + + group = ifcopenshell.api.run("group.add_group", model, Name="Furniture") + ifcopenshell.api.run("group.assign_group", model, + products=model.by_type("IfcFurniture"), group=group) + """ self.file = file self.settings = { - "products": None, - "group": None, + "products": products, + "group": group, } - for key, value in settings.items(): - self.settings[key] = value def execute(self): if not self.settings["group"].IsGroupedBy: diff --git a/src/ifcopenshell-python/ifcopenshell/api/group/edit_group.py b/src/ifcopenshell-python/ifcopenshell/api/group/edit_group.py index 2851b85029..51d5f8503f 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/group/edit_group.py +++ b/src/ifcopenshell-python/ifcopenshell/api/group/edit_group.py @@ -18,12 +18,28 @@ class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, group=None, attributes=None): + """Edits the attributes of an IfcGroup + + For more information about the attributes and data types of an + IfcGroup, consult the IFC documentation. + + :param group: The IfcGroup entity you want to edit + :type group: ifcopenshell.entity_instance.entity_instance + :param attributes: a dictionary of attribute names and values. + :type attributes: dict, optional + :return: None + :rtype: None + + Example:: + + group = ifcopenshell.api.run("group.add_group", model, Name="Unit 1A") + ifcopenshell.api.run("group.edit_group", model, + group=group, attributes={"Description": "All furniture and joinery included in the unit"}) + """ + self.file = file - self.settings = { - "group": None, "attributes": {}} - for key, value in settings.items(): - self.settings[key] = value + self.settings = {"group": group, "attributes": attributes or {}} def execute(self): for name, value in self.settings["attributes"].items(): diff --git a/src/ifcopenshell-python/ifcopenshell/api/group/remove_group.py b/src/ifcopenshell-python/ifcopenshell/api/group/remove_group.py index c9ec47d633..94716f66f5 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/group/remove_group.py +++ b/src/ifcopenshell-python/ifcopenshell/api/group/remove_group.py @@ -18,11 +18,24 @@ class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, group=None): + """Removes a group + + All products assigned to the group will remain, but the relationship to + the group will be removed. + + :param group: The IfcGroup entity you want to remove + :type group: ifcopenshell.entity_instance.entity_instance + :return: None + :rtype: None + + Example:: + + group = ifcopenshell.api.run("group.add_group", model, Name="Unit 1A") + ifcopenshell.api.run("group.remove_group", model, group=group) + """ self.file = file - self.settings = {"group": None} - for key, value in settings.items(): - self.settings[key] = value + self.settings = {"group": group} def execute(self): for rel in self.settings["group"].IsGroupedBy or []: diff --git a/src/ifcopenshell-python/ifcopenshell/api/group/unassign_group.py b/src/ifcopenshell-python/ifcopenshell/api/group/unassign_group.py index cd348a90f3..1491d7dc5d 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/group/unassign_group.py +++ b/src/ifcopenshell-python/ifcopenshell/api/group/unassign_group.py @@ -21,14 +21,32 @@ import ifcopenshell.api class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, product=None, group=None): + """Unassigns a product from a group + + If the product isn't assigned to the group, nothing will happen. + + :param product: A IfcProduct element to unassign from the group + :type product: ifcopenshell.entity_instance.entity_instance + :param group: The IfcGroup to assign the products to + :type group: ifcopenshell.entity_instance.entity_instance + :return: None + :rtype: None + + Example:: + + group = ifcopenshell.api.run("group.add_group", model, Name="Furniture") + furniture = model.by_type("IfcFurniture") + ifcopenshell.api.run("group.assign_group", model, products=furniture, group=group) + + bad_furniture = furniture[0] + ifcopenshell.api.run("group.unassign_group", model, product=bad_furniture, group=group) + """ self.file = file self.settings = { - "product": None, - "group": None, + "product": product, + "group": group, } - for key, value in settings.items(): - self.settings[key] = value def execute(self): if not self.settings["group"].IsGroupedBy: diff --git a/src/ifcopenshell-python/ifcopenshell/api/group/update_group_products.py b/src/ifcopenshell-python/ifcopenshell/api/group/update_group_products.py index e8133a28b7..5fccd4d9e5 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/group/update_group_products.py +++ b/src/ifcopenshell-python/ifcopenshell/api/group/update_group_products.py @@ -21,14 +21,30 @@ import ifcopenshell.api class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, group=None, products=None): + """Sets a group products to be an explicit list of products + + Any previous products assigned to that group will have their assignment + removed. + + :param products: A list of IfcProduct elements to assign to the group + :type products: list[ifcopenshell.entity_instance.entity_instance] + :param group: The IfcGroup to assign the products to + :type group: ifcopenshell.entity_instance.entity_instance + :return: The IfcRelAssignsToGroup relationship + :rtype: ifcopenshell.entity_instance.entity_instance + + Example:: + + group = ifcopenshell.api.run("group.add_group", model, Name="Furniture") + ifcopenshell.api.run("group.update_group_products", model, + products=model.by_type("IfcFurniture"), group=group) + """ self.file = file self.settings = { - "group": None, - "products": None, + "group": group, + "products": products, } - for key, value in settings.items(): - self.settings[key] = value def execute(self): if not self.settings["group"].IsGroupedBy: