comcheck-api 1.0.0__py3-none-any.whl

comcheck_api/types/custom_base_model.py

@@ -0,0 +1,314 @@
+import logging
+import re
+from typing import (
+    Any,
+    Optional,
+    TypeVar,
+    get_type_hints,
+)
+
+from pydantic.main import _model_construction
+from pydantic import BaseModel
+from comcheck_api.managers.data_manager import DataManager
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+S = TypeVar("S")
+
+
+class CustomBaseModel(BaseModel):
+    """Base model providing structured, type-safe manipulation of nested data components.
+
+    Extends Pydantic's :class:`~pydantic.BaseModel` with convenience methods
+    for appending, updating, and removing items in list-valued sub-component
+    fields (e.g. windows on a wall, skylights on a roof).  Subclasses
+    automatically gain ``add_<field>`` helper methods for every field whose
+    type is itself a :class:`~pydantic.BaseModel`.
+    """
+
+    _identifier: str = "id"
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kwargs):
+        """Automatically generate `add_<field>` methods for BaseModel-typed fields on subclasses."""
+        super().__pydantic_init_subclass__(**kwargs)
+        try:
+            from typing import get_type_hints
+
+            hints = get_type_hints(cls)
+        except Exception:
+            return
+
+        for field_name, field_type in hints.items():
+            try:
+                if isinstance(field_type, type) and issubclass(field_type, BaseModel):
+
+                    def make_adder(fn, ft):
+                        """Create an adder method that sets a single BaseModel-typed field."""
+
+                        def adder(self, instance, fn=fn, ft=ft):
+                            """Set the field `fn` to `instance` on this model."""
+                            setattr(self, fn, instance)
+                            logger.debug("Added %s: %s", fn, instance)
+
+                        adder.__name__ = f"add_{fn}"
+                        return adder
+
+                    setattr(
+                        cls, f"add_{field_name}", make_adder(field_name, field_type)
+                    )
+            except TypeError:
+                continue
+
+    def append_subcomponent(
+        self,
+        subcomponent: S | dict,
+        subcomponent_name: Optional[str] = None,
+    ) -> T:
+        """
+        Append a subcomponent to the corresponding subcomponent list.
+
+        Args:
+            subcomponent: The subcomponent instance to add.
+            subcomponent_name: Name of the subcomponent attribute (e.g., ``"door"``).
+
+        Returns:
+            Item with the new subcomponent added.
+        """
+
+        subcomponent_type, subcomponent_name = self._get_normalized_subcomponent_info(
+            subcomponent=subcomponent, subcomponent_name=subcomponent_name
+        )
+
+        current_subcomponents = self._get_subcomponent_list(subcomponent_name)
+        subcomponent_manager = DataManager[subcomponent_type](
+            initial_data=current_subcomponents, model_type=subcomponent_type
+        )
+
+        updated_list = subcomponent_manager.add_new(subcomponent)
+
+        setattr(self, subcomponent_name, updated_list)
+
+        return self
+
+    def update_subcomponent_list(
+        self,
+        *,
+        subcomponent_updates: Optional[S | dict] = None,
+        subcomponent_id: str = None,
+        subcomponent_name: str = None,
+    ) -> T:
+        """
+        Append a subcomponent to the corresponding subcomponent list.
+
+        Args:
+            subcomponent_updates: Partial updates (dict) or full model object to apply to the item.
+            subcomponent_id: The unique identifier of the subcomponent to remove
+            subcomponent_name: Name of the subcomponent attribute (e.g., "door")
+
+        Returns:
+            Item with the new subcomponent added.
+        """
+
+        subcomponent_type, subcomponent_name = self._get_normalized_subcomponent_info(
+            subcomponent=subcomponent_updates, subcomponent_name=subcomponent_name
+        )
+
+        current_subcomponents = self._get_subcomponent_list(subcomponent_name)
+        subcomponent_manager = DataManager[subcomponent_type](
+            initial_data=current_subcomponents, model_type=subcomponent_type
+        )
+
+        subcomponent_manager.modify_one(
+            id_value=subcomponent_id, updates=subcomponent_updates
+        )
+
+        setattr(self, subcomponent_name, subcomponent_manager.get_all())
+
+        return self
+
+    def remove_from_subcomponent_list(
+        self,
+        *,
+        subcomponent: Optional[S | dict] = None,
+        subcomponent_id: Optional[str] = None,
+        subcomponent_name: Optional[str] = None,
+    ) -> T:
+        """
+        Remove a subcomponent from a list-valued attribute by instance or ID.
+
+        Args:
+            subcomponent: The subcomponent instance to remove
+            subcomponent_id: The unique identifier of the subcomponent to remove
+            subcomponent_name: Name of the subcomponent attribute (e.g., "door")
+
+        Returns:
+            Item with the subcomponent removed.
+        """
+        if subcomponent is None and (subcomponent_name and subcomponent_id) is None:
+            raise ValueError(
+                "Must provide either subcomponent instance or subcomponent_id and subcomponent_name"
+            )
+
+        subcomponent_type, subcomponent_name = self._get_normalized_subcomponent_info(
+            subcomponent=subcomponent,
+            subcomponent_name=subcomponent_name,
+        )
+
+        current_subcomponents = self._get_subcomponent_list(subcomponent_name)
+        subcomponent_manager = DataManager[subcomponent_type](
+            initial_data=current_subcomponents, model_type=subcomponent_type
+        )
+
+        subcomponent_identifier = subcomponent_manager._identifier
+
+        target_id = (
+            getattr(subcomponent, subcomponent_identifier)
+            if subcomponent is not None
+            else subcomponent_id
+        )
+
+        was_deleted = subcomponent_manager.delete_one(target_id)
+
+        if not was_deleted:
+            raise ValueError(
+                f"Subcomponent with id {target_id} not found in '{subcomponent_name}'"
+            )
+
+        setattr(self, subcomponent_name, subcomponent_manager.get_all())
+
+        return self
+
+    def _get_normalized_subcomponent_info(
+        self, subcomponent: S, subcomponent_name: str | None
+    ):
+        """Resolve the concrete type and attribute name for a subcomponent.
+
+        When *subcomponent_name* is provided the type is looked up from
+        ``core_types`` by capitalising the name.  Otherwise the type and
+        name are derived from the *subcomponent* instance itself.
+
+        Args:
+            subcomponent: A model instance or dict representing the subcomponent.
+            subcomponent_name: Optional explicit attribute name (e.g. ``"door"``).
+
+        Returns:
+            A ``(subcomponent_type, resolved_subcomponent_name)`` tuple.
+
+        Raises:
+            ValueError: If the name cannot be resolved to a known type, or if
+                *subcomponent* is a dict and no *subcomponent_name* is given.
+            TypeError: If *subcomponent* is neither a dict nor a
+                :class:`CustomBaseModel`.
+        """
+        if subcomponent_name:
+            from comcheck_api.types import core_types
+
+            class_name = subcomponent_name[0].upper() + subcomponent_name[1:]
+            cls = getattr(core_types, class_name, None)
+            if cls is None:
+                raise ValueError(f"Unknown subcomponent type for name '{class_name}'")
+
+            return cls, subcomponent_name
+        else:
+            if isinstance(subcomponent, dict):
+                raise ValueError(
+                    "subcomponent_name is required when subcomponent is a dict"
+                )
+            elif isinstance(subcomponent, CustomBaseModel):
+                subcomponent_name = subcomponent.json_key()
+                return type(subcomponent), subcomponent_name
+            else:
+                raise TypeError(
+                    f"subcomponent must be a dict or CustomBaseModel instance, "
+                    f"got {type(subcomponent).__name__}"
+                )
+
+    def _get_subcomponent_list(self, subcomponent_name: str):
+        """Return the current list for a named subcomponent attribute.
+
+        Args:
+            subcomponent_name: Name of the list-valued field on this model.
+
+        Returns:
+            The current list value for the given attribute.
+
+        Raises:
+            AttributeError: If the field does not exist on this model.
+            TypeError: If the field value is not a list.
+        """
+        if subcomponent_name not in self.__class__.model_fields:
+            raise AttributeError(
+                f"{self.__class__.__name__} has no subcomponent list '{subcomponent_name}'"
+            )
+
+        current_subcomponents = getattr(self, subcomponent_name, [])
+
+        if not isinstance(current_subcomponents, list):
+            raise TypeError(
+                f"{self.__class__.__name__}.{subcomponent_name} "
+                f"must be a list, got {type(current_subcomponents).__name__}"
+            )
+
+        return current_subcomponents
+
+    def get_by_path(self, path: str, default: Any = None) -> Any | None:
+        """Traverse nested attributes/list indices using a dot-bracket path expression.
+
+        Args:
+            path: Dot-separated path string with optional bracket indexing,
+                e.g. ``"envelope.roof[0].assemblyType"``.
+            default: Value to return if any segment of the path is missing.
+
+        Returns:
+            The value at the given path, or ``default`` if not found.
+        """
+        current = self
+
+        # Split on dots that are not inside brackets
+        parts = re.split(r"\.(?![^\[]*\])", path)
+
+        try:
+            for part in parts:
+                # Handle object
+                attr_match = re.match(r"^([A-Za-z_]\w*)", part)
+                if attr_match:
+                    attr = attr_match.group(1)
+                    if not hasattr(current, attr):
+                        return default
+                    current = getattr(current, attr)
+                    remainder = part[len(attr) :]
+                else:
+                    remainder = part
+
+                # Handle brackets for possible list
+                for m in re.finditer(r"\[(.*?)\]", remainder):
+                    idx_str = m.group(1).strip()
+                    idx = int(idx_str)
+                    current = current[idx]
+        except Exception:
+            return default
+
+        return current
+
+    def require_attribute(self, path: str) -> None:
+        """Assert that a nested attribute exists and is truthy.
+
+        Args:
+            path: Dot-bracket path to the attribute (see ``get_by_path``).
+
+        Raises:
+            ValueError: If the attribute is falsy or not found.
+        """
+        if not self.get_by_path(path):
+            raise ValueError(f"'{path}' is required in project")
+
+    @classmethod
+    def json_key(cls) -> str:
+        """Return the camelCase JSON key derived from the class name.
+
+        Returns:
+            Class name with the first character lowercased (e.g. ``AgWall`` → ``agWall``).
+        """
+        return cls.__name__[0].lower() + cls.__name__[1:]

comcheck_api/utilities/__init__.py

@@ -0,0 +1,5 @@
+"""Utility functions module."""
+
+from .common import export_to_json
+
+__all__ = ["export_to_json"]

comcheck_api/utilities/common.py

@@ -0,0 +1,50 @@
+"""Common utility helpers used across the package."""
+
+import json
+import logging
+import random
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def get_random_number(min_value: int = 0, max_value: int = 100) -> int:
+    """Return a pseudo-random integer in the range [*min_value*, *max_value*].
+
+    Args:
+        min_value: Lower bound (inclusive).
+        max_value: Upper bound (inclusive).
+
+    Returns:
+        A random integer.
+    """
+    return random.randint(min_value, max_value)
+
+
+def export_to_json(data: Any, output_file: str | Path | None = None) -> str:
+    """Convert and optionally save data to JSON.
+
+    Args:
+        data: The data to convert to JSON.
+        output_file: Optional file path to save JSON data.
+
+    Returns:
+        JSON string representation of the data.
+
+    Raises:
+        Exception: If there's an error exporting data to JSON.
+    """
+    try:
+        json_data = json.dumps(data, indent=2, ensure_ascii=False)
+
+        if output_file:
+            output_path = Path(output_file).resolve()
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(json_data, encoding="utf-8")
+            logger.info("Data exported to %s", output_file)
+
+        return json_data
+    except Exception as error:
+        logger.error("Error exporting data to JSON: %s", error, exc_info=True)
+        raise

comcheck_api/utilities/envelope_utilities.py

@@ -0,0 +1,46 @@
+"""Envelope-related utility functions for COMcheck projects."""
+
+from typing import Any, Dict
+
+from comcheck_api.constants.envelope_constants import DEFAULT_ASSEMBLIES
+from comcheck_api.types.common_types import AssemblyType
+
+
+def type_map_description(type_name: str) -> str:
+    """Map assembly type to a human-readable description.
+
+    Args:
+        type_name: The assembly type identifier.
+
+    Returns:
+        A formatted description string.
+    """
+    mapping = {
+        "AgWall": "Ext Wall",
+        "BgWall": "Basement",
+    }
+    return mapping.get(type_name, type_name)
+
+
+def generate_assembly(
+    bldg_use_key: str, name: str, assembly_type: AssemblyType
+) -> Dict[str, Any]:
+    """Generate an assembly configuration by combining defaults with custom values.
+
+    Args:
+        bldg_use_key: The building use key identifier.
+        name: The custom name for the assembly.
+        assembly_type: The type of assembly (e.g., 'Window', 'AgWall', etc.).
+
+    Returns:
+        A dictionary containing the complete assembly configuration.
+    """
+    default_assembly = DEFAULT_ASSEMBLIES[assembly_type]
+    description = type_map_description(assembly_type)
+
+    result: Dict[str, Any] = {
+        **default_assembly,
+        "bldgUseKey": bldg_use_key,
+        "assemblyType": f"{description}:{name}",
+    }
+    return result

comcheck_api/utilities/id_registry.py

@@ -0,0 +1,79 @@
+"""In-memory registry for unique component identifiers.
+
+The registry tracks every ID that has been issued or imported so that
+:func:`generate_id_with_prefix` never produces duplicates within a session.
+Call :func:`reset_registry` between test runs or independent sessions.
+"""
+
+_used_ids: set[str] = set()
+_prefix_counters: dict[str, int] = {}
+
+
+def register_existing_id(id: str):
+    """Register a pre-existing ID so it is not re-issued by the generator.
+
+    Args:
+        id: The existing ID string to reserve.
+    """
+    if id in _used_ids:
+        # ID already registered, skip silently
+        return
+    _used_ids.add(id)
+
+    prefix, number = _parse_prefix_number(id)
+    if prefix:
+        current_max = _prefix_counters.get(prefix, 0)
+        if number and number > current_max:
+            _prefix_counters[prefix] = number
+
+
+def generate_id_with_prefix(prefix: str) -> str:
+    """Generate a unique ID of the form ``"<prefix> <n>"`` for the given prefix.
+
+    Args:
+        prefix: The prefix string (e.g. ``"Door:Door"``).
+
+    Returns:
+        A new unique ID string that has not been previously issued.
+    """
+    counter = _prefix_counters.get(prefix, 0) + 1
+
+    while True:
+        candidate = f"{prefix} {counter}"
+        if candidate not in _used_ids:
+            _used_ids.add(candidate)
+            _prefix_counters[prefix] = counter
+            return candidate
+        counter += 1
+
+
+def release_id(id: str):
+    """Release a previously registered ID so it may be reused.
+
+    Args:
+        id: The ID string to release.
+    """
+    _used_ids.discard(id)
+    # Note: Not adjusting _prefix_counters for simplicity
+
+
+def reset_registry():
+    """Clear all registered IDs and prefix counters, resetting the registry to empty."""
+    _used_ids.clear()
+    _prefix_counters.clear()
+
+
+def _parse_prefix_number(id: str):
+    """Parse a prefix and optional trailing number from a composite ID.
+
+    Args:
+        id: An ID string such as ``"Door:Door 5"``.
+
+    Returns:
+        A ``(prefix, number)`` tuple where *number* is ``None`` when the ID
+        has no trailing integer.
+    """
+    parts = id.rsplit(" ", 1)
+    if len(parts) == 2 and parts[1].isdigit():
+        return parts[0], int(parts[1])
+    return id, None

comcheck_api/utilities/project_utilities.py

@@ -0,0 +1,60 @@
+"""Internal helpers for validating and querying COMcheck project structures."""
+
+from typing import List
+from comcheck_api.types.custom_base_model import CustomBaseModel
+from comcheck_api.types.core_types import ComBuilding
+from comcheck_api.managers.data_manager import DataManager, get_model_info
+
+
+def _require_building_area(project: ComBuilding, building_area_key: str) -> None:
+    """
+    Ensure that project.lighting.wholeBldgUse exists and contains the given key.
+    """
+    whole_use = project.get_by_path("lighting.wholeBldgUse")
+
+    if not isinstance(whole_use, list):
+        raise ValueError("No building area (wholeBldgUse) found in project.")
+
+    if not any(getattr(area, "key", None) == building_area_key for area in whole_use):
+        raise ValueError(
+            f"Building area key '{building_area_key}' not found in lighting.wholeBldgUse."
+        )
+
+
+def find_component_in_component_list(
+    components: List[CustomBaseModel], component_id: str
+):
+    """Find a component by its identifier within a list of components.
+
+    Args:
+        components: List of model instances to search through.
+        component_id: The identifier value to look up.
+
+    Returns:
+        The matching component, or None if not found or the list is empty.
+    """
+    if not components:
+        return None
+
+    component_type = type(components[0])
+    component_manager = DataManager[component_type](
+        initial_data=components, model_type=component_type
+    )
+
+    return component_manager.get_by_identifier(component_id)
+
+
+def get_id_from_component(
+    component: CustomBaseModel,
+) -> str:
+    """Retrieve the unique identifier value of a component.
+
+    Args:
+        component: A model instance whose identifier should be extracted.
+
+    Returns:
+        The identifier string, or ``None`` if the identifier attribute is unset.
+    """
+
+    identifier, _ = get_model_info(type(component))
+    return getattr(component, identifier, None)

comcheck_api/validation.py

@@ -0,0 +1,64 @@
+"""Project-data validation helpers.
+
+Discoverable from the package root:
+
+    >>> from comcheck_api import validate_project
+    >>> result = validate_project(project_data)
+    >>> if not result.ok:
+    ...     for err in result.errors:
+    ...         print(err.loc, err.msg)
+
+No network calls. Validates against the SDK's ``ComBuilding`` Pydantic
+model.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pydantic
+from pydantic import BaseModel
+
+from comcheck_api.types.core_types import ComBuilding
+
+
+class ValidationError(BaseModel):
+    """One Pydantic validation failure with a dotted location path."""
+
+    loc: str
+    msg: str
+    type: str
+
+
+class ValidationResult(BaseModel):
+    """Outcome of validating a project against ``ComBuilding``."""
+
+    ok: bool
+    errors: list[ValidationError] = []
+
+
+def validate_project(data: dict[str, Any] | ComBuilding) -> ValidationResult:
+    """Validate ``data`` against the :class:`ComBuilding` Pydantic model.
+
+    Accepts a dict or an existing ``ComBuilding`` (round-trips through
+    ``model_dump`` so the same code path runs in both cases).
+    """
+    payload = data.model_dump() if isinstance(data, ComBuilding) else data
+    try:
+        ComBuilding.model_validate(payload)
+    except pydantic.ValidationError as e:
+        return ValidationResult(
+            ok=False,
+            errors=[
+                ValidationError(
+                    loc=".".join(str(x) for x in err["loc"]),
+                    msg=err["msg"],
+                    type=err["type"],
+                )
+                for err in e.errors()
+            ],
+        )
+    return ValidationResult(ok=True, errors=[])
+
+
+__all__ = ["ValidationError", "ValidationResult", "validate_project"]