python-midas 0.1.1__py3-none-any.whl → 1.0.1__py3-none-any.whl

midas/__init__.py

@@ -5,32 +5,40 @@ from midas.client import (
     API_URL,
     MIDASClient,
     body,
+    create_anonymous_client,
     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,
+    LookupTableResponse,
     MIDASBase,
     RateInfo,
     RinListEntry,
+    RinListResponse,
     ValueData,
 )
 from midas.enums import DayType, RateType, SignalType, Unit
+from midas.time import (
+    MIDAS_ZONE,
+    PendulumDateTime,
+    parse_instant,
+    parse_local,
+    parse_value_moment,
+)
 
 __all__ = [
     # Client
     "MIDASClient",
     "create_client",
     "create_auto_client",
+    "create_anonymous_client",
     "success",
     "body",
     "API_URL",
@@ -43,19 +51,24 @@ __all__ = [
     # Entity coercion
     "coerce_rate_info",
     "coerce_rin_list",
-    "coerce_holidays",
     "coerce_lookup_table",
-    "coerce_historical_list",
     # Entity models
     "MIDASBase",
     "RateInfo",
     "ValueData",
     "RinListEntry",
-    "Holiday",
+    "RinListResponse",
     "LookupEntry",
+    "LookupTableResponse",
     # Enums
     "SignalType",
     "RateType",
     "Unit",
     "DayType",
+    # Time
+    "MIDAS_ZONE",
+    "PendulumDateTime",
+    "parse_instant",
+    "parse_local",
+    "parse_value_moment",
 ]

midas/auth.py

@@ -73,9 +73,7 @@ def get_token(
     }
 
 
-def token_expired(
-    token_info: dict[str, Any], buffer_seconds: int = 30
-) -> bool:
+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:

midas/client.py

@@ -5,17 +5,15 @@ from __future__ import annotations
 from typing import Any
 
 import httpx
+import pendulum
 
 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,
@@ -35,6 +33,17 @@ def body(resp: httpx.Response) -> Any:
     return resp.json()
 
 
+def _check_historical_range(start_date: str, end_date: str) -> None:
+    """Enforce the v2.0 6-month max range for a single historical-data call."""
+    start = pendulum.parse(start_date)
+    end = pendulum.parse(end_date)
+    if end > start.add(months=6):
+        raise ValueError(
+            "MIDAS v2.0 limits /HistoricalData to a 6-month range per call; "
+            f"requested {start_date}..{end_date}. Split into multiple calls."
+        )
+
+
 class MIDASClient:
     """MIDAS API HTTP client with raw and coerced methods."""
 
@@ -48,7 +57,9 @@ class MIDASClient:
         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)
+            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
@@ -72,43 +83,26 @@ class MIDASClient:
         """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:
+    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}
-        )
+        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,
-            },
-        )
+        return self._http.get("/ValueData", params={"LookupTable": table_name})
 
     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."""
+        """Fetch archived rate data for a RIN within a date range.
+
+        v2.0 takes the RIN as a path parameter (``/HistoricalData/{rate_id}``)
+        and caps each call at a 6-month range.
+        """
+        _check_historical_range(start_date, end_date)
         return self._http.get(
-            "/HistoricalData",
-            params={"id": rin, "startdate": start_date, "enddate": end_date},
+            f"/HistoricalData/{rin}",
+            params={"startdate": start_date, "enddate": end_date},
         )
 
     # -- Coerced methods (return typed models) --
@@ -117,11 +111,9 @@ class MIDASClient:
         """Fetch and coerce RIN list."""
         resp = self.get_rin_list(signal_type)
         resp.raise_for_status()
-        return coerce_rin_list(resp.json())
+        return coerce_rin_list(resp.json(), signal_type)
 
-    def rate_values(
-        self, rin: str, query_type: str = "alldata"
-    ) -> RateInfo:
+    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()
@@ -133,23 +125,7 @@ class MIDASClient:
         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:
+    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()
@@ -160,9 +136,12 @@ class MIDASClient:
     @staticmethod
     def ghg(rate: RateInfo) -> bool:
         """True if rate-info represents a GHG signal."""
-        if rate.type == RateType.GHG:
+        if rate.type in (RateType.GHG, RateType.MOER):
             return True
-        if rate.values and rate.values[0].unit == Unit.KG_CO2_PER_KWH:
+        if rate.values and rate.values[0].unit in (
+            Unit.G_CO2_PER_KWH,
+            Unit.KG_CO2_PER_KWH,
+        ):
             return True
         return False
 
@@ -180,9 +159,7 @@ class MIDASClient:
         """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
-        )
+        return any(v.value is not None and v.value > 0 for v in rate.values)
 
 
 def create_client(
@@ -203,3 +180,16 @@ def create_auto_client(
     """Create a MIDAS client with auto-refreshing token."""
     auth = AutoTokenAuth(username, password, url)
     return MIDASClient(base_url=url, auth=auth)
+
+
+def create_anonymous_client(url: str = API_URL) -> MIDASClient:
+    """Create an unauthenticated client for v2.0 GET endpoints (no token).
+
+    This is the default, supported access mode for this read-only consumer
+    library: v2.0 makes all public GET endpoints (rate values, RIN list, lookup
+    tables, historical data) unauthenticated, so no token is acquired and no
+    ``Authorization`` header is sent. ``create_client`` / ``create_auto_client``
+    exist only for utilities that *upload* rate data to the CEC (POST); that
+    path requires CEC-issued utility credentials and is not exercised here.
+    """
+    return MIDASClient(base_url=url)

midas/entities/__init__.py

@@ -5,10 +5,11 @@ from __future__ import annotations
 from typing import Any
 
 from midas.entities.models import (
-    Holiday,
     LookupEntry,
+    LookupTableResponse,
     RateInfo,
     RinListEntry,
+    RinListResponse,
     ValueData,
 )
 
@@ -18,42 +19,34 @@ def coerce_rate_info(raw: dict[str, Any]) -> RateInfo:
     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_rin_list(raw: dict[str, Any], signal_type: int = 0) -> list[RinListEntry]:
+    """Coerce a v2.0 keyed RIN-list response into a list of RinListEntry models.
 
+    v2.0 wraps the entry array under one of Rates/GHGEmissions/FlexAlerts/All,
+    keyed by ``signal_type``; this peels that key into a flat list.
+    """
+    return RinListResponse.from_raw(raw, signal_type).entries
 
-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: dict[str, Any] | list[dict[str, Any]],
+) -> list[LookupEntry]:
+    """Coerce a v2.0 lookup-table response into a list of LookupEntry models.
 
-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
+    v2.0 wraps the rows in ``{table_name, data: [...]}``; this peels ``data``
+    (a bare list is also tolerated for legacy/defensive use).
+    """
+    return LookupTableResponse.from_raw(raw).entries
 
 
 __all__ = [
     "coerce_rate_info",
     "coerce_rin_list",
-    "coerce_holidays",
     "coerce_lookup_table",
-    "coerce_historical_list",
-    "Holiday",
     "LookupEntry",
+    "LookupTableResponse",
     "RateInfo",
     "RinListEntry",
+    "RinListResponse",
     "ValueData",
 ]

midas/entities/models.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import datetime
 from decimal import Decimal
 from typing import Any
 
@@ -10,6 +9,11 @@ import pendulum
 from pydantic import BaseModel, ConfigDict, PrivateAttr
 
 from midas.enums import DayType, RateType, SignalType, Unit
+from midas.time import (
+    PendulumDateTime,
+    parse_instant,
+    parse_value_moment,
+)
 
 
 class MIDASBase(BaseModel):
@@ -27,38 +31,6 @@ class MIDASBase(BaseModel):
         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:
@@ -66,13 +38,10 @@ def _parse_decimal(n: int | float | None) -> Decimal | 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_day_type(v: object) -> DayType | None:
+    # v2.0 MOER/ALRT send an integer code (1=Mon..8=Holiday); v1.0/electricity
+    # send a weekday string. DayType.from_wire accepts both.
+    return DayType.from_wire(v)
 
 
 def _parse_unit(s: str | None) -> Unit | str | None:
@@ -103,29 +72,33 @@ def _parse_signal_type(s: str | None) -> SignalType | None:
 
 
 class ValueData(MIDASBase):
-    """A single time-series interval with a price or emissions value."""
+    """A single time-series interval with a price or emissions value.
+
+    The interval boundary is exposed as ``period`` — a ``(start, end)`` pair of
+    zone-aware ``pendulum.DateTime`` moments composed from the UTC wire date+time
+    (v2.0 delivers ``ValueInformation`` timestamps in UTC). Need a wall-clock
+    date or time? Derive it from a period endpoint (``period[0].in_tz(...)`` then
+    ``.date()`` / ``.time()``). The original wire strings remain on ``_raw``.
+    """
 
     name: str
-    date_start: datetime.date | None = None
-    date_end: datetime.date | None = None
+    period: tuple[pendulum.DateTime, pendulum.DateTime] | 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:
+        start = parse_value_moment(raw.get("DateStart"), raw.get("TimeStart"))
+        end = parse_value_moment(raw.get("DateEnd"), raw.get("TimeEnd"))
+        period = (start, end) if start is not None and end is not None else None
         inst = cls(
             name=raw["ValueName"],
-            date_start=_parse_date(raw.get("DateStart")),
-            date_end=_parse_date(raw.get("DateEnd")),
+            period=period,
             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")),
+            value=_parse_decimal(raw.get("Value")),
             unit=_parse_unit(raw.get("Unit")),
         )
         inst._raw = raw
@@ -136,8 +109,10 @@ class RateInfo(MIDASBase):
     """Rate information and associated time-series values for a single RIN."""
 
     id: str | None = None
-    system_time: pendulum.DateTime | None = None
+    system_time: PendulumDateTime = None
     name: str | None = None
+    signal_type: SignalType | None = None
+    description: str | None = None
     type: RateType | str | None = None
     sector: str | None = None
     end_use: str | None = None
@@ -145,7 +120,7 @@ class RateInfo(MIDASBase):
     rate_plan_url: str | None = None
     alt_name_1: str | None = None
     alt_name_2: str | None = None
-    signup_close: pendulum.DateTime | None = None
+    signup_close: PendulumDateTime = None
     values: list[ValueData] = []
 
     @classmethod
@@ -159,8 +134,12 @@ class RateInfo(MIDASBase):
 
         inst = cls(
             id=raw.get("RateID"),
-            system_time=_parse_datetime(raw.get("SystemTime_UTC")),
+            system_time=parse_instant(raw.get("SystemTime_UTC")),
             name=raw.get("RateName"),
+            # v2.0 rate-values responses carry the per-RIN SignalType label and
+            # Description at the top level (as in the RIN list).
+            signal_type=_parse_signal_type(raw.get("SignalType")),
+            description=raw.get("Description"),
             type=_parse_rate_type(raw.get("RateType")),
             sector=raw.get("Sector"),
             end_use=raw.get("EndUse"),
@@ -168,7 +147,7 @@ class RateInfo(MIDASBase):
             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")),
+            signup_close=parse_instant(raw.get("SignupCloseDate")),
             values=values,
         )
         inst._raw = raw
@@ -176,12 +155,12 @@ class RateInfo(MIDASBase):
 
 
 class RinListEntry(MIDASBase):
-    """A RIN catalog entry from the RIN list or historical list endpoints."""
+    """A RIN catalog entry from the RIN-list endpoint."""
 
     id: str
     signal_type: SignalType | None = None
     description: str | None = None
-    last_updated: pendulum.DateTime | None = None
+    last_updated: PendulumDateTime = None
 
     @classmethod
     def from_raw(cls, raw: dict[str, Any]) -> RinListEntry:
@@ -189,43 +168,94 @@ class RinListEntry(MIDASBase):
             id=raw["RateID"],
             signal_type=_parse_signal_type(raw.get("SignalType")),
             description=raw.get("Description"),
-            last_updated=_parse_datetime(raw.get("LastUpdated")),
+            # v2.0 UTC instant with a basic-format offset (e.g. "+0000"); the
+            # string is self-describing. Absent on Flex Alert entries → None.
+            last_updated=parse_instant(raw.get("LastUpdated")),
         )
         inst._raw = raw
         return inst
 
 
-class Holiday(MIDASBase):
-    """A utility holiday entry."""
+class RinListResponse(MIDASBase):
+    """The v2.0 keyed RIN-list response (``GET /ValueData?SignalType=N``).
 
-    energy_code: str
-    energy_name: str | None = None
-    date: datetime.date | None = None
-    description: str | None = None
+    v1.0 returned a bare array; v2.0 wraps it in a single-keyed object. On the
+    live v2.0 API the wrapper key is **always** ``Rates``, regardless of the
+    requested ``SignalType`` (confirmed 2026-06-22 for SignalType 0/1/2/3 — the
+    ``GHGEmissions``/``FlexAlerts``/``All`` keys implied by early design notes
+    do not appear on the wire). This model peels the single value without
+    switching on the key name; each entry's ``signal_type`` field still
+    identifies its signal class.
+    """
+
+    signal_type: int = 0
+    entries: list[RinListEntry] = []
 
     @classmethod
-    def from_raw(cls, raw: dict[str, Any]) -> Holiday:
+    def from_raw(cls, raw: dict[str, Any], signal_type: int = 0) -> RinListResponse:
+        # Always "Rates" on the live API; fall back to the first list value
+        # present so an unexpected wrapper key still peels correctly.
+        arr = raw.get("Rates")
+        if arr is None:
+            arr = next((v for v in raw.values() if isinstance(v, list)), None)
         inst = cls(
-            energy_code=raw["EnergyCode"],
-            energy_name=raw.get("EnergyDescription"),
-            date=_parse_date(raw.get("DateOfHoliday")),
-            description=raw.get("HolidayDescription"),
+            signal_type=signal_type,
+            entries=[RinListEntry.from_raw(e) for e in (arr or [])],
         )
         inst._raw = raw
         return inst
 
 
 class LookupEntry(MIDASBase):
-    """A reference/lookup table entry."""
+    """A reference/lookup table entry.
+
+    All rows carry ``UploadCode`` and ``Description``; some tables add extra
+    columns (e.g. the ``Unit`` table's ``PayloadDescriptor`` and ``UnitType``),
+    surfaced here as optional fields. Any other columns remain on ``_raw``.
+    """
 
     code: str
     description: str | None = None
+    payload_descriptor: str | None = None
+    unit_type: str | None = None
 
     @classmethod
     def from_raw(cls, raw: dict[str, Any]) -> LookupEntry:
         inst = cls(
             code=raw["UploadCode"],
             description=raw.get("Description"),
+            payload_descriptor=raw.get("PayloadDescriptor"),
+            unit_type=raw.get("UnitType"),
         )
         inst._raw = raw
         return inst
+
+
+class LookupTableResponse(MIDASBase):
+    """The v2.0 keyed lookup-table response (``GET /ValueData?LookupTable=X``).
+
+    v1.0 returned a bare array; v2.0 wraps it in ``{table_name, data: [...]}``
+    (confirmed against the live API 2026-06-22). This model peels ``data`` into
+    a flat list of :class:`LookupEntry`.
+    """
+
+    table_name: str | None = None
+    entries: list[LookupEntry] = []
+
+    @classmethod
+    def from_raw(
+        cls, raw: dict[str, Any] | list[dict[str, Any]]
+    ) -> LookupTableResponse:
+        # v2.0: keyed object. Tolerate a bare list (legacy / defensive).
+        if isinstance(raw, dict):
+            table_name = raw.get("table_name")
+            rows = raw.get("data") or []
+        else:
+            table_name = None
+            rows = raw or []
+        inst = cls(
+            table_name=table_name,
+            entries=[LookupEntry.from_raw(e) for e in rows],
+        )
+        inst._raw = raw if isinstance(raw, dict) else {"data": raw}
+        return inst