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

python_midas-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check .
+      - run: ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      # Integration tests hit the live MIDAS API; CI runs unit tests only.
+      - run: pytest tests/ -v -m "not integration"

python_midas-1.0.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+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.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.
+
+### Changed
+
+- **Breaking: the per-interval value field is read from `Value` (capital V)** instead of v1.0's lowercase `value`. The CEC standardised the casing in v2.0; `ValueData.from_raw` reads `Value`.
+- **Breaking: `ValueData` interval boundaries are a zone-aware `period` tuple.** The four zone-naive fields `date_start`, `date_end`, `time_start`, and `time_end` (`datetime.date` / `datetime.time`) are **removed**; each interval is exposed as `period: tuple[pendulum.DateTime, pendulum.DateTime] | None` — a `(start, end)` pair of zone-aware moments. A bare wall-clock time with no zone is ambiguous, and in v2.0 the wire delivers `DateStart`/`TimeStart`/`DateEnd`/`TimeEnd` in UTC for *every* signal type (v1.0 delivered SGIP GHG and Flex Alert in Pacific Time — an upstream-provider passthrough bug the CEC fixed in v2.0). The pair is composed from the UTC wire date+time and **preserved in UTC** — the library never normalizes to a display zone. Need a wall-clock date or time? Convert an endpoint yourself: `period[0].in_tz("America/Los_Angeles").date()`. The original wire strings remain on `_raw`. (Mirrors `python-oa3`'s `IntervalPeriod.period`.)
+- **Breaking: datetime coercion is zone-aware `pendulum.DateTime`, preserving the wire zone.** Every coerced timestamp carries an honest timezone — `Z`-suffixed fields (`SystemTime_UTC`, `SignupCloseDate`) stay UTC, as does `LastUpdated`, which in v2.0 carries an explicit basic-format offset (`+0000`); `parse_instant` honours it (no Pacific-local shift). The library does not normalize to a single zone; consumers convert with `.in_tz(...)` as needed. This replaces the prior `_parse_datetime` that silently treated every naive field as UTC.
+- **Breaking: `rin_list` / `coerce_rin_list` peel the v2.0 keyed-object response.** v2.0 wraps the entry array in a single-keyed object — on the live API the key is **always `Rates`**, regardless of the requested `SignalType` (the `GHGEmissions`/`FlexAlerts`/`All` keys implied by early design notes do not appear on the wire). `coerce_rin_list(raw, signal_type)` peels the single value without switching on the key name and returns a uniform `list[RinListEntry]`; the new `RinListResponse` model validates the shape.
+- **Breaking: lookup tables return a keyed object.** v2.0 wraps lookup rows in `{table_name, data: [...]}` instead of v1.0's bare array. `lookup_table` / `coerce_lookup_table` peel `data`; the new `LookupTableResponse` model validates the shape. `LookupEntry` gains optional `payload_descriptor` and `unit_type` (extra columns the `Unit` table carries).
+- **Breaking: `SignalType` enum carries the v2.0 long-form wire labels.** `SignalType.RATES` is now `"Electricity Rates"` (was `"Rates"`); new members `GHG_EMISSIONS = "Greenhouse Gas Emissions"` and `FLEX_ALERT = "California Independent System Operator Flex Alert"`. v2.0 always populates the per-entry `SignalType` field (v1.0 returned `null` for GHG/Flex Alert entries); the old labels no longer map.
+- **Breaking: `RateType` enum tracks the v2.0 wire values, which differ by signal type.** Electricity rates return the short `Ratetype` UploadCode, so the enum now uses short codes (`TOU`, `CPP`, `RTP`, `VPP`, `DSR`, `V-D`, `C-D`, `R-D`, `T-D`) — was the long descriptions (`"Time of use"`, …). GHG returns the long Description `"Greenhouse Gas emissions"` (`RateType.GHG`) and Flex Alert returns `"Flex Alert"` (`RateType.FLEX_ALERT`); both are retained. Unknown values still pass through as plain strings.
+- **Breaking: `Unit` reports v2.0 GHG emissions in grams.** New `Unit.G_CO2_PER_KWH = "g/kWh CO2"` — values are **1000× larger** than v1.0's `kg/kWh CO2` for the same physical reading. `Unit.KG_CO2_PER_KWH` is retained for pre-migration historical-archive reads; `MIDASClient.ghg()` recognises both.
+- **Breaking: `get_historical_data` / `historical_data` use the path-param endpoint `/HistoricalData/{rate_id}`** (was the `?id=` query param), and reject a range longer than the v2.0 **6-month** max per call with `ValueError`. The Python signatures are unchanged.
+
+### Added
+
+- **`create_anonymous_client`** — an unauthenticated client for the v2.0 GET endpoints (no token acquired, no `Authorization` header sent). This is the default, supported access mode for this read-only consumer; `create_client` / `create_auto_client` remain for the utility upload (POST) path only.
+- **`src/midas/time.py`** — pendulum-based time module shared in spirit with `python-oa3`: the `PendulumDateTime` annotated Pydantic type (parses on input, serialises to ISO 8601 preserving the wire offset) plus `parse_instant` (zone-tagged fields, incl. `LastUpdated`), `parse_local` (attach a documented zone to a bare wall-clock string), and `parse_value_moment` (compose a UTC `ValueInformation` boundary). `MIDAS_ZONE = "America/Los_Angeles"` documents MIDAS's native administrative zone.
+- **`RinListResponse`** and **`LookupTableResponse`** entity models for the v2.0 keyed RIN-list and lookup-table responses, exported from `midas` and `midas.entities`.
+- **`RateType.MOER`** for the v2.0 unified SGIP GHG signal, plus the short electricity `Ratetype` codes (`VPP`, `DSR`, `V-D`, `C-D`, `R-D`, `T-D`).
+
+### Removed
+
+- **`get_holidays` / `holidays` / `coerce_holidays` and the `Holiday` model** — v2.0 retired the standalone `/Holiday` endpoint (absent from the CEC's published OpenAPI). Remove any holiday calls; the `Holiday` *day-type* value in rate schedules (`DayType.HOLIDAY`) is unaffected.
+- **`get_historical_list` / `historical_list` / `coerce_historical_list`** — v2.0 retires the `/HistoricalList` endpoint. Use `rin_list(signal_type=0)` for the full active RIN list.
+- The `Holiday` and `TimeZone` **lookup tables** are retired in v2.0 (`?LookupTable=Holiday` / `TimeZone` no longer return data).
+
+## [0.1.1] — 2026-03-20
+
+### Fixed
+
+- `RateInfo.id` accepts `null` for empty realtime responses (the live API returns an all-null `RateInfo` when a RIN has no current realtime datapoint).
+
+## [0.1.0] — 2026-03-20
+
+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.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/CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# Contributing to python-midas
+
+Thanks for your interest in contributing! This repo is a Python client library for the California Energy Commission's [MIDAS API](https://midasapi.energy.ca.gov/). It exposes a two-layer raw/coerced data model with Pydantic v2 entities, pendulum time types, and an httpx-based client. Unlike some sibling libraries it does **not** bundle an OpenAPI spec — endpoints are hand-written `httpx` calls, and the spec-level source of truth lives upstream in [`grid-coordination/midas-api-specs`](https://github.com/grid-coordination/midas-api-specs).
+
+## How to contribute
+
+### Discussions
+
+Use [Discussions](https://github.com/grid-coordination/python-midas/discussions) for:
+
+- Questions about how to use the library — clients, coercion, raw/coerced layering, time and timezone handling, signal-type helpers
+- API and design judgment calls — "should python-midas model X?" / "is this the right shape for Y?"
+- MIDAS API behavior gaps that affect python-midas — when the live API exposes something that doesn't fit the current entity shape and you want to scope what the library should do about it
+- Coordination with the upstream [`midas-api-specs`](https://github.com/grid-coordination/midas-api-specs) spec repo (whose `doc/` notes — RIN structure, datetime/timezone semantics, the v2.0 migration map — this library follows)
+- Sharing what you're building on top of python-midas
+
+Discussions are open-ended — a good place to think out loud or scope something before it becomes a concrete change. Aligned outcomes from a Discussion often turn into one or more Issues.
+
+### Issues
+
+Use [Issues](https://github.com/grid-coordination/python-midas/issues) for actionable changes:
+
+- Bugs in client construction, request building, response parsing, or coercion against the live MIDAS API
+- Coercion or schema gaps surfaced by real API responses (a field the library doesn't handle, or a value that breaks the coerced shape)
+- New endpoints or request parameters when MIDAS exposes them
+- Test failures or unexpected behavior with concrete repro steps
+- Documentation errors, unclear explanations, or stale prose in `README.md` or docstrings
+- Discussion outcomes that have alignment and a clear scope
+
+If you're not sure whether something is an Issue or a Discussion, start with a Discussion — we can convert it later.
+
+### Pull requests
+
+Pull requests are welcome.
+
+- For small fixes (typos, broken links, single-test corrections, single-coercion bug fixes), open a PR directly.
+- For substantive changes (new endpoints, new entity types, new coerced fields, time-handling changes), open a Discussion or Issue first so we can align on scope before you invest the effort.
+- All changes pass `pytest tests/ -m "not integration"` and `ruff check src/ tests/` / `ruff format --check src/ tests/` cleanly.
+- Match the existing tone and structure. The library composes HTTP client → raw response accessors → coerced Pydantic entities as roughly orthogonal layers; patches that fit cleanly into one layer without leaking concerns across them are the easiest to land.
+- One commit per logical change is fine; we don't require squash or any particular branch naming.
+
+## Development
+
+```bash
+pip install -e ".[dev]"                    # install with dev dependencies
+pytest tests/ -v -m "not integration"      # run the offline unit suite
+ruff check src/ tests/                      # lint
+ruff format --check src/ tests/             # format check (drop --check to apply)
+```
+
+### Time and timezones
+
+Every coerced datetime is a zone-aware `pendulum.DateTime`, and the library **preserves the honest wire zone** rather than normalizing to one display zone: `Z`-suffixed fields (`SystemTime_UTC`, `SignupCloseDate`) stay UTC; bare administrative fields (`LastUpdated`) are `America/Los_Angeles` local; `ValueData` interval boundaries are exposed as a `period` `(start, end)` tuple composed from the v2.0 UTC wire and kept in UTC. Convert to a zone of your choice yourself with `.in_tz(...)`. The parsing rules live in `src/midas/time.py`; the wire-level semantics they encode are documented in [`midas-api-specs/doc/datetime-and-timezone.md`](https://github.com/grid-coordination/midas-api-specs/blob/main/doc/datetime-and-timezone.md). When changing time handling, keep the "know the zone, convert it yourself" contract intact.
+
+### Integration tests
+
+Tests marked `integration` hit the live MIDAS API and require `MIDAS_USERNAME` / `MIDAS_PASSWORD`; they are excluded from CI and from the default offline run above. They target the **v2.0** API, which is live only after the CEC cutover on 2026-06-22 — running them before then (or without credentials) will fail or skip. Run them on release day to smoke-test against production:
+
+```bash
+MIDAS_USERNAME=... MIDAS_PASSWORD=... pytest tests/ -v -m integration
+```
+
+### Releases
+
+`python-midas` is published to PyPI by a GitHub Actions workflow ([`.github/workflows/publish.yml`](.github/workflows/publish.yml)) using PyPI's [Trusted Publisher](https://docs.pypi.org/trusted-publishers/) flow — no API tokens or personal credentials are involved. Pushing a `v*` tag triggers the workflow, which runs the offline test suite, builds the sdist + wheel, and uploads via OpenID Connect.
+
+To cut a release:
+
+1. Bump `version` in `pyproject.toml`.
+2. Move the `## [Unreleased]` entries in [`CHANGELOG.md`](CHANGELOG.md) under a `## [<version>] — <date>` heading (Added / Changed / Fixed / Removed). Update the reference links at the bottom.
+3. Commit on `main` (e.g. `Bump version to X.Y.Z`).
+4. Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z`.
+5. The `Publish to PyPI` workflow runs the test job, then the publish job in the `pypi` environment. Watch it on the Actions tab.
+
+The Trusted Publisher binding is `grid-coordination / python-midas / publish.yml / pypi`, configured at [pypi.org → Manage → Publishing](https://pypi.org/manage/account/publishing/). If a release fails with an OIDC error, verify the binding hasn't drifted (workflow filename, environment name, repo path).
+
+Versioning follows [SemVer](https://semver.org/). The 1.0.0 release tracks MIDAS v2.0 and is a v2-only, breaking release (see [`CHANGELOG.md`](CHANGELOG.md)).
+
+## Code of conduct
+
+Be respectful and constructive. We're a small project and appreciate everyone who takes the time to file an issue or send a PR.
+
+## Important notice
+
+This library is provided on an "as-is" basis. Updates and maintenance, including responses to issues filed on GitHub, will take place on an "as time and resources permit" basis. Library output (raw API responses, coerced entities) is best-effort against the live MIDAS API and the upstream [`midas-api-specs`](https://github.com/grid-coordination/midas-api-specs) documentation. This library is not authoritative for billing, dispatch, or grid operations — independent verification against the MIDAS API's actual responses is recommended for any consumer relying on these results for operational correctness.

python_midas-1.0.0/PKG-INFO

@@ -0,0 +1,417 @@
+Metadata-Version: 2.4
+Name: python-midas
+Version: 1.0.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 :: 5 - Production/Stable
+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
+
+[![PyPI version](https://img.shields.io/pypi/v/python-midas.svg)](https://pypi.org/project/python-midas/)
+[![Python versions](https://img.shields.io/pypi/pyversions/python-midas.svg)](https://pypi.org/project/python-midas/)
+[![CI](https://github.com/grid-coordination/python-midas/actions/workflows/ci.yml/badge.svg)](https://github.com/grid-coordination/python-midas/actions/workflows/ci.yml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+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 and a two-layer data model that preserves raw API responses alongside coerced Python-native types.
+
+> **This is a read-only consumer client.** python-midas is built for *consuming* MIDAS data. In v2.0 all public GET endpoints are unauthenticated, so you need **no credentials** — just `create_anonymous_client()`. The authenticated constructors (`create_client` / `create_auto_client`) exist only for utilities that *upload* rate data to the CEC; that path requires CEC-issued utility credentials and is not exercised by this project.
+
+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 python-midas
+```
+
+The distribution is named `python-midas` (the bare `midas` name on PyPI belongs to an unrelated gas-detector driver), but it imports as `midas`:
+
+```python
+import midas
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```python
+from midas import create_anonymous_client
+
+client = create_anonymous_client()   # v2.0 GETs need no credentials
+
+# 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:
+    start, end = v.period          # zone-aware (start, end) — UTC on the wire
+    print(f"  {start}–{end}: {v.value} {v.unit}")
+```
+
+## Authentication
+
+In MIDAS **v2.0**, all public GET endpoints (rate values, RIN list, lookup tables, historical data) are **unauthenticated** — use `create_anonymous_client` for read-only access:
+
+```python
+from midas import create_anonymous_client
+
+with create_anonymous_client() as client:
+    rins = client.rin_list()
+    rate = client.rate_values(rins[0].id)
+```
+
+Authentication exists only for **uploads** (LSE rate submission, POST) and requires CEC-issued utility credentials; it is **not exercised by this read-only consumer**. For completeness, the upload path is provided: MIDAS uses HTTP Basic authentication to acquire a short-lived bearer token (valid for 10 minutes), via `create_auto_client` (acquires a token and transparently refreshes it within a 30-second buffer), `create_client` (a single token), or the low-level `get_token` / `token_expired` helpers.
+
+```python
+from midas import create_auto_client, create_client, get_token, token_expired
+
+client = create_auto_client("username", "password")   # auto-refreshing (uploads)
+client = create_client("username", "password")        # single token (~10 min)
+
+token_info = get_token("username", "password")         # low-level
+# token_info = {"token": "...", "acquired_at": DateTime, "expires_at": DateTime}
+```
+
+## API Coverage
+
+The MIDAS API has a single multiplexed `/ValueData` endpoint that serves different response shapes depending on query parameters, plus a separate endpoint for historical data. All read 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_EMISSIONS`, or `SignalType.FLEX_ALERT` (v2.0 long-form wire labels)
+- `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 or raw string. The wire value is inconsistent across signal types in v2.0: electricity rates return the short Ratetype code (`TOU`, `CPP`, `RTP`, …) while GHG returns `Greenhouse Gas emissions` and Flex Alert returns `Flex Alert`
+- `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` — interval description (e.g. `"winter off peak"`)
+- `period` — `(start, end)` tuple of zone-aware `pendulum.DateTime` moments (or `None` when a boundary is absent). Composed from the v2.0 UTC wire date+time and kept in UTC; convert with `.in_tz(...)`. See [Time and timezones](#time-and-timezones).
+- `day_start`, `day_end` — `DayType` enum (Monday through Sunday, plus Holiday)
+- `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`. (v2.0 retired the `Holiday` and `TimeZone` lookup tables.)
+
+In v2.0 a lookup response is a keyed object `{table_name, data: [...]}`; the client peels `data` for you. Each `LookupEntry` has `code` and `description`, plus optional `payload_descriptor` and `unit_type` (the `Unit` table carries these extra columns).
+
+### Historical Data
+
+Query archived rate data for a RIN over a date range (v2.0 caps each call at a **6-month** range and takes the RIN as a path parameter):
+
+```python
+hist = client.historical_data("USCA-PGPG-ETOU-0000", "2023-01-01", "2023-06-30")
+```
+
+A range longer than six months raises `ValueError` — split it into multiple calls.
+
+> The v1.0 `historical_list` / `get_historical_list` methods are **removed** — v2.0 retires the `/HistoricalList` endpoint. For the full active RIN list use `client.rin_list(signal_type=0)`.
+
+## 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
+```
+
+## Time and timezones
+
+Every coerced datetime is a zone-aware `pendulum.DateTime` — Python's equivalent of Java's `ZonedDateTime` (it carries an IANA zone, not just a fixed offset, so it is DST-correct). The guiding principle, shared with [clj-midas](https://github.com/grid-coordination/clj-midas) and [python-oa3](https://github.com/grid-coordination/python-oa3): **you always know what zone a value is in, and you convert it yourself.** The library preserves the honest wire zone and never normalizes to a single display zone.
+
+MIDAS mixes two wire conventions and does not tag the bare ones; python-midas encodes the documented zone for each field (see [midas-api-specs/doc/datetime-and-timezone.md](https://github.com/grid-coordination/midas-api-specs/blob/main/doc/datetime-and-timezone.md)):
+
+| Field | Wire form (v2.0) | Coerced as |
+|-------|------------------|------------|
+| `system_time`, `signup_close` | `Z`-suffixed (UTC) | `pendulum.DateTime` in **UTC** — instant preserved |
+| `ValueData.period` (start, end) | bare `DateStart`/`TimeStart`/…, **UTC** in v2.0 | pair of `pendulum.DateTime` in **UTC** |
+| `last_updated` | UTC with basic-format offset (`+0000`) | `pendulum.DateTime` in **UTC** — instant preserved (absent on Flex Alert entries → `None`) |
+
+```python
+rate = client.rate_values("USCA-TSTS-TTOU-TEST")
+start, end = rate.values[0].period
+start                                       # 2026-05-01 07:00:00+00:00   (UTC, as delivered)
+start.in_tz("America/Los_Angeles")          # 2026-05-01 00:00:00-07:00   (you convert)
+start.in_tz("America/Los_Angeles").date()   # datetime.date(2026, 5, 1)   (wall-clock date)
+```
+
+In v2.0 (effective 2026-06-22) MIDAS delivers every `ValueInformation` date/time field in UTC for all signal types — fixing the v1.0 bug where SGIP GHG and Flex Alert timestamps arrived Pacific-local on the wire — and `LastUpdated` now carries an explicit `+0000` offset. The parsing rules live in `midas.time` (`parse_instant`, `parse_local`, `parse_value_moment`, and the `PendulumDateTime` Pydantic type).
+
+> The v1.0 zone-naive fields `date_start`, `date_end`, `time_start`, `time_end` (`datetime.date` / `datetime.time`) are **removed** in favour of `period`: a bare wall-clock time with no zone is ambiguous, whereas the `(start, end)` moments are self-describing. The exact wire strings remain on `_raw`.
+
+## 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  (v2.0 capitalises the key)
+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 in UTC (Z-suffixed wire field)
+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].period        # (DateTime, DateTime) — zone-aware (start, end)
+```
+
+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_historical_data("USCA-PGPG-ETOU-0000", "2023-01-01", "2023-06-30")
+```
+
+**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]
+rate = client.historical_data(rin, start, end)    # RateInfo (≤ 6-month range)
+```
+
+## 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_lookup_table
+
+rate = coerce_rate_info({"RateID": "...", "ValueInformation": [...]})
+# v2.0 wraps the RIN list under a single key (always "Rates"); coerce_rin_list peels it.
+rins = coerce_rin_list({"Rates": [{"RateID": "...", "SignalType": "Electricity Rates", ...}]})
+# v2.0 wraps lookup rows under {table_name, data: [...]}; coerce_lookup_table peels data.
+units = coerce_lookup_table({"table_name": "Unit", "data": [{"UploadCode": "...", ...}]})
+```
+
+Available: `coerce_rate_info`, `coerce_rin_list`, `coerce_lookup_table`.
+
+## 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          # "Electricity Rates"
+SignalType.GHG_EMISSIONS  # "Greenhouse Gas Emissions"
+SignalType.FLEX_ALERT     # "California Independent System Operator Flex Alert"
+
+# Electricity rates return the short Ratetype UploadCode in v2.0:
+RateType.TOU              # "TOU"
+RateType.CPP              # "CPP"
+RateType.RTP              # "RTP"
+# (also VPP, DSR, V-D, C-D, R-D, T-D)
+# GHG and Flex Alert return long Descriptions, not short codes:
+RateType.GHG              # "Greenhouse Gas emissions"
+RateType.FLEX_ALERT       # "Flex Alert"
+RateType.MOER             # "MOER"  (v2.0 unified SGIP GHG signal)
+
+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.G_CO2_PER_KWH        # "g/kWh CO2"   (v2.0 GHG — grams, 1000× the v1.0 kg value)
+Unit.KG_CO2_PER_KWH       # "kg/kWh CO2"  (historical-archive reads)
+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 |
+|----------|-------------|-------|
+| Zone-tagged datetime (`"…Z"`) | `pendulum.DateTime` | Instant preserved in UTC (`system_time`, `signup_close`) |
+| `LastUpdated` (`"…+0000"`) | `pendulum.DateTime` | UTC instant; explicit offset honoured |
+| `ValueInformation` date + time | `pendulum.DateTime` pair (`period`) | Composed as UTC in v2.0 — see [Time and timezones](#time-and-timezones) |
+| 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_anonymous_client
+
+with create_anonymous_client() 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_anonymous_client, create_client, create_auto_client
+    auth.py              # BearerAuth, BasicAuth, AutoTokenAuth, get_token (upload path)
+    enums.py             # SignalType, RateType, Unit, DayType
+    time.py              # pendulum parsing + PendulumDateTime Pydantic type
+    entities/
+        __init__.py      # Coercion dispatch functions
+        models.py        # Pydantic models: RateInfo, ValueData, RinListEntry, RinListResponse, LookupEntry, LookupTableResponse
+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 (anonymous, no credentials)
+```
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Lint
+ruff check src/ tests/
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor workflow and [CHANGELOG.md](CHANGELOG.md) for release history. python-midas `1.0.0` tracks the breaking MIDAS **v2.0** API (live 2026-06-22; v2-only — v1.0 support intentionally dropped) — see [doc/v2-migration.md](doc/v2-migration.md) for the v1.0→v2.0 upgrade guide.
+
+### 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` using an anonymous client — **no credentials required** (v2.0 GETs are unauthenticated):
+
+```bash
+pytest -m integration
+```
+
+Integration tests exercise every read endpoint (RIN list, rate values, lookup tables, historical data), all entity coercion paths against real response shapes, the v2.0 wire-shape corrections (keyed `Rates` RIN list, keyed `{table_name, data}` lookup tables, UTC `LastUpdated`, signal-type-dependent `RateType`), and the signal type helpers (GHG, Flex Alert detection). Pre-migration historical data may be absent during the v2.0 cutover week, so the historical test skips gracefully on a 404.
+
+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