Merge branch 'improvements-basedon-plan' into 'main'

Make API base URL configurable via environment variable

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

Author: yanyanzhu-pnnl

CHANGELOG.md

@@ -7,14 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+- Made BASE_URL configurable via COMCHECK_API_URL environment variable
+
 ### To Be Added
 - Logging implementation to replace print statements
 - Custom exception classes for better error handling
 - Comprehensive API documentation
 - Additional examples and tutorials
 
 ### To Be Fixed
-- Remove hardcoded BASE_URL, make configurable via environment
 - Fix import path documentation in __init__.py
 - Security: Remove .env from version control
 
@@ -71,7 +73,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Known Issues
 - API key must be provided manually (no OAuth flow yet)
 - Some print() statements used instead of proper logging
-- Hardcoded API URL (should be configurable)
 - Limited error handling with custom exceptions
 
 ### Breaking Changes

comcheck_api/__init__.py

@@ -1,22 +1,56 @@
-"""COMcheckWeb API package.
+"""COMcheckWeb API - Python client for programmatic building energy code compliance.
 
-Example:
-    from comcheckweb.client import COMcheckClient
-    from comcheckweb.project_operations import (
-        project_building_area_operations,
-        project_envelope_operations,
+This package provides a type-safe, automated interface to the U.S. Department of
+Energy's COMcheck Web API for building energy code compliance verification.
+
+Quick Start:
+    >>> from comcheck_api import COMcheckClient
+    >>> client = COMcheckClient(api_key="your-api-key")
+    >>> project = client.get_project("123")
+    >>> session_id = client.start_run_simulation(project)
+
+Basic Usage:
+    from comcheck_api import (
+        COMcheckClient,
+        COMCheckHTTPError,
+        export_to_json,
     )
-    from comcheckweb.utilities import export_to_json
-    from comcheckweb.utilities.get_project_default import (
-        get_default_ag_wall_template,
-        get_default_building_area_template,
+
+    client = COMcheckClient(api_key="your-key")
+
+    try:
+        projects = client.list_projects()
+        export_to_json(projects, "projects.json")
+    except COMCheckHTTPError as e:
+        print(f"HTTP error: {e.status_code}")
+
+Advanced Usage:
+    from comcheck_api import (
+        COMcheckClient,
+        project_envelope_operations,
     )
-    from comcheckweb.types import AssemblyType, AgWall
+    from comcheck_api.types import AgWall, ComBuilding
+
+    # For type imports, use the types submodule
+    # from comcheck_api.types import ...
+
+    # For advanced utilities, use the utilities submodule
+    # from comcheck_api.utilities import ...
 """
 
-# COMcheck API Client
+# Client
 from .client import COMcheckClient
 
+# Exceptions
+from .exceptions import (
+    COMCheckAPIError,
+    COMCheckHTTPError,
+    COMCheckConnectionError,
+    COMCheckValidationError,
+    COMCheckSimulationError,
+    COMCheckProjectNotFoundError,
+)
+
 # Project Defaults
 from .utilities import get_project_default
 
@@ -26,7 +60,7 @@
     project_envelope_operations,
 )
 
-# Utility Functions
+# Utilities
 from . import utilities
 
 # Types
@@ -35,7 +69,14 @@
 __all__ = [
     # Client
     "COMcheckClient",
-    # Defaults
+    # Exceptions
+    "COMCheckAPIError",
+    "COMCheckHTTPError",
+    "COMCheckConnectionError",
+    "COMCheckValidationError",
+    "COMCheckSimulationError",
+    "COMCheckProjectNotFoundError",
+    # Project Defaults
     "get_project_default",
     # Project Operations
     "project_building_area_operations",

comcheck_api/api/api_services.py

@@ -1,13 +1,20 @@
 """COMCheck API service module for making HTTP requests to the COMCheck API."""
 
-"""Note: Service layer accepts raw data types (dicts) as inputs to stay simple and 
-HTTP-library-friendly, but returns validated Pydantic models to provide type safety 
+"""Note: Service layer accepts raw data types (dicts) as inputs to stay simple and
+HTTP-library-friendly, but returns validated Pydantic models to provide type safety
 and catch API schema mismatches at the boundary."""
 
-from typing import Any, Dict, Optional
+import logging
+import os
+from typing import Any, Dict, NoReturn, Optional
 
 import httpx
 
+from comcheck_api.exceptions import (
+    COMCheckHTTPError,
+    COMCheckConnectionError,
+    COMCheckValidationError,
+)
 from comcheck_api.types.api_types import (
     RunSimulationResponse,
     SimulationStatusResponse,
@@ -18,8 +25,6 @@
 class COMCheckApiService:
     """COMCheck API service class for interacting with the COM API."""
 
-    BASE_URL: str = "https://becp-dev.pnl.gov/ahj/COM"  # COM API base URL
-
     def __init__(self, api_key: str) -> None:
         """Initialize COMCheck API service.
 
@@ -35,6 +40,9 @@ def __init__(self, api_key: str) -> None:
                 "or set it in your environment variables."
             )
         self.api_key = api_key
+        self.base_url: str = os.getenv(
+            "COMCHECK_API_URL", "https://becp-dev.pnl.gov/ahj/COM"
+        )
         self._client: Optional[httpx.Client] = None
 
     def _get_client(self) -> httpx.Client:
@@ -45,7 +53,7 @@ def _get_client(self) -> httpx.Client:
         """
         if self._client is None:
             self._client = httpx.Client(
-                base_url=self.BASE_URL,
+                base_url=self.base_url,
                 headers=self._prepare_headers(),
                 timeout=30.0,
             )
@@ -63,22 +71,48 @@ def _prepare_headers(self) -> Dict[str, str]:
             "Accept": "application/json",
         }
 
-    def _handle_api_error(self, error: Exception) -> None:
-        """Handle API errors with detailed logging.
+    def _handle_api_error(self, error: Exception) -> NoReturn:
+        """Handle API errors with detailed logging and raise custom exceptions.
 
         Args:
             error: The error object to handle
+
+        Raises:
+            COMCheckHTTPError: For HTTP status errors
+            COMCheckConnectionError: For connection/request errors
+            COMCheckValidationError: For validation errors
         """
+        logger = logging.getLogger(__name__)
+
         if isinstance(error, httpx.HTTPStatusError):
-            print(f"HTTP error occurred: {error}")
-            print(f"Status: {error.response.status_code}")
-            print(f"Response data: {error.response.text}")
-            print(f"Response headers: {error.response.headers}")
+            logger.error(
+                "HTTP error occurred: %s (Status: %s)",
+                error,
+                error.response.status_code,
+                exc_info=True,
+                extra={
+                    "response_data": error.response.text,
+                    "response_headers": dict(error.response.headers),
+                },
+            )
+            raise COMCheckHTTPError(
+                status_code=error.response.status_code,
+                message=error.response.reason_phrase,
+                response_data=error.response.text,
+            ) from error
         elif isinstance(error, httpx.RequestError):
-            print(f"Request error occurred: {error}")
-            print(f"Request: {error.request}")
+            logger.error(
+                "Request error occurred: %s",
+                error,
+                exc_info=True,
+                extra={"request": str(error.request)},
+            )
+            raise COMCheckConnectionError(
+                f"Failed to connect to COMcheck API: {str(error)}"
+            ) from error
         else:
-            print(f"Unexpected error: {error}")
+            logger.error("Unexpected error: %s", error, exc_info=True)
+            raise
 
     def get_project(self, project_id: str) -> Dict[str, Any]:
         """Get a single project by ID.
@@ -90,8 +124,8 @@ def get_project(self, project_id: str) -> Dict[str, Any]:
             API response data as dictionary
 
         Raises:
-            httpx.HTTPStatusError: If the API returns an error status
-            httpx.RequestError: If the request fails
+            COMCheckHTTPError: If the API returns an error status
+            COMCheckConnectionError: If the request fails
         """
         try:
             client = self._get_client()
@@ -100,7 +134,6 @@ def get_project(self, project_id: str) -> Dict[str, Any]:
             return response.json()
         except Exception as error:
             self._handle_api_error(error)
-            raise
 
     def get_project_list(self) -> Dict[str, Any]:
         """Get a list of all projects.
@@ -109,8 +142,8 @@ def get_project_list(self) -> Dict[str, Any]:
             API response data as dictionary
 
         Raises:
-            httpx.HTTPStatusError: If the API returns an error status
-            httpx.RequestError: If the request fails
+            COMCheckHTTPError: If the API returns an error status
+            COMCheckConnectionError: If the request fails
         """
         try:
             client = self._get_client()
@@ -119,7 +152,6 @@ def get_project_list(self) -> Dict[str, Any]:
             return response.json()
         except Exception as error:
             self._handle_api_error(error)
-            raise
 
     def update_project(
         self, project_id: str, project_data: Dict[str, Any]
@@ -134,8 +166,8 @@ def update_project(
             API response data as dictionary
 
         Raises:
-            httpx.HTTPStatusError: If the API returns an error status
-            httpx.RequestError: If the request fails
+            COMCheckHTTPError: If the API returns an error status
+            COMCheckConnectionError: If the request fails
         """
         try:
             client = self._get_client()
@@ -144,7 +176,6 @@ def update_project(
             return response.json()
         except Exception as error:
             self._handle_api_error(error)
-            raise
 
     def start_run_simulation(
         self, project_data: Dict[str, Any]
@@ -158,8 +189,8 @@ def start_run_simulation(
             RunSimulationResponse with session information
 
         Raises:
-            httpx.HTTPStatusError: If the API returns an error status
-            httpx.RequestError: If the request fails
+            COMCheckHTTPError: If the API returns an error status
+            COMCheckConnectionError: If the request fails
         """
         try:
             client = self._get_client()
@@ -170,7 +201,6 @@ def start_run_simulation(
             return RunSimulationResponse.model_construct(**response.json())
         except Exception as error:
             self._handle_api_error(error)
-            raise
 
     def get_simulation_status(self, session_id: str) -> SimulationStatusResponse:
         """Get status of a simulation.
@@ -182,8 +212,8 @@ def get_simulation_status(self, session_id: str) -> SimulationStatusResponse:
             SimulationStatusResponse with status information
 
         Raises:
-            httpx.HTTPStatusError: If the API returns an error status
-            httpx.RequestError: If the request fails
+            COMCheckHTTPError: If the API returns an error status
+            COMCheckConnectionError: If the request fails
         """
         try:
             client = self._get_client()
@@ -194,7 +224,6 @@ def get_simulation_status(self, session_id: str) -> SimulationStatusResponse:
             return SimulationStatusResponse.model_construct(**response.json())
         except Exception as error:
             self._handle_api_error(error)
-            raise
 
     def get_simulation_result(self, session_id: str) -> SimulationResultResponse:
         """Get result of a simulation.
@@ -206,8 +235,8 @@ def get_simulation_result(self, session_id: str) -> SimulationResultResponse:
             SimulationResultResponse with simulation results
 
         Raises:
-            httpx.HTTPStatusError: If the API returns an error status
-            httpx.RequestError: If the request fails
+            COMCheckHTTPError: If the API returns an error status
+            COMCheckConnectionError: If the request fails
         """
         try:
             client = self._get_client()
@@ -218,7 +247,6 @@ def get_simulation_result(self, session_id: str) -> SimulationResultResponse:
             return SimulationResultResponse.model_construct(**response.json())
         except Exception as error:
             self._handle_api_error(error)
-            raise
 
     def close(self) -> None:
         """Close the HTTP client connection."""