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.

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.

Raises:

Type	Description
ValueError	If another building area with the same areaDescription already exists in lighting.wholeBldgUse.

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.

    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.

    Raises:
        ValueError: If another building area with the same ``areaDescription``
            already exists in ``lighting.wholeBldgUse``.
    """

    desc = getattr(new_building_area, "areaDescription", None)
    if desc:
        _require_unique_area_description(project, desc)

    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.

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.

Raises:

Type	Description
ValueError	If building_area_key is not found, or if updates contains an areaDescription that already belongs to a different building area in lighting.wholeBldgUse.

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.

    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.

    Raises:
        ValueError: If ``building_area_key`` is not found, or if ``updates``
            contains an ``areaDescription`` that already belongs to a different
            building area in ``lighting.wholeBldgUse``.
    """
    _require_building_area(project, building_area_key)

    new_desc = (
        updates.get("areaDescription")
        if isinstance(updates, dict)
        else getattr(updates, "areaDescription", None)
    )
    if new_desc:
        _require_unique_area_description(
            project, new_desc, exclude_key=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
    ]