python-midas 1.0.0__tar.gz → 1.0.1__tar.gz

{python_midas-1.0.0 → python_midas-1.0.1}/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). While the library was in early development (0.x), breaking changes appeared between minor versions when needed to fix correctness issues or align with the MIDAS API. The 1.0.0 release tracks the California Energy Commission's MIDAS v2.0 API.
 
+## [1.0.1] - 2026-06-24
+
+Patch release. Regenerating the spec examples against the live API surfaced two wire-shape details the lenient client silently tolerated; both are now handled and guarded by tests.
+
+### Fixed
+
+- **Integer day-types are no longer dropped.** Live v2.0 SGIP GHG (MOER) and Flex Alert (ALRT) responses encode `DayStart` / `DayEnd` as integers (1=Monday through 7=Sunday, 8=Holiday: the upload-format code), where v1.0 returned weekday strings. `_parse_day_type` previously tried `DayType(value)` and returned `None` on the resulting `ValueError`, so every MOER/ALRT interval lost its `day_start` / `day_end`. `DayType.from_wire` now accepts the integer code, a digit string, or a weekday string; the electricity-rate wire form (unconfirmed pending utility-data migration) is covered by accepting both.
+
+### Added
+
+- **`RateInfo.signal_type` and `RateInfo.description`.** v2.0 rate-values responses carry the per-RIN `SignalType` label and `Description` at the top level (as in the RIN list); these are now surfaced on the entity instead of being silently ignored.
+- **Strict wire-contract validation in the integration suite.** New `TestWireContract` validates raw live responses against the `midas-api-specs` JSON Schemas (via `jsonschema`), and the coerced tests now assert day-type values, so future wire drift fails the suite rather than being absorbed by the lenient runtime models. Point `MIDAS_SPECS_DIR` at a `midas-api-specs` checkout to enable the schema checks (they skip cleanly if absent). Adds `jsonschema` as a dev dependency.
+
 ## [1.0.0] — 2026-06-22
 
 The California Energy Commission released **MIDAS v2.0 on 2026-06-22**, a breaking change to the live API. v1.0 was removed from the live service that day, so python-midas 1.0.0 is a **v2-only release** — v1.0 compatibility is intentionally dropped. See [doc/v2-migration.md](doc/v2-migration.md) for the v1.0→v2.0 upgrade guide, and the upstream [`midas-api-specs`](https://github.com/grid-coordination/midas-api-specs) `v2` branch for the spec-level delta. Every change below was verified by a live smoke-test against the production v2.0 API on release day. python-midas is a **read-only consumer client**: v2.0 GET endpoints are unauthenticated, so `create_anonymous_client` needs no credentials; the authenticated constructors remain for the utility upload path only.
@@ -43,6 +56,7 @@ The California Energy Commission released **MIDAS v2.0 on 2026-06-22**, a breaki
 
 Initial implementation. Two-layer raw/coerced data model: raw `httpx.Response` accessors plus coerced Pydantic entities (`RateInfo`, `ValueData`, `RinListEntry`, `Holiday`, `LookupEntry`) with `Decimal` prices and pendulum datetimes, each carrying its original wire dict on `_raw`. httpx-based `MIDASClient` with HTTP Basic → bearer-token auth and transparent auto-refresh (`AutoTokenAuth`); RIN list, rate values, lookup tables, holidays, and historical endpoints; signal-type helpers (`ghg`, `flex_alert`, `flex_alert_active`); domain enums (`SignalType`, `RateType`, `Unit`, `DayType`).
 
+[1.0.1]: https://github.com/grid-coordination/python-midas/releases/tag/v1.0.1
 [1.0.0]: https://github.com/grid-coordination/python-midas/releases/tag/v1.0.0
 [0.1.1]: https://github.com/grid-coordination/python-midas/releases/tag/v0.1.1
 [0.1.0]: https://github.com/grid-coordination/python-midas/releases/tag/v0.1.0

{python_midas-1.0.0 → python_midas-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-midas
-Version: 1.0.0
+Version: 1.0.1
 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
@@ -23,6 +23,7 @@ Requires-Dist: httpx>=0.27
 Requires-Dist: pendulum>=3.0
 Requires-Dist: pydantic>=2.5
 Provides-Extra: dev
+Requires-Dist: jsonschema>=4.18; extra == 'dev'
 Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.3; extra == 'dev'

{python_midas-1.0.0 → python_midas-1.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-midas"
-version = "1.0.0"
+version = "1.0.1"
 description = "Python client library for the California Energy Commission MIDAS API"
 readme = "README.md"
 license = "MIT"
@@ -35,6 +35,9 @@ dev = [
     "pytest>=8.0",
     "pytest-httpx>=0.30",
     "ruff>=0.3",
+    # Strict wire-contract validation in the integration suite (validates raw
+    # responses against the midas-api-specs JSON Schemas).
+    "jsonschema>=4.18",
 ]
 
 [project.urls]

{python_midas-1.0.0 → python_midas-1.0.1}/src/midas/entities/models.py

@@ -38,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:
@@ -114,6 +111,8 @@ class RateInfo(MIDASBase):
     id: str | 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
@@ -137,6 +136,10 @@ class RateInfo(MIDASBase):
             id=raw.get("RateID"),
             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"),

{python_midas-1.0.0 → python_midas-1.0.1}/src/midas/enums.py

@@ -71,3 +71,41 @@ class DayType(str, Enum):
     SATURDAY = "Saturday"
     SUNDAY = "Sunday"
     HOLIDAY = "Holiday"
+
+    @classmethod
+    def from_wire(cls, v: object) -> "DayType | None":
+        """Coerce a wire day-type value to a DayType, or None if unmappable.
+
+        v2.0 SGIP GHG (MOER) and Flex Alert (ALRT) responses encode the day
+        type as an INTEGER upload code (1=Monday ... 7=Sunday, 8=Holiday); v1.0
+        and electricity rates use the weekday string ("Monday"). Both forms are
+        accepted (a digit string such as "1" is treated as the integer code).
+        """
+        if isinstance(v, bool) or v is None:
+            return None
+        if isinstance(v, int):
+            return _DAY_TYPE_BY_CODE.get(v)
+        if isinstance(v, str):
+            s = v.strip()
+            if not s:
+                return None
+            if s.isdigit():
+                return _DAY_TYPE_BY_CODE.get(int(s))
+            try:
+                return cls(s)
+            except ValueError:
+                return None
+        return None
+
+
+#: v2.0 integer day-type upload codes (1=Monday ... 7=Sunday, 8=Holiday).
+_DAY_TYPE_BY_CODE: dict[int, DayType] = {
+    1: DayType.MONDAY,
+    2: DayType.TUESDAY,
+    3: DayType.WEDNESDAY,
+    4: DayType.THURSDAY,
+    5: DayType.FRIDAY,
+    6: DayType.SATURDAY,
+    7: DayType.SUNDAY,
+    8: DayType.HOLIDAY,
+}

{python_midas-1.0.0 → python_midas-1.0.1}/tests/test_entities.py

@@ -12,6 +12,7 @@ from midas.entities import (
     coerce_rin_list,
 )
 from midas.entities.models import (
+    _parse_day_type,
     _parse_rate_type,
     _parse_signal_type,
     _parse_unit,
@@ -149,6 +150,23 @@ def test_rate_type_moer_parses():
     assert _parse_rate_type("Some Future Type") == "Some Future Type"
 
 
+def test_day_type_integer_codes_parse():
+    # v2.0 MOER/ALRT send integer day-type codes (1=Mon..7=Sun, 8=Holiday).
+    assert _parse_day_type(1) == DayType.MONDAY
+    assert _parse_day_type(7) == DayType.SUNDAY
+    assert _parse_day_type(8) == DayType.HOLIDAY
+    # Digit strings are treated as the integer code.
+    assert _parse_day_type("3") == DayType.WEDNESDAY
+    # v1.0 / electricity weekday strings still parse.
+    assert _parse_day_type("Monday") == DayType.MONDAY
+    # Out-of-range, empty, None, and junk coerce to None (not an error).
+    assert _parse_day_type(0) is None
+    assert _parse_day_type(9) is None
+    assert _parse_day_type(None) is None
+    assert _parse_day_type("") is None
+    assert _parse_day_type("Funday") is None
+
+
 # -- RIN List tests --
 
 
@@ -239,6 +257,47 @@ def test_rate_info_raw_preserved():
     assert rate.values[0]._raw == RAW_RATE_INFO["ValueInformation"][0]
 
 
+# v2.0 MOER/ALRT rate-values shape: top-level SignalType/Description, and
+# integer day-type codes in ValueInformation.
+RAW_MOER_RATE = {
+    "RateID": "USCA-SGIP-MOER-PGE",
+    "SystemTime_UTC": "2026-06-23T03:34:50.858999Z",
+    "RateName": "SGIP_CAISO_PGE Realtime GHG Emissions",
+    "RateType": "Greenhouse Gas emissions",
+    "SignalType": "Greenhouse Gas Emissions",
+    "Description": "SGIP_CAISO_PGE Realtime GHG Emissions - Greenhouse Gas emissions",
+    "ValueInformation": [
+        {
+            "ValueName": "Realtime SGIP GHG Emission",
+            "DateStart": "2026-06-22",
+            "DateEnd": "2026-06-22",
+            "DayStart": 1,
+            "DayEnd": 1,
+            "TimeStart": "07:00:00",
+            "TimeEnd": "07:04:59",
+            "Unit": "g/kWh CO2",
+            "Value": 643.19,
+        }
+    ],
+}
+
+
+def test_rate_info_surfaces_signal_type_and_description():
+    # v2.0 carries the per-RIN SignalType label and Description at the top level.
+    rate = coerce_rate_info(RAW_MOER_RATE)
+    assert rate.signal_type == SignalType.GHG_EMISSIONS
+    assert rate.description == RAW_MOER_RATE["Description"]
+
+
+def test_rate_info_integer_day_types_not_dropped():
+    # Integer DayStart/DayEnd must coerce, not silently become None
+    # (regression: python-midas-ib9).
+    rate = coerce_rate_info(RAW_MOER_RATE)
+    v = rate.values[0]
+    assert v.day_start == DayType.MONDAY
+    assert v.day_end == DayType.MONDAY
+
+
 # -- Flex Alert tests --
 
 

{python_midas-1.0.0 → python_midas-1.0.1}/tests/test_integration.py

@@ -16,14 +16,26 @@ paths; thin/absent data on a given RIN is expected this week, not a regression.
 
 from __future__ import annotations
 
+import json
+import os
 from decimal import Decimal
+from pathlib import Path
 
 import httpx
 import pendulum
 import pytest
 
+try:
+    import jsonschema
+    from referencing import Registry, Resource
+
+    _HAVE_JSONSCHEMA = True
+except ImportError:  # pragma: no cover - dev extra not installed
+    _HAVE_JSONSCHEMA = False
+
 from midas import (
     MIDASClient,
+    DayType,
     RateInfo,
     RinListEntry,
     LookupEntry,
@@ -138,6 +150,10 @@ class TestRateValues:
         rin = _first_ghg_rin(client)
         rate = client.rate_values(rin, query_type="realtime")
         assert len(rate.values) > 0
+        # v2.0 surfaces the per-RIN SignalType label and Description at the top
+        # level of a rate-values response.
+        assert rate.signal_type == SignalType.GHG_EMISSIONS
+        assert rate.description is not None
 
         v = rate.values[0]
         assert isinstance(v, ValueData)
@@ -152,6 +168,10 @@ class TestRateValues:
         assert start <= end
         assert isinstance(v.value, Decimal)
         assert v.unit is not None
+        # MOER sends integer day-type codes (1=Mon..8=Holiday); they must coerce
+        # to DayType, not silently drop to None (regression: python-midas-ib9).
+        assert v.day_start in DayType.__members__.values()
+        assert v.day_end in DayType.__members__.values()
 
     def test_realtime_query(self, client: MIDASClient):
         rate = client.rate_values(TOU_TEST_RIN, query_type="realtime")
@@ -170,6 +190,8 @@ class TestFlexAlert:
         assert client.flex_alert(rate) is True
         assert len(rate.values) > 0
         assert rate.values[0].unit == Unit.EVENT
+        # ALRT also sends integer day-types; confirm they coerce.
+        assert rate.values[0].day_start in DayType.__members__.values()
 
     def test_flex_alert_active_type(self, client: MIDASClient):
         rate = client.rate_values(FLEX_RIN)
@@ -251,7 +273,85 @@ class TestGHG:
 class TestRetiredRins:
     def test_legacy_flex_rin_errors(self, client: MIDASClient):
         # Legacy SGIP/Flex RINs are retired in v2.0. The live API returns
-        # HTTP 404 ("RIN not found") — note: NOT 410 Gone as the migration
-        # notes state (filed as a midas-api-specs discrepancy).
+        # HTTP 404 ("RIN not found"), not 410 Gone as the migration notes
+        # state (filed as a midas-api-specs discrepancy).
         resp = client.get_rate_values(LEGACY_FLEX_RIN)
         assert resp.status_code == 404
+
+
+# -- Strict wire-contract validation --
+#
+# The endpoint tests above assert on the lenient coerced model, which by design
+# tolerates drift (extra='ignore', lenient day-type/rate-type passthrough). That
+# leniency is correct for production but masks wire changes: it is how the
+# integer-day-type bug (python-midas-ib9) shipped undetected. These tests
+# validate the RAW response JSON against the authoritative midas-api-specs JSON
+# Schemas, so any divergence from the documented wire contract (an unmodeled
+# field, a wrong day-type encoding) fails the suite.
+
+
+def _specs_schema_dir() -> Path | None:
+    """Locate the midas-api-specs value-data schema directory.
+
+    Honours MIDAS_SPECS_DIR (the midas-api-specs checkout root); otherwise
+    falls back to a sibling checkout next to this repo. Returns None if not
+    found, so the strict tests skip rather than fail off a missing sibling.
+    """
+    candidates = []
+    env = os.environ.get("MIDAS_SPECS_DIR")
+    if env:
+        candidates.append(Path(env) / "apis" / "value-data" / "schemas")
+    repo_root = Path(__file__).resolve().parents[1]
+    candidates.append(
+        repo_root.parent / "midas-api-specs" / "apis" / "value-data" / "schemas"
+    )
+    return next((c for c in candidates if c.is_dir()), None)
+
+
+def _validator(schema_filename: str):
+    """Build a Draft 2020-12 validator for one schema, with a registry that
+    resolves the sibling ``*.schema.json`` ``$ref`` files by their ``$id``."""
+    schema_dir = _specs_schema_dir()
+    if schema_dir is None:
+        return None
+    resources = []
+    for path in schema_dir.glob("*.schema.json"):
+        contents = json.loads(path.read_text())
+        resources.append(
+            (contents.get("$id", path.name), Resource.from_contents(contents))
+        )
+    registry = Registry().with_resources(resources)
+    root = json.loads((schema_dir / schema_filename).read_text())
+    return jsonschema.Draft202012Validator(root, registry=registry)
+
+
+@pytest.mark.skipif(not _HAVE_JSONSCHEMA, reason="jsonschema dev extra not installed")
+class TestWireContract:
+    def _assert_valid(self, schema_filename: str, payload) -> None:
+        validator = _validator(schema_filename)
+        if validator is None:
+            pytest.skip(
+                "midas-api-specs schemas not found; set MIDAS_SPECS_DIR to the "
+                "midas-api-specs checkout to enable strict wire-contract checks"
+            )
+        errors = sorted(validator.iter_errors(payload), key=lambda e: list(e.path))
+        assert not errors, "wire diverges from midas-api-specs:\n" + "\n".join(
+            f"  {list(e.absolute_path)}: {e.message}" for e in errors
+        )
+
+    def test_moer_rate_values_matches_schema(self, client: MIDASClient):
+        rin = _first_ghg_rin(client)
+        raw = client.get_rate_values(rin, query_type="realtime").json()
+        self._assert_valid("midas-rate-info.schema.json", raw)
+
+    def test_flex_rate_values_matches_schema(self, client: MIDASClient):
+        raw = client.get_rate_values(FLEX_RIN).json()
+        self._assert_valid("midas-rate-info.schema.json", raw)
+
+    def test_rin_list_matches_schema(self, client: MIDASClient):
+        raw = client.get_rin_list(signal_type=2).json()
+        self._assert_valid("midas-rin-list-response.schema.json", raw)
+
+    def test_unit_lookup_matches_schema(self, client: MIDASClient):
+        raw = client.get_lookup_table("Unit").json()
+        self._assert_valid("midas-lookup-table-response.schema.json", raw)