Merge branch 'docstrings-mypycheck' into 'main'

Docstrings mypycheck

See merge request becp/checktool-libraries/comcheckweb-api-python!15

Author: yanyanzhu-pnnl

comcheck_api/client/comcheck_client.py

@@ -78,6 +78,15 @@ def get_project(
         project_id: str,
         mode: Literal["python", "json"] = "python",
     ) -> Optional[Union["ComBuilding", Dict[str, Any]]]:
+        """Fetch a single project by ID.
+
+        Args:
+            project_id: The project ID to retrieve.
+            mode: ``"python"`` returns a ``ComBuilding`` model; ``"json"`` returns a raw dict.
+
+        Returns:
+            The project as a ``ComBuilding`` or dict, or ``None`` if not found.
+        """
         resp = self._service.get_project(project_id)
         data = resp.get("data")
         if data is not None:
@@ -90,13 +99,13 @@ def get_project(
 
         return self._parse_data(data, mode)
 
-    def list_projects(self) -> Dict[str, Any]:
+    def list_projects(self) -> List[Dict[str, Any]]:
         """Get a list of all projects.
 
         Returns:
-            API response data as dictionary
+            API response data as list of project dictionaries
         """
-        return self._service.get_project_list().get("data", {})
+        return self._service.get_project_list().get("data", [])
 
     # TODO: return of update_project should be ComBuilding
     def update_project(
@@ -195,6 +204,15 @@ def update_project(
         return self.get_project(project_id=project_id, mode=mode)
 
     def _parse_data(self, data, mode):
+        """Convert raw API data to the requested output format.
+
+        Args:
+            data: Raw dict from the API response, or ``None``.
+            mode: ``"python"`` wraps data in a ``ComBuilding``; ``"json"`` returns it as-is.
+
+        Returns:
+            A ``ComBuilding``, a raw dict, or ``None`` if ``data`` is ``None``.
+        """
         if data is None:
             return None
         if mode == "python":

comcheck_api/constants/building_area_constants.py

@@ -5,29 +5,31 @@
 from comcheck_api.types.core_types import WholeBldgUse
 
 # Default building area structure with interior lighting space
-DEFAULT_BUILDING_AREA: WholeBldgUse = WholeBldgUse(**{
-    "key": str(uuid4()),
-    "wholeBldgType": "WHOLE_BUILDING_AUTOMOTIVE",  # TODO: wholeBldgType is a list of enum, need to define the enum type
-    "areaDescription": "Automotive Facility",
-    "constructionType": "NON_RESIDENTIAL",
-    "floorArea": 1000,
-    "internalLoad": 0,
-    "powerDensity": 0.71,  # TODO: power density is automatically calculated based on wholeBldgType
-    "isTenantSpace": False,  # TODO: space conditioning is a list of enum, need to define the enum type
-    "activityUse": [],
-    "interiorLightingSpace": {
-        "altExemptType": "EXEMPT_NOT_SET",
-        "description": "",
-        "numFixturesAlteredOrAdded": 0,
-        "postAltTotalWattage": 0,
-        "preAltNumberFixtures": 0,
-        "preAltTotalWattage": 0,
-        "allowanceType": None,
-        "exemptionType": None,
-        "allowanceFloorArea": 0,
-        "rcrFloorToWorkplaneHeight": 0,
-        "rcrPerimeter": 0,
-        "rcrWorkplaneToLuminaireHeight": 0,
-        "fixture": [],
-    },  # redundant data, but need it for backend call
-})
+DEFAULT_BUILDING_AREA: WholeBldgUse = WholeBldgUse.model_validate(
+    {
+        "key": str(uuid4()),
+        "wholeBldgType": "WHOLE_BUILDING_AUTOMOTIVE",  # TODO: wholeBldgType is a list of enum, need to define the enum type
+        "areaDescription": "Automotive Facility",
+        "constructionType": "NON_RESIDENTIAL",
+        "floorArea": 1000,
+        "internalLoad": 0,
+        "powerDensity": 0.71,  # TODO: power density is automatically calculated based on wholeBldgType
+        "isTenantSpace": False,  # TODO: space conditioning is a list of enum, need to define the enum type
+        "activityUse": [],
+        "interiorLightingSpace": {
+            "altExemptType": "EXEMPT_NOT_SET",
+            "description": "",
+            "numFixturesAlteredOrAdded": 0,
+            "postAltTotalWattage": 0,
+            "preAltNumberFixtures": 0,
+            "preAltTotalWattage": 0,
+            "allowanceType": None,
+            "exemptionType": None,
+            "allowanceFloorArea": 0,
+            "rcrFloorToWorkplaneHeight": 0,
+            "rcrPerimeter": 0,
+            "rcrWorkplaneToLuminaireHeight": 0,
+            "fixture": [],
+        },  # redundant data, but need it for backend call
+    }
+)

comcheck_api/constants/common_constants.py

@@ -1,7 +1,7 @@
 from comcheck_api.types.core_types import ComBuilding
 
-PROJECT_TEMPLATE = ComBuilding(
-    **{
+PROJECT_TEMPLATE = ComBuilding.model_validate(
+    {
         "control": {
             "code": "CEZ_IECC2018",
             "complianceMode": "UA",

comcheck_api/constants/envelope_constants.py

@@ -15,8 +15,8 @@
 )
 from comcheck_api.utilities.common import get_random_number
 
-DEFAULT_WINDOW: Window = Window(
-    **{
+DEFAULT_WINDOW: Window = Window.model_validate(
+    {
         "adjacentSpaceBuildingType": "WHOLE_BUILDING_OFFICE",
         "adjacentSpaceType": "ADJACENT_SPACE_EXTERIOR",
         "allowanceType": "ENV_ALLOWANCE_NONE",
@@ -48,8 +48,8 @@
     }
 )
 
-DEFAULT_DOOR: Door = Door(
-    **{
+DEFAULT_DOOR: Door = Door.model_validate(
+    {
         "adjacentSpaceBuildingType": None,
         "adjacentSpaceType": None,
         "allowanceType": None,
@@ -83,8 +83,8 @@
     }
 )
 
-DEFAULT_SKYLIGHT: Skylight = Skylight(
-    **{
+DEFAULT_SKYLIGHT: Skylight = Skylight.model_validate(
+    {
         "adjacentSpaceType": None,
         "allowanceType": None,
         "assemblyType": "Skylight:Default Skylight",
@@ -110,8 +110,8 @@
     }
 )
 
-DEFAULT_ROOF: Roof = Roof(
-    **{
+DEFAULT_ROOF: Roof = Roof.model_validate(
+    {
         "adjacentSpaceType": None,
         "allowanceType": None,
         "assemblyType": "Roof:Default Roof",
@@ -134,8 +134,8 @@
     }
 )
 
-DEFAULT_FLOOR: Floor = Floor(
-    **{
+DEFAULT_FLOOR: Floor = Floor.model_validate(
+    {
         "adjacentSpaceType": None,
         "allowanceType": None,
         "altExemptType": None,
@@ -158,8 +158,8 @@
     }
 )
 
-DEFAULT_AG_WALL: AgWall = AgWall(
-    **{
+DEFAULT_AG_WALL: AgWall = AgWall.model_validate(
+    {
         "adjacentSpaceType": None,
         "agWallConstructionDetailsType": "NONE",
         "agWallExteriorFinishDetailsType": None,
@@ -191,8 +191,8 @@
     }
 )
 
-DEFAULT_THERMAL_BRIDGE: ThermalBridge = ThermalBridge(
-    **{
+DEFAULT_THERMAL_BRIDGE: ThermalBridge = ThermalBridge.model_validate(
+    {
         "chiFactor": 0,
         "id": get_random_number(),
         "numberOfPoints": 0,
@@ -204,8 +204,8 @@
     }
 )
 
-DEFAULT_BG_WALL: BgWall = BgWall(
-    **{
+DEFAULT_BG_WALL: BgWall = BgWall.model_validate(
+    {
         "adjacentSpaceBuildingType": None,
         "adjacentSpaceType": None,
         "allowanceType": None,
@@ -235,13 +235,7 @@
 )
 
 DEFAULT_ENVELOPE: Envelope = Envelope(
-    agWall=[],
-    bgWall=[],
-    roof=[],
-    floor=[],
-    door=[],
-    window=[],
-    skylight=[]
+    agWall=[], bgWall=[], roof=[], floor=[], door=[], window=[], skylight=[]
 )
 
 # TODO: add values to other assemblies

comcheck_api/exceptions.py

@@ -11,6 +11,13 @@ class COMCheckHTTPError(COMCheckAPIError):
     """HTTP request failed."""
 
     def __init__(self, status_code: int, message: str, response_data: str = ""):
+        """Initialize with the HTTP status code, message, and optional response body.
+
+        Args:
+            status_code: The HTTP status code returned by the API.
+            message: Human-readable error description.
+            response_data: Raw response body text (empty string if unavailable).
+        """
         self.status_code = status_code
         self.response_data = response_data
         super().__init__(f"HTTP {status_code}: {message}")
@@ -38,5 +45,10 @@ class COMCheckProjectNotFoundError(COMCheckAPIError):
     """Project not found."""
 
     def __init__(self, project_id: str):
+        """Initialize with the ID of the project that was not found.
+
+        Args:
+            project_id: The project ID that could not be located.
+        """
         self.project_id = project_id
         super().__init__(f"Project with ID '{project_id}' not found")

comcheck_api/managers/components/envelope/ag_wall.py

@@ -1,6 +1,5 @@
 """AgWall (exterior wall) manager for COMcheck projects."""
 
-from typing import Union
 from comcheck_api.types.core_types import (
     AgWall,
     Door,
@@ -31,15 +30,9 @@ class AgWallListManager(DataManager[AgWall]):
     def add_new_thermal_bridge(
         self,
         ag_wall: AgWall,
-        thermal_bridge_type: Union[
-            ThermalBridgeTypeOptions, str
-        ] = ThermalBridgeTypeOptions.THERMAL_BRIDGE_OTHER,
-        thermal_bridge_category: Union[
-            ThermalBridgeCategoryOptions, str
-        ] = ThermalBridgeCategoryOptions.THERMAL_BRIDGE_UNCATEGORIZED,
-        thermal_bridge_compliance_type: Union[
-            ThermalBridgeComplianceTypeOptions, str
-        ] = ThermalBridgeComplianceTypeOptions.THERMAL_BRIDGE_NON_PRESCRIPTIVE,
+        thermal_bridge_type: ThermalBridgeTypeOptions = ThermalBridgeTypeOptions.THERMAL_BRIDGE_OTHER,
+        thermal_bridge_category: ThermalBridgeCategoryOptions = ThermalBridgeCategoryOptions.THERMAL_BRIDGE_UNCATEGORIZED,
+        thermal_bridge_compliance_type: ThermalBridgeComplianceTypeOptions = ThermalBridgeComplianceTypeOptions.THERMAL_BRIDGE_NON_PRESCRIPTIVE,
         psi_factor: float = 0.0,
         chi_factor: float = 0.0,
         thermal_bridge_length: float = 0.0,

comcheck_api/managers/data_manager.py

@@ -52,6 +52,14 @@ def __init__(
         self._initialize_data(initial_data)
 
     def _initialize_metadata(self, model_type: BaseModel | None = None) -> None:
+        """Resolve and store the model type and its ID field information.
+
+        Args:
+            model_type: Explicit model class; falls back to the class-level ``model_type``.
+
+        Raises:
+            ValueError: If no model type is available or no ID info is found for it.
+        """
         self.model_type = model_type or self.__class__.model_type
         if self.model_type is None:
             raise ValueError(
@@ -77,6 +85,11 @@ def _initialize_schema(self, schema_path: str | Path) -> None:
                     self._schema = json.load(f)
 
     def _initialize_data(self, initial_data: list[T] = []) -> None:
+        """Populate the manager with an initial list of items.
+
+        Args:
+            initial_data: Items to add via ``add_new`` on startup.
+        """
         for item in initial_data:
             self.add_new(item)
 
@@ -96,9 +109,9 @@ def _validate_item(self, item: T) -> T:
             model_instance = item
         else:
             model_instance = self.model_type.model_validate(item)
-        
+
         return model_instance
-    
+
     def _get_identifier_value(self, item: T) -> Any:
         """Extract the identifier value from an item.
 
@@ -305,6 +318,15 @@ def modify_one(self, id_value: Any, updates: T | dict[str, Any]) -> T:
 
 
 def get_model_info(model_class: Type[BaseModel]) -> IdInfo | None:
+    """Return the identifier field name and ID prefix for a known model class.
+
+    Args:
+        model_class: The Pydantic model class to look up.
+
+    Returns:
+        An ``IdInfo`` namedtuple with ``identifier`` and ``id_prefix`` fields,
+        or ``None`` if the class is not registered.
+    """
     from comcheck_api.types.core_types import (
         Door,
         Roof,