python-midas 0.1.0__py3-none-any.whl

midas/__init__.py

@@ -0,0 +1,61 @@
+"""midas — Python client library for the California Energy Commission MIDAS API."""
+
+from midas.auth import AutoTokenAuth, BasicAuth, BearerAuth, get_token, token_expired
+from midas.client import (
+    API_URL,
+    MIDASClient,
+    body,
+    create_auto_client,
+    create_client,
+    success,
+)
+from midas.entities import (
+    coerce_historical_list,
+    coerce_holidays,
+    coerce_lookup_table,
+    coerce_rate_info,
+    coerce_rin_list,
+)
+from midas.entities.models import (
+    Holiday,
+    LookupEntry,
+    MIDASBase,
+    RateInfo,
+    RinListEntry,
+    ValueData,
+)
+from midas.enums import DayType, RateType, SignalType, Unit
+
+__all__ = [
+    # Client
+    "MIDASClient",
+    "create_client",
+    "create_auto_client",
+    "success",
+    "body",
+    "API_URL",
+    # Auth
+    "BearerAuth",
+    "BasicAuth",
+    "AutoTokenAuth",
+    "get_token",
+    "token_expired",
+    # Entity coercion
+    "coerce_rate_info",
+    "coerce_rin_list",
+    "coerce_holidays",
+    "coerce_lookup_table",
+    "coerce_historical_list",
+    # Entity models
+    "MIDASBase",
+    "RateInfo",
+    "ValueData",
+    "RinListEntry",
+    "Holiday",
+    "LookupEntry",
+    # Enums
+    "SignalType",
+    "RateType",
+    "Unit",
+    "DayType",
+]

midas/auth.py

@@ -0,0 +1,109 @@
+"""Authentication utilities for the MIDAS API."""
+
+from __future__ import annotations
+
+from typing import Any, Generator
+
+import httpx
+import pendulum
+
+
+class BearerAuth(httpx.Auth):
+    """httpx Auth subclass that injects a Bearer token."""
+
+    def __init__(self, token: str) -> None:
+        self.token = token
+
+    def auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        request.headers["Authorization"] = f"Bearer {self.token}"
+        yield request
+
+
+class BasicAuth(httpx.Auth):
+    """httpx Auth subclass that injects HTTP Basic auth."""
+
+    def __init__(self, username: str, password: str) -> None:
+        import base64
+
+        credentials = f"{username}:{password}"
+        encoded = base64.b64encode(credentials.encode("utf-8")).decode("ascii")
+        self._header_value = f"Basic {encoded}"
+
+    def auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        request.headers["Authorization"] = self._header_value
+        yield request
+
+
+def get_token(
+    username: str,
+    password: str,
+    url: str = "https://midasapi.energy.ca.gov/api",
+) -> dict[str, Any]:
+    """Authenticate with MIDAS using HTTP Basic auth and return token info.
+
+    The token is returned in the `Token` response header and is valid for
+    10 minutes. Returns a dict with token, acquired_at, and expires_at.
+
+    Raises httpx.HTTPStatusError on failure.
+    """
+    import base64
+
+    credentials = f"{username}:{password}"
+    encoded = base64.b64encode(credentials.encode("utf-8")).decode("ascii")
+
+    timeout = httpx.Timeout(30.0, connect=30.0)
+    with httpx.Client(timeout=timeout) as client:
+        resp = client.get(
+            f"{url}/Token",
+            headers={"Authorization": f"Basic {encoded}"},
+        )
+        resp.raise_for_status()
+
+    token = resp.headers.get("token") or resp.headers.get("Token")
+    now = pendulum.now("UTC")
+
+    return {
+        "token": token,
+        "acquired_at": now,
+        "expires_at": now.add(seconds=600),
+    }
+
+
+def token_expired(
+    token_info: dict[str, Any], buffer_seconds: int = 30
+) -> bool:
+    """True if a token-info dict is expired or will expire within buffer_seconds."""
+    expires_at = token_info.get("expires_at")
+    if expires_at is None:
+        return True
+    now = pendulum.now("UTC")
+    return now >= expires_at.subtract(seconds=buffer_seconds)
+
+
+class AutoTokenAuth(httpx.Auth):
+    """httpx Auth that auto-refreshes the MIDAS bearer token when expired."""
+
+    def __init__(
+        self,
+        username: str,
+        password: str,
+        url: str = "https://midasapi.energy.ca.gov/api",
+        buffer_seconds: int = 30,
+    ) -> None:
+        self.username = username
+        self.password = password
+        self.url = url
+        self.buffer_seconds = buffer_seconds
+        self.token_info: dict[str, Any] = get_token(username, password, url)
+
+    def auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        if token_expired(self.token_info, self.buffer_seconds):
+            self.token_info = get_token(self.username, self.password, self.url)
+        request.headers["Authorization"] = f"Bearer {self.token_info['token']}"
+        yield request

midas/client.py

@@ -0,0 +1,205 @@
+"""MIDAS API client — HTTP with entity coercion."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from midas.auth import AutoTokenAuth, BearerAuth, get_token
+from midas.entities import (
+    coerce_historical_list,
+    coerce_holidays,
+    coerce_lookup_table,
+    coerce_rate_info,
+    coerce_rin_list,
+)
+from midas.entities.models import (
+    Holiday,
+    LookupEntry,
+    RateInfo,
+    RinListEntry,
+)
+from midas.enums import RateType, Unit
+
+API_URL = "https://midasapi.energy.ca.gov/api"
+
+
+def success(resp: httpx.Response) -> bool:
+    """Check if an HTTP response indicates success (2xx)."""
+    return 200 <= resp.status_code < 300
+
+
+def body(resp: httpx.Response) -> Any:
+    """Extract JSON body from a response."""
+    return resp.json()
+
+
+class MIDASClient:
+    """MIDAS API HTTP client with raw and coerced methods."""
+
+    def __init__(
+        self,
+        base_url: str = API_URL,
+        token: str | None = None,
+        auth: httpx.Auth | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        _timeout = httpx.Timeout(timeout, connect=timeout)
+        if auth:
+            self._http = httpx.Client(base_url=self.base_url, auth=auth, timeout=_timeout)
+        elif token:
+            self._http = httpx.Client(
+                base_url=self.base_url, auth=BearerAuth(token), timeout=_timeout
+            )
+        else:
+            self._http = httpx.Client(base_url=self.base_url, timeout=_timeout)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self) -> MIDASClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    # -- Raw methods (return httpx.Response) --
+
+    def get_rin_list(self, signal_type: int = 0) -> httpx.Response:
+        """Fetch list of available RINs by signal type (0=All, 1=Rates, 2=GHG, 3=Flex Alert)."""
+        return self._http.get("/ValueData", params={"SignalType": signal_type})
+
+    def get_rate_values(
+        self, rin: str, query_type: str = "alldata"
+    ) -> httpx.Response:
+        """Fetch rate/price values for a specific RIN."""
+        return self._http.get(
+            "/ValueData", params={"ID": rin, "QueryType": query_type}
+        )
+
+    def get_lookup_table(self, table_name: str) -> httpx.Response:
+        """Fetch a MIDAS lookup/reference table."""
+        return self._http.get(
+            "/ValueData", params={"LookupTable": table_name}
+        )
+
+    def get_holidays(self) -> httpx.Response:
+        """Fetch all utility holidays."""
+        return self._http.get("/Holiday")
+
+    def get_historical_list(
+        self, distribution_code: str, energy_code: str
+    ) -> httpx.Response:
+        """Fetch list of RINs with historical data for a provider pair."""
+        return self._http.get(
+            "/HistoricalList",
+            params={
+                "DistributionCode": distribution_code,
+                "EnergyCode": energy_code,
+            },
+        )
+
+    def get_historical_data(
+        self, rin: str, start_date: str, end_date: str
+    ) -> httpx.Response:
+        """Fetch archived rate data for a RIN within a date range."""
+        return self._http.get(
+            "/HistoricalData",
+            params={"id": rin, "startdate": start_date, "enddate": end_date},
+        )
+
+    # -- Coerced methods (return typed models) --
+
+    def rin_list(self, signal_type: int = 0) -> list[RinListEntry]:
+        """Fetch and coerce RIN list."""
+        resp = self.get_rin_list(signal_type)
+        resp.raise_for_status()
+        return coerce_rin_list(resp.json())
+
+    def rate_values(
+        self, rin: str, query_type: str = "alldata"
+    ) -> RateInfo:
+        """Fetch and coerce rate values for a specific RIN."""
+        resp = self.get_rate_values(rin, query_type)
+        resp.raise_for_status()
+        return coerce_rate_info(resp.json())
+
+    def lookup_table(self, table_name: str) -> list[LookupEntry]:
+        """Fetch and coerce a lookup table."""
+        resp = self.get_lookup_table(table_name)
+        resp.raise_for_status()
+        return coerce_lookup_table(resp.json())
+
+    def holidays(self) -> list[Holiday]:
+        """Fetch and coerce holidays."""
+        resp = self.get_holidays()
+        resp.raise_for_status()
+        return coerce_holidays(resp.json())
+
+    def historical_list(
+        self, distribution_code: str, energy_code: str
+    ) -> list[RinListEntry]:
+        """Fetch and coerce historical RIN list (deduplicated)."""
+        resp = self.get_historical_list(distribution_code, energy_code)
+        resp.raise_for_status()
+        return coerce_historical_list(resp.json())
+
+    def historical_data(
+        self, rin: str, start_date: str, end_date: str
+    ) -> RateInfo:
+        """Fetch and coerce historical rate data."""
+        resp = self.get_historical_data(rin, start_date, end_date)
+        resp.raise_for_status()
+        return coerce_rate_info(resp.json())
+
+    # -- Signal type helpers --
+
+    @staticmethod
+    def ghg(rate: RateInfo) -> bool:
+        """True if rate-info represents a GHG signal."""
+        if rate.type == RateType.GHG:
+            return True
+        if rate.values and rate.values[0].unit == Unit.KG_CO2_PER_KWH:
+            return True
+        return False
+
+    @staticmethod
+    def flex_alert(rate: RateInfo) -> bool:
+        """True if rate-info represents a Flex Alert signal."""
+        if rate.type == RateType.FLEX_ALERT:
+            return True
+        if rate.values and rate.values[0].unit == Unit.EVENT:
+            return True
+        return False
+
+    @staticmethod
+    def flex_alert_active(rate: RateInfo) -> bool:
+        """True if the Flex Alert indicates an active alert (any non-zero value)."""
+        if not MIDASClient.flex_alert(rate):
+            return False
+        return any(
+            v.value is not None and v.value > 0 for v in rate.values
+        )
+
+
+def create_client(
+    username: str,
+    password: str,
+    url: str = API_URL,
+) -> MIDASClient:
+    """Create a MIDAS client with a manually-acquired token."""
+    token_info = get_token(username, password, url)
+    return MIDASClient(base_url=url, token=token_info["token"])
+
+
+def create_auto_client(
+    username: str,
+    password: str,
+    url: str = API_URL,
+) -> MIDASClient:
+    """Create a MIDAS client with auto-refreshing token."""
+    auth = AutoTokenAuth(username, password, url)
+    return MIDASClient(base_url=url, auth=auth)

midas/entities/__init__.py

@@ -0,0 +1,59 @@
+"""Entity coercion dispatch for MIDAS API responses."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from midas.entities.models import (
+    Holiday,
+    LookupEntry,
+    RateInfo,
+    RinListEntry,
+    ValueData,
+)
+
+
+def coerce_rate_info(raw: dict[str, Any]) -> RateInfo:
+    """Coerce a raw rate info response dict into a RateInfo model."""
+    return RateInfo.from_raw(raw)
+
+
+def coerce_rin_list(raw: list[dict[str, Any]]) -> list[RinListEntry]:
+    """Coerce a raw RIN list response into a list of RinListEntry models."""
+    return [RinListEntry.from_raw(entry) for entry in raw]
+
+
+def coerce_holidays(raw: list[dict[str, Any]]) -> list[Holiday]:
+    """Coerce a raw holidays response into a list of Holiday models."""
+    return [Holiday.from_raw(entry) for entry in raw]
+
+
+def coerce_lookup_table(raw: list[dict[str, Any]]) -> list[LookupEntry]:
+    """Coerce a raw lookup table response into a list of LookupEntry models."""
+    return [LookupEntry.from_raw(entry) for entry in raw]
+
+
+def coerce_historical_list(raw: list[dict[str, Any]]) -> list[RinListEntry]:
+    """Coerce a raw historical list response, deduplicating by RIN ID."""
+    seen: set[str] = set()
+    result: list[RinListEntry] = []
+    for entry in raw:
+        rid = entry["RateID"]
+        if rid not in seen:
+            seen.add(rid)
+            result.append(RinListEntry.from_raw(entry))
+    return result
+
+
+__all__ = [
+    "coerce_rate_info",
+    "coerce_rin_list",
+    "coerce_holidays",
+    "coerce_lookup_table",
+    "coerce_historical_list",
+    "Holiday",
+    "LookupEntry",
+    "RateInfo",
+    "RinListEntry",
+    "ValueData",
+]

midas/entities/models.py

@@ -0,0 +1,231 @@
+"""Coerced Pydantic models for MIDAS API entities."""
+
+from __future__ import annotations
+
+import datetime
+from decimal import Decimal
+from typing import Any
+
+import pendulum
+from pydantic import BaseModel, ConfigDict, PrivateAttr
+
+from midas.enums import DayType, RateType, SignalType, Unit
+
+
+class MIDASBase(BaseModel):
+    """Base model for all coerced MIDAS entities.
+
+    Carries the original raw dict as a private attribute.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    _raw: dict[str, Any] = PrivateAttr(default_factory=dict)
+
+    @classmethod
+    def from_raw(cls, raw: dict[str, Any]) -> MIDASBase:
+        raise NotImplementedError("Subclasses must implement from_raw")
+
+
+def _parse_date(s: str | None) -> datetime.date | None:
+    """Parse an ISO date string (YYYY-MM-DD) or extract date from datetime string."""
+    if not s or not isinstance(s, str):
+        return None
+    # Handle datetime strings like "2023-12-25T00:00:00" — take date part
+    date_part = s[:10] if len(s) >= 10 else s
+    parts = date_part.split("-")
+    return datetime.date(int(parts[0]), int(parts[1]), int(parts[2]))
+
+
+def _parse_datetime(s: str | None) -> pendulum.DateTime | None:
+    """Parse an ISO datetime string, treating naive datetimes as UTC."""
+    if not s or not isinstance(s, str):
+        return None
+    dt = pendulum.parse(s)
+    if dt.timezone is None or dt.timezone_name is None:
+        dt = dt.in_tz("UTC")
+    return dt
+
+
+def _parse_time(s: str | None) -> datetime.time | None:
+    """Parse a time string (HH:MM:SS or HH:MM)."""
+    if not s or not isinstance(s, str):
+        return None
+    parts = s.split(":")
+    if len(parts) == 2:
+        return datetime.time(int(parts[0]), int(parts[1]))
+    if len(parts) == 3:
+        return datetime.time(int(parts[0]), int(parts[1]), int(parts[2]))
+    return None
+
+
+def _parse_decimal(n: int | float | None) -> Decimal | None:
+    """Coerce a number to Decimal."""
+    if n is None:
+        return None
+    return Decimal(str(n))
+
+
+def _parse_day_type(s: str | None) -> DayType | None:
+    if not s:
+        return None
+    try:
+        return DayType(s)
+    except ValueError:
+        return None
+
+
+def _parse_unit(s: str | None) -> Unit | str | None:
+    if not s:
+        return None
+    try:
+        return Unit(s)
+    except ValueError:
+        return s
+
+
+def _parse_rate_type(s: str | None) -> RateType | str | None:
+    if not s:
+        return None
+    try:
+        return RateType(s)
+    except ValueError:
+        return s
+
+
+def _parse_signal_type(s: str | None) -> SignalType | None:
+    if not s:
+        return None
+    try:
+        return SignalType(s)
+    except ValueError:
+        return None
+
+
+class ValueData(MIDASBase):
+    """A single time-series interval with a price or emissions value."""
+
+    name: str
+    date_start: datetime.date | None = None
+    date_end: datetime.date | None = None
+    day_start: DayType | None = None
+    day_end: DayType | None = None
+    time_start: datetime.time | None = None
+    time_end: datetime.time | None = None
+    value: Decimal | None = None
+    unit: Unit | str | None = None
+
+    @classmethod
+    def from_raw(cls, raw: dict[str, Any]) -> ValueData:
+        inst = cls(
+            name=raw["ValueName"],
+            date_start=_parse_date(raw.get("DateStart")),
+            date_end=_parse_date(raw.get("DateEnd")),
+            day_start=_parse_day_type(raw.get("DayStart")),
+            day_end=_parse_day_type(raw.get("DayEnd")),
+            time_start=_parse_time(raw.get("TimeStart")),
+            time_end=_parse_time(raw.get("TimeEnd")),
+            value=_parse_decimal(raw.get("value")),
+            unit=_parse_unit(raw.get("Unit")),
+        )
+        inst._raw = raw
+        return inst
+
+
+class RateInfo(MIDASBase):
+    """Rate information and associated time-series values for a single RIN."""
+
+    id: str
+    system_time: pendulum.DateTime | None = None
+    name: str | None = None
+    type: RateType | str | None = None
+    sector: str | None = None
+    end_use: str | None = None
+    api_url: str | None = None
+    rate_plan_url: str | None = None
+    alt_name_1: str | None = None
+    alt_name_2: str | None = None
+    signup_close: pendulum.DateTime | None = None
+    values: list[ValueData] = []
+
+    @classmethod
+    def from_raw(cls, raw: dict[str, Any]) -> RateInfo:
+        api_url = raw.get("API_Url")
+        if api_url == "None":
+            api_url = None
+
+        vi = raw.get("ValueInformation")
+        values = [ValueData.from_raw(v) for v in vi] if vi else []
+
+        inst = cls(
+            id=raw["RateID"],
+            system_time=_parse_datetime(raw.get("SystemTime_UTC")),
+            name=raw.get("RateName"),
+            type=_parse_rate_type(raw.get("RateType")),
+            sector=raw.get("Sector"),
+            end_use=raw.get("EndUse"),
+            api_url=api_url,
+            rate_plan_url=raw.get("RatePlan_Url"),
+            alt_name_1=raw.get("AltRateName1"),
+            alt_name_2=raw.get("AltRateName2"),
+            signup_close=_parse_datetime(raw.get("SignupCloseDate")),
+            values=values,
+        )
+        inst._raw = raw
+        return inst
+
+
+class RinListEntry(MIDASBase):
+    """A RIN catalog entry from the RIN list or historical list endpoints."""
+
+    id: str
+    signal_type: SignalType | None = None
+    description: str | None = None
+    last_updated: pendulum.DateTime | None = None
+
+    @classmethod
+    def from_raw(cls, raw: dict[str, Any]) -> RinListEntry:
+        inst = cls(
+            id=raw["RateID"],
+            signal_type=_parse_signal_type(raw.get("SignalType")),
+            description=raw.get("Description"),
+            last_updated=_parse_datetime(raw.get("LastUpdated")),
+        )
+        inst._raw = raw
+        return inst
+
+
+class Holiday(MIDASBase):
+    """A utility holiday entry."""
+
+    energy_code: str
+    energy_name: str | None = None
+    date: datetime.date | None = None
+    description: str | None = None
+
+    @classmethod
+    def from_raw(cls, raw: dict[str, Any]) -> Holiday:
+        inst = cls(
+            energy_code=raw["EnergyCode"],
+            energy_name=raw.get("EnergyDescription"),
+            date=_parse_date(raw.get("DateOfHoliday")),
+            description=raw.get("HolidayDescription"),
+        )
+        inst._raw = raw
+        return inst
+
+
+class LookupEntry(MIDASBase):
+    """A reference/lookup table entry."""
+
+    code: str
+    description: str | None = None
+
+    @classmethod
+    def from_raw(cls, raw: dict[str, Any]) -> LookupEntry:
+        inst = cls(
+            code=raw["UploadCode"],
+            description=raw.get("Description"),
+        )
+        inst._raw = raw
+        return inst

midas/enums.py

@@ -0,0 +1,41 @@
+"""MIDAS domain enumerations."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class SignalType(str, Enum):
+    RATES = "Rates"
+    GHG = "GHG"
+    FLEX_ALERT = "Flex Alert"
+
+
+class RateType(str, Enum):
+    TOU = "Time of use"
+    CPP = "Critical Peak Pricing"
+    RTP = "Real Time Pricing"
+    GHG = "Greenhouse Gas emissions"
+    FLEX_ALERT = "Flex Alert"
+
+
+class Unit(str, Enum):
+    DOLLAR_PER_KWH = "$/kWh"
+    DOLLAR_PER_KW = "$/kW"
+    EXPORT_DOLLAR_PER_KWH = "export $/kWh"
+    BACKUP_DOLLAR_PER_KWH = "backup $/kWh"
+    KG_CO2_PER_KWH = "kg/kWh CO2"
+    DOLLAR_PER_KVARH = "$/kvarh"
+    EVENT = "Event"
+    LEVEL = "Level"
+
+
+class DayType(str, Enum):
+    MONDAY = "Monday"
+    TUESDAY = "Tuesday"
+    WEDNESDAY = "Wednesday"
+    THURSDAY = "Thursday"
+    FRIDAY = "Friday"
+    SATURDAY = "Saturday"
+    SUNDAY = "Sunday"
+    HOLIDAY = "Holiday"

python_midas-0.1.0.dist-info/METADATA

@@ -0,0 +1,404 @@
+Metadata-Version: 2.4
+Name: python-midas
+Version: 0.1.0
+Summary: Python client library for the California Energy Commission MIDAS API
+Project-URL: Homepage, https://grid-coordination.energy
+Project-URL: Repository, https://github.com/grid-coordination/python-midas
+Project-URL: Issues, https://github.com/grid-coordination/python-midas/issues
+Author: Clark Communications Corporation
+License-Expression: MIT
+License-File: LICENSE
+Keywords: california,energy,ghg,grid,midas,rates
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pendulum>=3.0
+Requires-Dist: pydantic>=2.5
+Provides-Extra: dev
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# python-midas
+
+Python client library for the California Energy Commission [MIDAS](https://midasapi.energy.ca.gov/) (Market Informed Demand Automation Server) API.
+
+MIDAS provides California energy rate data, greenhouse gas (GHG) emissions signals, and Flex Alert status. This library wraps the API with typed Pydantic models, automatic token management, and a two-layer data model that preserves raw API responses alongside coerced Python-native types.
+
+Part of the [grid-coordination](https://github.com/grid-coordination) project family, alongside [clj-midas](https://github.com/grid-coordination/clj-midas) (Clojure client) and [midas-api-specs](https://github.com/grid-coordination/midas-api-specs) (OpenAPI specifications).
+
+## Installation
+
+```bash
+pip install midas
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```python
+from midas import create_auto_client
+
+client = create_auto_client("username", "password")
+
+# List available Rate Identification Numbers (RINs)
+rins = client.rin_list()
+for rin in rins:
+    print(f"{rin.id}  {rin.signal_type}  {rin.description}")
+
+# Get rate values for a specific RIN
+rate = client.rate_values(rins[0].id)
+print(f"{rate.name} ({rate.type})")
+for v in rate.values:
+    print(f"  {v.date_start} {v.time_start}-{v.time_end}: {v.value} {v.unit}")
+```
+
+## Authentication
+
+MIDAS uses HTTP Basic authentication to acquire a short-lived bearer token (valid for 10 minutes). The library provides two client creation modes:
+
+### Auto-refreshing client (recommended)
+
+`create_auto_client` acquires a token on creation and transparently refreshes it before any request where the token is expired or about to expire (within a 30-second buffer):
+
+```python
+from midas import create_auto_client
+
+client = create_auto_client("username", "password")
+# Token refreshes automatically — use the client for as long as you need
+```
+
+### Manual token client
+
+`create_client` acquires a single token. You are responsible for creating a new client when it expires:
+
+```python
+from midas import create_client
+
+client = create_client("username", "password")
+# Token is valid for ~10 minutes
+```
+
+### Low-level token management
+
+For advanced use cases, you can manage tokens directly:
+
+```python
+from midas import get_token, token_expired, MIDASClient
+
+token_info = get_token("username", "password")
+# token_info = {"token": "...", "acquired_at": DateTime, "expires_at": DateTime}
+
+if token_expired(token_info):
+    token_info = get_token("username", "password")
+
+client = MIDASClient(token=token_info["token"])
+```
+
+## API Coverage
+
+The MIDAS API has a single multiplexed `/ValueData` endpoint that serves different response shapes depending on query parameters, plus separate endpoints for holidays and historical data. All six operations are covered:
+
+### RIN List
+
+List available Rate Identification Numbers, optionally filtered by signal type:
+
+```python
+all_rins = client.rin_list()                # All signal types
+rate_rins = client.rin_list(signal_type=1)  # Rates only
+ghg_rins = client.rin_list(signal_type=2)   # GHG only
+flex_rins = client.rin_list(signal_type=3)  # Flex Alert only
+```
+
+Each `RinListEntry` has:
+- `id` — the RIN string (e.g. `"USCA-PGPG-ETOU-0000"`)
+- `signal_type` — `SignalType.RATES`, `SignalType.GHG`, or `SignalType.FLEX_ALERT`
+- `description` — human-readable description
+- `last_updated` — `pendulum.DateTime` of last data update
+
+### Rate Values
+
+Fetch current rate/price data for a specific RIN:
+
+```python
+rate = client.rate_values("USCA-TSTS-TTOU-TEST")
+rate = client.rate_values("USCA-TSTS-TTOU-TEST", query_type="realtime")
+```
+
+The `RateInfo` model contains:
+- `id` — the RIN
+- `name` — rate name (e.g. `"CEC TEST24HTOU"`)
+- `type` — `RateType` enum (`TOU`, `CPP`, `RTP`, `GHG`, `FLEX_ALERT`) or raw string
+- `system_time` — server timestamp as `pendulum.DateTime`
+- `sector`, `end_use` — customer classification
+- `rate_plan_url`, `api_url` — external links (the API's `"None"` string is coerced to `None`)
+- `signup_close` — rate signup deadline as `pendulum.DateTime`
+- `values` — list of `ValueData` intervals
+
+Each `ValueData` interval has:
+- `name` — period description (e.g. `"winter off peak"`)
+- `date_start`, `date_end` — `datetime.date`
+- `day_start`, `day_end` — `DayType` enum (Monday through Sunday, plus Holiday)
+- `time_start`, `time_end` — `datetime.time` (handles both `HH:MM:SS` and `HH:MM` formats)
+- `value` — `Decimal` (preserves precision for financial data)
+- `unit` — `Unit` enum (`$/kWh`, `$/kW`, `kg/kWh CO2`, `Event`, etc.)
+
+### Lookup Tables
+
+Fetch reference data tables:
+
+```python
+energies = client.lookup_table("Energy")       # Energy providers
+dists = client.lookup_table("Distribution")    # Distribution companies
+units = client.lookup_table("Unit")            # Available units
+sectors = client.lookup_table("Sector")        # Customer sectors
+```
+
+Available tables: `Country`, `Daytype`, `Distribution`, `Enduse`, `Energy`, `Location`, `Ratetype`, `Sector`, `State`, `Unit`.
+
+Each `LookupEntry` has `code` and `description`.
+
+### Holidays
+
+Fetch utility-observed holidays:
+
+```python
+holidays = client.holidays()
+for h in holidays:
+    print(f"{h.energy_name}: {h.date} — {h.description}")
+```
+
+Each `Holiday` has `energy_code`, `energy_name`, `date` (`datetime.date`), and `description`.
+
+### Historical Data
+
+Query archived rate data by provider and date range:
+
+```python
+# List RINs with historical data for a provider pair
+hist_rins = client.historical_list("PG", "PG")  # PG&E distribution + energy
+
+# Fetch archived data for a date range
+hist = client.historical_data("USCA-PGPG-ETOU-0000", "2023-01-01", "2023-12-31")
+```
+
+The historical list is automatically deduplicated (the live API returns duplicate entries).
+
+## Signal Type Helpers
+
+Convenience methods for identifying signal types, matching the [clj-midas](https://github.com/grid-coordination/clj-midas) API:
+
+```python
+rate = client.rate_values("USCA-GHGH-SGHT-0000")
+
+client.ghg(rate)               # True if GHG signal (by RateType or Unit)
+client.flex_alert(rate)        # True if Flex Alert signal
+client.flex_alert_active(rate) # True if Flex Alert with any non-zero value
+```
+
+## Two-Layer Data Model
+
+Following the [python-oa3](https://github.com/grid-coordination/python-oa3) pattern, every entity provides two layers:
+
+**Raw layer** — the original API JSON dict (PascalCase keys, string values), accessible via `_raw`:
+
+```python
+rate = client.rate_values("USCA-TSTS-TTOU-TEST")
+rate._raw["RateID"]                           # "USCA-TSTS-TTOU-TEST"
+rate._raw["ValueInformation"][0]["value"]      # 0.1006
+rate.values[0]._raw["Unit"]                   # "$/kWh"
+```
+
+**Coerced layer** — typed Pydantic models with snake_case fields and native Python types:
+
+```python
+rate.id                      # "USCA-TSTS-TTOU-TEST"
+rate.type                    # RateType.TOU
+rate.system_time             # pendulum.DateTime (UTC)
+rate.values[0].value         # Decimal("0.1006")
+rate.values[0].unit          # Unit.DOLLAR_PER_KWH
+rate.values[0].day_start     # DayType.MONDAY
+rate.values[0].date_start    # datetime.date(2023, 5, 1)
+rate.values[0].time_start    # datetime.time(7, 0, 0)
+```
+
+This lets you work with clean, typed data while always being able to fall back to the exact API response when needed.
+
+## Dual-Mode Client
+
+Every endpoint is available in two forms:
+
+**Raw methods** return `httpx.Response` for full HTTP control:
+
+```python
+resp = client.get_rin_list(signal_type=0)
+resp.status_code  # 200
+resp.json()       # raw JSON list
+
+resp = client.get_rate_values("USCA-TSTS-TTOU-TEST", query_type="alldata")
+resp = client.get_lookup_table("Energy")
+resp = client.get_holidays()
+resp = client.get_historical_list("PG", "PG")
+resp = client.get_historical_data("USCA-PGPG-ETOU-0000", "2023-01-01", "2023-12-31")
+```
+
+**Coerced methods** return typed Pydantic models (call `raise_for_status()` internally):
+
+```python
+rins = client.rin_list(signal_type=0)           # list[RinListEntry]
+rate = client.rate_values("USCA-TSTS-TTOU-TEST") # RateInfo
+entries = client.lookup_table("Energy")           # list[LookupEntry]
+holidays = client.holidays()                      # list[Holiday]
+rins = client.historical_list("PG", "PG")        # list[RinListEntry]
+rate = client.historical_data(rin, start, end)    # RateInfo
+```
+
+## Coercion Functions
+
+You can also coerce raw dicts directly, without going through the client:
+
+```python
+from midas import coerce_rate_info, coerce_rin_list, coerce_holidays
+
+rate = coerce_rate_info({"RateID": "...", "ValueInformation": [...]})
+rins = coerce_rin_list([{"RateID": "...", "SignalType": "Rates", ...}])
+```
+
+Available: `coerce_rate_info`, `coerce_rin_list`, `coerce_holidays`, `coerce_lookup_table`, `coerce_historical_list`.
+
+## Enums
+
+Domain values are represented as `str` enums, so they compare equal to their string values:
+
+```python
+from midas import SignalType, RateType, Unit, DayType
+
+SignalType.RATES          # "Rates"
+SignalType.GHG            # "GHG"
+SignalType.FLEX_ALERT     # "Flex Alert"
+
+RateType.TOU              # "Time of use"
+RateType.CPP              # "Critical Peak Pricing"
+RateType.RTP              # "Real Time Pricing"
+RateType.GHG              # "Greenhouse Gas emissions"
+RateType.FLEX_ALERT       # "Flex Alert"
+
+Unit.DOLLAR_PER_KWH       # "$/kWh"
+Unit.DOLLAR_PER_KW        # "$/kW"
+Unit.EXPORT_DOLLAR_PER_KWH # "export $/kWh"
+Unit.BACKUP_DOLLAR_PER_KWH # "backup $/kWh"
+Unit.KG_CO2_PER_KWH       # "kg/kWh CO2"
+Unit.DOLLAR_PER_KVARH      # "$/kvarh"
+Unit.EVENT                 # "Event"
+Unit.LEVEL                 # "Level"
+
+DayType.MONDAY             # "Monday"
+# ... through SUNDAY, plus:
+DayType.HOLIDAY            # "Holiday"
+```
+
+## Type Coercion Details
+
+The coercion layer applies the following transformations:
+
+| API type | Python type | Notes |
+|----------|-------------|-------|
+| Date strings (`"2023-05-01"`) | `datetime.date` | Extracts date from datetime strings too |
+| Datetime strings | `pendulum.DateTime` | Naive datetimes treated as UTC |
+| Time strings (`"07:00:00"`, `"03:11"`) | `datetime.time` | Handles both `HH:MM:SS` and `HH:MM` |
+| Numeric values | `Decimal` | Preserves precision for financial data |
+| Signal type strings | `SignalType` enum | `None` passes through as `None` |
+| Rate type strings | `RateType` enum | Unknown values pass through as strings |
+| Unit strings | `Unit` enum | Unknown values pass through as strings |
+| Day type strings | `DayType` enum | `None` passes through (historical data) |
+| `"None"` string (API_Url) | `None` | MIDAS API quirk |
+
+## Context Manager
+
+The client supports context manager protocol for clean resource management:
+
+```python
+from midas import create_auto_client
+
+with create_auto_client("user", "pass") as client:
+    rins = client.rin_list()
+    rate = client.rate_values(rins[0].id)
+# httpx client is closed automatically
+```
+
+## Project Structure
+
+```
+src/midas/
+    __init__.py          # Public API re-exports
+    py.typed             # PEP 561 type-checking marker
+    client.py            # MIDASClient, create_client, create_auto_client
+    auth.py              # BearerAuth, BasicAuth, AutoTokenAuth, get_token
+    enums.py             # SignalType, RateType, Unit, DayType
+    entities/
+        __init__.py      # Coercion dispatch functions
+        models.py        # Pydantic models: RateInfo, ValueData, RinListEntry, Holiday, LookupEntry
+tests/
+    test_entities.py     # Entity coercion from raw fixture dicts
+    test_client.py       # HTTP client tests with pytest-httpx
+    test_auth.py         # Token parsing, expiry, auth headers
+    test_integration.py  # Live API tests (requires MIDAS credentials)
+```
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Lint
+ruff check src/ tests/
+```
+
+### Tests
+
+The test suite has two tiers:
+
+**Unit tests** run entirely offline using fixture dicts and mocked HTTP (pytest-httpx):
+
+```bash
+pytest -m "not integration"
+```
+
+**Integration tests** run against the live MIDAS API at `midasapi.energy.ca.gov`. They require credentials in environment variables and are skipped automatically when the variables are not set:
+
+```bash
+export MIDAS_USERNAME="you@example.com"
+export MIDAS_PASSWORD="your-password"
+pytest -m integration
+```
+
+Integration tests exercise the full auth flow (token acquisition, expiry checks), every endpoint (RIN list, rate values, lookup tables, holidays, historical list/data), all entity coercion paths against real response shapes, and the signal type helpers (GHG, Flex Alert detection).
+
+Note that the MIDAS API server can be slow (5-20+ seconds per request is normal), so the integration suite takes a few minutes to complete. Run everything together with just `pytest`.
+
+## Related Projects
+
+- **[midas-api-specs](https://github.com/grid-coordination/midas-api-specs)** — OpenAPI specifications for the MIDAS API, derived from documentation and live API validation
+- **[clj-midas](https://github.com/grid-coordination/clj-midas)** — Clojure client for the MIDAS API (Martian-based, spec-driven)
+- **[python-oa3](https://github.com/grid-coordination/python-oa3)** — Python client for OpenADR 3 (same entity API pattern)
+
+## License
+
+MIT

python_midas-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+midas/__init__.py,sha256=6KNBi8eoH9KuzfnEhXqjqa2RU4nW183454lZHDcbCjQ,1223
+midas/auth.py,sha256=tCXEVrhnTrkYbyOSnWXHvBiAqk1QJaJIc2lPOqz2brA,3307
+midas/client.py,sha256=SV7L8nOme25yXcGEGYH9T5igQhuZ8nuyfILBtiDaRNo,6513
+midas/enums.py,sha256=u688kEIX6eBOueY1VcdeoHI2wtJyTbyzfiJ3-IRPQ0E,869
+midas/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+midas/entities/__init__.py,sha256=L8lS5g8vXeEeOF2KEVFrYolvoGRs4Ik-Bw0M1Rsj53c,1633
+midas/entities/models.py,sha256=cCZbwDtBjA4XnSeyOXIRtWSyAdUaoJBEsEDQqXff9OU,6685
+python_midas-0.1.0.dist-info/METADATA,sha256=bX6CKeFaqFH2kS1Hy7j5krJat3bfdXX4zk00A6Gesb4,14523
+python_midas-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_midas-0.1.0.dist-info/licenses/LICENSE,sha256=SNfEtQtKuaLySMOhEdErGT_hoKN-6L0BJlPJpUXZoDI,1089
+python_midas-0.1.0.dist-info/RECORD,,

python_midas-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

python_midas-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clark Communications Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.