Building Area Operations

Functions for adding, updating, and removing building areas in a COMcheck project.

project_building_area_operations

Project Building Area Operations.

add_building_area_to_project

add_building_area_to_project(project, new_building_area)

Add a new building area to the project using buildingAreaListManager.

Parameters:

Name	Type	Description	Default
project	ComBuilding	The project object to modify	required
new_building_area	WholeBldgUse	The building area object to add	required

Returns:

Type	Description
ComBuilding	Updated project object with the building area added

Source code in comcheck_api/project_operations/project_building_area_operations.py

def add_building_area_to_project(
    project: ComBuilding, new_building_area: WholeBldgUse
) -> ComBuilding:
    """Add a new building area to the project using buildingAreaListManager.

    Args:
        project: The project object to modify
        new_building_area: The building area object to add

    Returns:
        Updated project object with the building area added

    """

    updated_project = project.model_copy(deep=True)

    # Ensure interiorLightingSpace is initialized
    if new_building_area.interiorLightingSpace is None:
        new_building_area.interiorLightingSpace = (
            DEFAULT_BUILDING_AREA.interiorLightingSpace.model_copy(deep=True)
        )

    updated_project.lighting.append_subcomponent(new_building_area)

    return updated_project

update_building_area_in_project

update_building_area_in_project(
    project, building_area_key, updates
)

Update an existing building area in the project using buildingAreaListManager.

Parameters:

Name	Type	Description	Default
project	ComBuilding	The project object to modify	required
building_area_key	str	The key of the building area to update	required
updates	dict[str, Any] | WholeBldgUse	Partial updates (dict) or full building area object to apply	required

Returns:

Type	Description
ComBuilding	Updated project object with the building area updated

Source code in comcheck_api/project_operations/project_building_area_operations.py

def update_building_area_in_project(
    project: ComBuilding, building_area_key: str, updates: dict[str, Any] | WholeBldgUse
) -> ComBuilding:
    """Update an existing building area in the project using buildingAreaListManager.

    Args:
        project: The project object to modify
        building_area_key: The key of the building area to update
        updates: Partial updates (dict) or full building area object to apply

    Returns:
        Updated project object with the building area updated

    """
    _require_building_area(project, building_area_key)

    updated_project = project.model_copy(deep=True)

    updated_project.lighting.update_subcomponent_list(subcomponent_updates=updates, subcomponent_id=building_area_key, subcomponent_name="wholeBldgUse")

    return updated_project

remove_building_area_from_project

remove_building_area_from_project(
    project, building_area_key
)

Remove an existing building area in the project.

Parameters:

Name	Type	Description	Default
project	ComBuilding	The project object to modify	required
building_area_key	str	The key of the building area to update	required

Returns:

Type	Description
ComBuilding	Updated project object with the building area removed

Source code in comcheck_api/project_operations/project_building_area_operations.py

def remove_building_area_from_project(
    project: ComBuilding, building_area_key: str) -> ComBuilding:
    """Remove an existing building area in the project.

    Args:
        project: The project object to modify
        building_area_key: The key of the building area to update

    Returns:
        Updated project object with the building area removed

    """
    _require_building_area(project, building_area_key)

    updated_project = project.model_copy(deep=True)

    updated_project.lighting.remove_from_subcomponent_list(subcomponent_id=building_area_key, subcomponent_name="wholeBldgUse")

    return updated_project

get_building_area_keys_from_project

get_building_area_keys_from_project(project)

Extract valid building area identifiers from a COMcheck project.

This function retrieves the lighting.wholeBldgUse field from the provided project and returns a list of dictionaries containing each area's unique key and description.

Parameters:

Name	Type	Description	Default
project	ComBuilding	The COMcheck project object.	required

Returns:

Type	Description
list[dict]	list[dict]: A list of dictionaries with the shape: { "key": , "areaDescription": }

Source code in comcheck_api/project_operations/project_building_area_operations.py

def get_building_area_keys_from_project(project: ComBuilding) -> list[dict]:
    """
    Extract valid building area identifiers from a COMcheck project.

    This function retrieves the `lighting.wholeBldgUse` field from the provided
    project and returns a list of dictionaries containing each area's unique key
    and description.

    Args:
        project (ComBuilding): The COMcheck project object.

    Returns:
        list[dict]: A list of dictionaries with the shape:
            {
                "key": <area key>,
                "areaDescription": <area description>
            }
    """
    whole_use = project.get_by_path("lighting.wholeBldgUse")

    if not isinstance(whole_use, list):
        return []

    return [
        {"key": getattr(area, "key"), "areaDescription": getattr(area, "areaDescription")}
        for area in whole_use
        if getattr(area, "key", None) is not None and getattr(area, "areaDescription", None) is not None
    ]