comcheck-api 1.0.0__py3-none-any.whl

comcheck_api/types/__init__.py

@@ -0,0 +1,49 @@
+"""Type definitions for the comcheckweb-api-python package.
+
+This module re-exports all generated types from api_types and core_types
+so package users can import them directly.
+"""
+
+from types import ModuleType
+from typing import List
+
+# Import modules to access their __all__ if defined
+from . import api_types as _api_types
+from . import common_types as _common_types
+from . import core_types as _core_types
+from .api_types import *  # noqa: F401, F403
+from .common_types import *  # noqa: F401, F403
+from .core_types import *  # noqa: F401, F403
+
+
+def _collect_exports(mod: ModuleType) -> List[str]:
+    """Collect public names exported by a module.
+
+    Uses the module's ``__all__`` list when available; otherwise falls back to
+    all names that do not start with an underscore.
+
+    Args:
+        mod: The module to inspect.
+
+    Returns:
+        List of exportable name strings.
+    """
+    if hasattr(mod, "__all__"):
+        return list(mod.__all__)
+    return [name for name in dir(mod) if not name.startswith("_")]
+
+
+# Build __all__ from all modules
+__all__ = []
+
+for name in _collect_exports(_common_types):
+    if name not in __all__:
+        __all__.append(name)
+
+for name in _collect_exports(_api_types):
+    if name not in __all__:
+        __all__.append(name)
+
+for name in _collect_exports(_core_types):
+    if name not in __all__:
+        __all__.append(name)

comcheck_api/types/api_types.py

@@ -0,0 +1,127 @@
+"""Pydantic models for COMcheck API request and response payloads.
+
+These models represent the JSON structures returned by the COMcheck Web API
+and are used internally by :class:`~comcheck_api.api.COMCheckApiService` and
+:class:`~comcheck_api.client.COMcheckClient` for type-safe deserialization.
+"""
+
+from enum import StrEnum
+from typing import Any
+from pydantic import BaseModel, ConfigDict
+
+
+class SimulationStatus(StrEnum):
+    """Known lifecycle states for a COMcheck simulation session.
+
+    This catalog is **not exhaustive** — the server may introduce
+    additional states without notice. ``StatusInfo.status`` is typed
+    as ``str`` so unknown values still parse cleanly; only the
+    terminal pair (``SUCCESS`` / ``FAILED``) is guaranteed to remain
+    stable. Compare against these members for terminal detection;
+    treat anything else as "still in progress."
+    """
+
+    INITIALIZING = "INITIALIZING"
+    GENERATING_BASELINE = "GENERATING_BASELINE"
+    GENERATING_PROPOSED = "GENERATING_PROPOSED"
+    RUNNING_SIMULATIONS = "RUNNING_SIMULATIONS"
+    CALCULATING_RESULTS = "CALCULATING_RESULTS"
+    EVALUATING = "EVALUATING"
+    SUCCESS = "SUCCESS"
+    FAILED = "FAILED"
+
+
+class ApiResponse(BaseModel):
+    """Base model for all COMcheck API responses.
+
+    Attributes:
+        success: Whether the API call succeeded. Defaults to ``True``
+            because the server omits this field on successful responses
+            (failures surface as non-2xx HTTP statuses, which the client
+            raises as exceptions before validation).
+        message: Optional human-readable message from the server.
+        data: Response payload (type varies by endpoint).
+        errors: List of error strings, if any.
+    """
+
+    success: bool = True
+    message: str | None = None
+    data: Any = None
+    errors: list[str] | None = None
+
+
+class SessionInfo(BaseModel):
+    """Session metadata returned when a simulation is started.
+
+    Attributes:
+        sessionId: Unique identifier for the simulation session.
+    """
+
+    model_config = ConfigDict(extra="allow")
+    sessionId: str
+
+
+class RunSimulationResponse(ApiResponse):
+    """Response from the ``start-run-simulation`` endpoint.
+
+    Attributes:
+        data: Session information for the started simulation, or ``None`` on failure.
+    """
+
+    data: SessionInfo | None = None
+
+
+class StatusInfo(BaseModel):
+    """Simulation status details.
+
+    Attributes:
+        sessionId: The simulation session identifier.
+        status: Current lifecycle state. Typed as ``str`` because the
+            server may emit values not yet enumerated in
+            :class:`SimulationStatus` (the enum is a known-values
+            catalog, not an exhaustive contract). The terminal pair
+            (``"SUCCESS"`` / ``"FAILED"``) is guaranteed stable.
+        message: Optional status message from the server.
+    """
+
+    sessionId: str
+    status: str
+    message: str | None = None
+
+
+class SimulationStatusResponse(ApiResponse):
+    """Response from the ``get-status-simulation`` endpoint.
+
+    Attributes:
+        data: Status details for the queried session, or ``None`` on failure.
+    """
+
+    data: StatusInfo | None = None
+
+
+class SimulationResultInfo(BaseModel):
+    """Simulation result metrics.
+
+    Attributes:
+        sessionId: The simulation session identifier.
+        performanceRating: Overall performance rating (percentage).
+        energyCreditPerformanceRating: Energy credit performance rating.
+        proposedBpf: Proposed building performance factor.
+        baselineBpf: Baseline building performance factor.
+    """
+
+    sessionId: str
+    performanceRating: float | None = None
+    energyCreditPerformanceRating: float | None = None
+    proposedBpf: float | None = None
+    baselineBpf: float | None = None
+
+
+class SimulationResultResponse(ApiResponse):
+    """Response from the ``get-result-simulation`` endpoint.
+
+    Attributes:
+        data: Result metrics for the queried session, or ``None`` on failure.
+    """
+
+    data: SimulationResultInfo | None = None

comcheck_api/types/common_types.py

@@ -0,0 +1,32 @@
+"""Common utility types used throughout the comcheckweb package.
+
+This module contains generic types, enums, and type aliases that are used
+across multiple modules but aren't generated from schemas.
+"""
+
+from enum import Enum
+from typing import Literal
+
+# Type alias for assembly types
+AssemblyType = Literal[
+    "Roof", "Skylight", "AgWall", "Floor", "BgWall", "Window", "Door"
+]
+
+
+# Runtime-friendly enum (useful when you need a value at runtime)
+class AssemblyTypeEnum(str, Enum):
+    """Enum representation of assembly types for runtime validation and iteration."""
+
+    ROOF = "Roof"
+    SKYLIGHT = "Skylight"
+    AGWALL = "AgWall"
+    FLOOR = "Floor"
+    BGWALL = "BgWall"
+    WINDOW = "Window"
+    DOOR = "Door"
+
+
+__all__ = [
+    "AssemblyType",
+    "AssemblyTypeEnum",
+]