tariffkit 0.2.2__tar.gz → 0.2.3__tar.gz

{tariffkit-0.2.2 → tariffkit-0.2.3}/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project are documented here. This project follows
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-08-17
+
+### Changed
+- Pacific Gas and Electric now has the unambiguous machine identifier
+  `pacific_gas_and_electric`, while Home Assistant and MQTT present `PG&E` or
+  the full company name. The separate `pge` identifier correctly means Portland
+  General Electric and is recognized but explicitly unsupported for pricing,
+  preventing it from ever selecting California tariff data.
+- Home Assistant now labels the export-minus-import calculation explicitly,
+  translates time-of-use states for display, and presents the forecast horizon
+  as **Rates Available Through**. Forecast metadata and a new **Rate Data
+  Status** entity are grouped under diagnostics, where PTO date, export lock
+  end, NBT vintage, tariff provenance, source, and quality flags explain the
+  active rates without crowding the primary price controls.
+
+### Fixed
+- The PyPI project page now loads the TariffKit banner from an absolute URL
+  instead of an unresolved repository-relative path.
+
 ## [0.2.2] - 2026-08-16
 
 ### Added
@@ -221,7 +240,8 @@ Initial release.
 - Holiday calendars are extracted per vintage from the source data rather than
   recomputed, because the vintage files disagree in far-future years.
 
-[Unreleased]: https://github.com/eman/tariffkit/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/eman/tariffkit/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/eman/tariffkit/releases/tag/v0.2.3
 [0.2.2]: https://github.com/eman/tariffkit/releases/tag/v0.2.2
 [0.2.1]: https://github.com/eman/tariffkit/releases/tag/v0.2.1
 [0.2.0]: https://github.com/eman/tariffkit/releases/tag/v0.2.0

{tariffkit-0.2.2 → tariffkit-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tariffkit
-Version: 0.2.2
+Version: 0.2.3
 Summary: Offline electricity tariff pricing, billing, and integration tools
 Project-URL: Homepage, https://github.com/eman/tariffkit
 Project-URL: Documentation, https://github.com/eman/tariffkit#documentation
@@ -44,7 +44,7 @@ Requires-Dist: uvicorn[standard]>=0.29; extra == 'web'
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="images/banner.svg" alt="TariffKit — electricity pricing, billing, and energy integrations" width="100%">
+  <img src="https://raw.githubusercontent.com/eman/tariffkit/main/images/banner.svg" alt="TariffKit — electricity pricing, billing, and energy integrations" width="100%">
 </p>
 
 # TariffKit

{tariffkit-0.2.2 → tariffkit-0.2.3}/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="images/banner.svg" alt="TariffKit — electricity pricing, billing, and energy integrations" width="100%">
+  <img src="https://raw.githubusercontent.com/eman/tariffkit/main/images/banner.svg" alt="TariffKit — electricity pricing, billing, and energy integrations" width="100%">
 </p>
 
 # TariffKit

{tariffkit-0.2.2 → tariffkit-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tariffkit"
-version = "0.2.2"
+version = "0.2.3"
 description = "Offline electricity tariff pricing, billing, and integration tools"
 readme = "README.md"
 license = "MIT"

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/__init__.py

@@ -25,6 +25,7 @@ from .models import (
     Season,
     Supplier,
     TouPeriod,
+    Utility,
 )
 from .timeutil import PACIFIC, DayType, now_pacific
 
@@ -47,6 +48,7 @@ __all__ = [
     "Supplier",
     "TariffKitError",
     "TouPeriod",
+    "Utility",
     "__version__",
     "now_pacific",
 ]

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/cca.py

@@ -15,6 +15,7 @@ from typing import Any
 
 from .data import versioned
 from .errors import ConfigError, DataError
+from .models import Utility
 
 
 @dataclass(frozen=True, slots=True)
@@ -115,7 +116,12 @@ def load_rate_card(provider: str, on: date) -> CcaRateCard:
         ) from exc
     if version.raw.get("schema") != 1:
         raise DataError(f"{provider}: unsupported rate card schema {version.raw.get('schema')}")
-    return CcaRateCard(provider=str(version.raw["provider"]), raw=version.raw)
+    raw = dict(version.raw)
+    try:
+        raw["utility"] = Utility(raw["utility"]).value
+    except (KeyError, ValueError) as exc:
+        raise DataError(f"{provider}: invalid utility identifier") from exc
+    return CcaRateCard(provider=str(raw["provider"]), raw=raw)
 
 
 def available_rate_cards() -> tuple[str, ...]:

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/config.py

@@ -11,7 +11,7 @@ from pathlib import Path
 from typing import Any, Literal
 
 from .errors import ConfigError
-from .models import Supplier
+from .models import Supplier, Utility
 
 AccPlusSegment = Literal["residential", "residential_low_income", "none"]
 Discount = Literal["none", "care", "fera"]
@@ -80,7 +80,7 @@ class CcaConfig:
 class Config:
     """Everything needed to price a kWh for one service agreement."""
 
-    utility: str = "PGE"
+    utility: Utility = Utility.PACIFIC_GAS_AND_ELECTRIC
     tariff: str = "E-ELEC"
     supplier: Supplier = Supplier.BUNDLED
 
@@ -117,6 +117,7 @@ class Config:
     nsc_rate: float | None = None
 
     def __post_init__(self) -> None:
+        object.__setattr__(self, "utility", Utility(self.utility))
         # Coerce the string forms of the enums. Supplier is a StrEnum, so a
         # plain "cca" compares equal to Supplier.CCA but is not it -- and every
         # branch that matters tests identity. Constructing Config directly with
@@ -195,7 +196,7 @@ class Config:
     def to_dict(self) -> dict[str, Any]:
         """A JSON-compatible representation suitable for API request bodies."""
         data: dict[str, Any] = {
-            "utility": self.utility,
+            "utility": self.utility.value,
             "tariff": self.tariff,
             "supplier": self.supplier.value,
             "interconnection_year": self.interconnection_year,

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/cca/mce/2023-01-01.toml

@@ -16,7 +16,7 @@
 schema = 1
 provider = "MCE"
 name = "Marin Clean Energy"
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 schedules = ["E-ELEC", "E-TOU-C", "EV2-A"]
 effective = "2023-01-01"
 currency = "USD/kWh"

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/cca/mce/2026-04-01.toml

@@ -49,7 +49,7 @@
 schema = 1
 provider = "MCE"
 name = "Marin Clean Energy"
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 #: MCE prices each PG&E schedule separately, so a rate card is keyed by schedule
 #: rather than tied to one. Slugs match the tariff data directories.
 schedules = ["E-ELEC", "E-TOU-C", "EV2-A"]

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/export/pge/acc_plus/2023-04-15.toml

@@ -1,4 +1,4 @@
-# ACC Plus adder, Pacific Gas and Electric Schedule NBT.
+# ACC Plus adder, Pacific Gas and Electric Company Schedule NBT.
 #
 # Source: https://www.pge.com/tariffs/assets/pdf/tariffbook/ELEC_SCHEDS_NBT.pdf
 #
@@ -18,13 +18,9 @@
 # closure.
 
 schema = 1
-# When this version of the adder table took force. The Net Billing Tariff opened
-# on 2023-04-15 and the five-year step-down has been published unchanged since,
-# so there is one vintage -- but it is dated, because a revision must be able to
-# sit beside it rather than overwrite it.
 effective = "2023-04-15"
 unit = "USD/kWh"
-source = "Pacific Gas and Electric Schedule NBT"
+source = "Pacific Gas and Electric Company Schedule NBT"
 
 [residential]
 2023 = 0.02200

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/nsc/pge.toml

@@ -1,4 +1,4 @@
-# Pacific Gas and Electric Net Surplus Compensation (NSC) rates, by true-up month.
+# Pacific Gas and Electric Company Net Surplus Compensation (NSC) rates, by true-up month.
 #
 # Source: https://www.pge.com/assets/pge/docs/clean-energy/solar/AB920-RateTable.pdf
 #
@@ -28,7 +28,7 @@
 # case rather than an edge one.
 
 schema = 1
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 currency = "USD/kWh"
 source_url = "https://www.pge.com/assets/pge/docs/clean-energy/solar/AB920-RateTable.pdf"
 decision = "D.11-06-016"

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/tariff/pge/eelec/2025-01-01.toml

@@ -18,7 +18,7 @@
 # makes a silent mis-parse essentially impossible.
 
 schema = 1
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 tariff = "E-ELEC"
 effective = "2025-01-01"
 advice_letter = "7469-E"

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/tariff/pge/eelec/2025-03-01.toml

@@ -17,7 +17,7 @@
 # makes a silent mis-parse essentially impossible.
 
 schema = 1
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 tariff = "E-ELEC"
 effective = "2025-03-01"
 advice_letter = "7516-E"

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/tariff/pge/eelec/2025-09-01.toml

@@ -17,7 +17,7 @@
 # makes a silent mis-parse essentially impossible.
 
 schema = 1
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 tariff = "E-ELEC"
 effective = "2025-09-01"
 advice_letter = "7684-E"

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/tariff/pge/eelec/2026-01-01.toml

@@ -18,7 +18,7 @@
 # makes a silent mis-parse essentially impossible.
 
 schema = 1
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 tariff = "E-ELEC"
 effective = "2026-01-01"
 advice_letter = "7797-E"

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/tariff/pge/eelec/2026-03-01.toml

@@ -1,4 +1,4 @@
-# Pacific Gas and Electric Schedule E-ELEC -- retail time-of-use rates.
+# Pacific Gas and Electric Company Schedule E-ELEC -- retail time-of-use rates.
 #
 # Source: https://www.pge.com/tariffs/assets/pdf/tariffbook/ELEC_SCHEDS_E-ELEC.pdf
 #
@@ -22,7 +22,7 @@
 # makes a silent mis-parse essentially impossible.
 
 schema = 1
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 tariff = "E-ELEC"
 effective = "2026-03-01"
 advice_letter = "7846-E"

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/tariff/pge/etouc/2025-01-01.toml

@@ -19,7 +19,7 @@
 # makes a silent mis-parse essentially impossible.
 
 schema = 1
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 tariff = "E-TOU-C"
 effective = "2025-01-01"
 advice_letter = "7469-E"

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/tariff/pge/etouc/2025-03-01.toml

@@ -18,7 +18,7 @@
 # makes a silent mis-parse essentially impossible.
 
 schema = 1
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 tariff = "E-TOU-C"
 effective = "2025-03-01"
 advice_letter = "7516-E"

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/tariff/pge/etouc/2025-09-01.toml

@@ -18,7 +18,7 @@
 # makes a silent mis-parse essentially impossible.
 
 schema = 1
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 tariff = "E-TOU-C"
 effective = "2025-09-01"
 advice_letter = "7684-E"

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/tariff/pge/etouc/2026-01-01.toml

@@ -19,7 +19,7 @@
 # makes a silent mis-parse essentially impossible.
 
 schema = 1
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 tariff = "E-TOU-C"
 effective = "2026-01-01"
 advice_letter = "7797-E"

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/tariff/pge/etouc/2026-03-01.toml

@@ -1,4 +1,4 @@
-# PG&E Schedule E-TOU-C -- retail time-of-use rates.
+# Pacific Gas and Electric Company Schedule E-TOU-C -- retail time-of-use rates.
 #
 # Source: https://www.pge.com/tariffs/assets/pdf/tariffbook/ELEC_SCHEDS_E-TOU-C.pdf
 #
@@ -26,7 +26,7 @@
 # makes a silent mis-parse essentially impossible.
 
 schema = 1
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 tariff = "E-TOU-C"
 effective = "2026-03-01"
 advice_letter = "7846-E"
@@ -193,8 +193,10 @@ drop_components = ["generation", "bundled_pcia"]
 2025 = -0.01011
 2026 = -0.01011
 
-# Schedule E-FFS franchise fee surcharge. A different schedule, so it is
-# carried forward rather than read from this sheet.
+# Franchise fee surcharge, which a CCA/DA customer pays and a bundled one
+# does not. Published in a separate schedule (E-FFS) and read from it,
+# because carrying it forward would let that schedule be reissued without
+# anything noticing -- it is live rate data on every CCA price.
 [cca.franchise_fee_vintages]
 2009 = 0.00064
 2010 = 0.00061

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/tariff/pge/ev2a/2025-01-01.toml

@@ -18,7 +18,7 @@
 # makes a silent mis-parse essentially impossible.
 
 schema = 1
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 tariff = "EV2-A"
 effective = "2025-01-01"
 advice_letter = "7469-E"

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/tariff/pge/ev2a/2025-03-01.toml

@@ -17,7 +17,7 @@
 # makes a silent mis-parse essentially impossible.
 
 schema = 1
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 tariff = "EV2-A"
 effective = "2025-03-01"
 advice_letter = "7516-E"

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/tariff/pge/ev2a/2025-09-01.toml

@@ -17,7 +17,7 @@
 # makes a silent mis-parse essentially impossible.
 
 schema = 1
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 tariff = "EV2-A"
 effective = "2025-09-01"
 advice_letter = "7684-E"

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/tariff/pge/ev2a/2026-01-01.toml

@@ -18,7 +18,7 @@
 # makes a silent mis-parse essentially impossible.
 
 schema = 1
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 tariff = "EV2-A"
 effective = "2026-01-01"
 advice_letter = "7797-E"

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/data/tariff/pge/ev2a/2026-03-01.toml

@@ -1,4 +1,4 @@
-# Pacific Gas and Electric Schedule EV2-A -- retail time-of-use rates.
+# Pacific Gas and Electric Company Schedule EV2-A -- retail time-of-use rates.
 #
 # Source: https://www.pge.com/tariffs/assets/pdf/tariffbook/ELEC_SCHEDS_EV2%20(Sch).pdf
 #
@@ -23,7 +23,7 @@
 # makes a silent mis-parse essentially impossible.
 
 schema = 1
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 tariff = "EV2-A"
 effective = "2026-03-01"
 advice_letter = "7846-E"

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/engine.py

@@ -5,8 +5,9 @@ from __future__ import annotations
 from datetime import UTC, datetime, timedelta
 
 from .config import Config
+from .errors import DataError
 from .export.nbt import NbtExportRates
-from .models import PriceCurve, PricePoint
+from .models import PriceCurve, PricePoint, Utility
 from .tariff.retail import RetailTariff
 from .timeutil import PACIFIC, hour_floor, now_pacific, to_pacific
 
@@ -21,6 +22,8 @@ class RateEngine:
 
     def __init__(self, config: Config | None = None) -> None:
         self.config = config or Config()
+        if self.config.utility is not Utility.PACIFIC_GAS_AND_ELECTRIC:
+            raise DataError(f"{self.config.utility.display_name} pricing is not supported")
         self.tariff = RetailTariff(self.config)
         self.export_rates = NbtExportRates(self.config)
 
@@ -69,7 +72,7 @@ class RateEngine:
         snapshot = self.tariff.snapshot_for(when)
         low, high = self.export_rates.covered_years
         return {
-            "utility": self.config.utility,
+            "utility": self.config.utility.value,
             "tariff": self.config.tariff,
             "supplier": str(self.config.supplier),
             "tariff_effective": snapshot.effective.isoformat(),
@@ -78,5 +81,6 @@ class RateEngine:
             "export_vintage": self.export_rates.vintage,
             "export_years": [low, high],
             "acc_plus": self.export_rates.acc_plus,
+            "pto_date": self.config.pto_date.isoformat() if self.config.pto_date else None,
             "lock_end": self.config.lock_end.isoformat() if self.config.lock_end else None,
         }

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/export/nbt.py

@@ -15,7 +15,7 @@ from typing import Any
 from ..config import FLOATING_VINTAGE, Config
 from ..data import read_data_json_gz, versioned
 from ..errors import ConfigError, DataError, OutOfRangeError
-from ..models import ExportPrice, Supplier
+from ..models import ExportPrice, Supplier, Utility
 from ..timeutil import MONTHS, DayType, day_type, export_hour
 
 #: Where a utility's ACC Plus adder table lives. Keyed by utility rather than
@@ -32,9 +32,10 @@ def _matrix(vintage: str) -> dict[str, Any]:
     return payload
 
 
-def _acc_plus_table(utility: str, on: date) -> dict[str, Any]:
-    relative = ACC_PLUS_DIR.format(utility=utility.lower())
-    return versioned.load(relative, on, label=f"{utility} ACC Plus").raw
+def _acc_plus_table(utility: Utility | str, on: date) -> dict[str, Any]:
+    utility_id = Utility(utility)
+    relative = ACC_PLUS_DIR.format(utility=utility_id.data_slug)
+    return versioned.load(relative, on, label=f"{utility_id.short_name} ACC Plus").raw
 
 
 class NbtExportRates:

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/models.py

@@ -28,6 +28,40 @@ class Supplier(StrEnum):
     CCA = "cca"
 
 
+class Utility(StrEnum):
+    """Stable utility identities used by profiles and API payloads."""
+
+    PACIFIC_GAS_AND_ELECTRIC = "pacific_gas_and_electric"
+    PORTLAND_GENERAL_ELECTRIC = "pge"
+
+    @property
+    def data_slug(self) -> str:
+        """Private filesystem key for this utility's vendored data."""
+        match self:
+            case Utility.PACIFIC_GAS_AND_ELECTRIC:
+                return "pge"
+            case Utility.PORTLAND_GENERAL_ELECTRIC:
+                return "portland_general_electric"
+
+    @property
+    def short_name(self) -> str:
+        """Recognizable user-facing abbreviation."""
+        match self:
+            case Utility.PACIFIC_GAS_AND_ELECTRIC:
+                return "PG&E"
+            case Utility.PORTLAND_GENERAL_ELECTRIC:
+                return "PGE"
+
+    @property
+    def display_name(self) -> str:
+        """Full user-facing company name."""
+        match self:
+            case Utility.PACIFIC_GAS_AND_ELECTRIC:
+                return "Pacific Gas and Electric Company"
+            case Utility.PORTLAND_GENERAL_ELECTRIC:
+                return "Portland General Electric"
+
+
 @dataclass(frozen=True, slots=True)
 class ImportPrice:
     """What a kWh drawn from the grid costs, marginally."""

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/mqtt/discovery.py

@@ -8,6 +8,8 @@ from __future__ import annotations
 
 from typing import Any
 
+from ..models import Utility
+
 DEVICE_ID = "tariffkit"
 
 #: (object_id, name, state topic suffix, icon)
@@ -19,10 +21,11 @@ SENSORS: tuple[tuple[str, str, str, str], ...] = (
 
 
 def _device(engine_info: dict[str, Any]) -> dict[str, Any]:
+    utility = Utility(engine_info.get("utility", Utility.PACIFIC_GAS_AND_ELECTRIC))
     return {
         "identifiers": [DEVICE_ID],
-        "name": "PG&E Rates",
-        "manufacturer": str(engine_info.get("utility", "PGE")),
+        "name": f"{utility.short_name} Rates",
+        "manufacturer": utility.display_name,
         "model": f"{engine_info.get('tariff', 'E-ELEC')} / {engine_info.get('export_vintage', '')}",
         "sw_version": _version(),
     }

{tariffkit-0.2.2 → tariffkit-0.2.3}/src/tariffkit/tariff/retail.py

@@ -28,7 +28,7 @@ from typing import Any
 from ..cca import load_rate_card
 from ..config import Config
 from ..errors import ConfigError, DataError
-from ..models import ImportPrice, Season, Supplier, TouPeriod
+from ..models import ImportPrice, Season, Supplier, TouPeriod, Utility
 
 TARIFF_DATA_ROOT = "tariff"
 
@@ -50,11 +50,11 @@ class TariffSnapshot:
 
 
 @lru_cache(maxsize=8)
-def _snapshots(utility: str, tariff: str) -> tuple[TariffSnapshot, ...]:
+def _snapshots(utility: Utility, tariff: str) -> tuple[TariffSnapshot, ...]:
     directory = (
         files("tariffkit.data")
         / TARIFF_DATA_ROOT
-        / utility.lower()
+        / utility.data_slug
         / tariff.lower().replace("-", "")
     )
     if not directory.is_dir():
@@ -64,19 +64,24 @@ def _snapshots(utility: str, tariff: str) -> tuple[TariffSnapshot, ...]:
         if not entry.name.endswith(".toml"):
             continue
         raw = tomllib.loads(entry.read_text(encoding="utf-8"))
+        try:
+            raw["utility"] = Utility(raw["utility"]).value
+        except (KeyError, ValueError) as exc:
+            raise DataError(f"{entry.name}: invalid utility identifier") from exc
         found.append(TariffSnapshot(date.fromisoformat(raw["effective"]), raw))
     if not found:
         raise DataError(f"no tariff snapshots for {utility}/{tariff}")
     return tuple(sorted(found, key=lambda s: s.effective))
 
 
-def load_snapshot(utility: str, tariff: str, on: date) -> TariffSnapshot:
+def load_snapshot(utility: Utility | str, tariff: str, on: date) -> TariffSnapshot:
     """The snapshot in force on ``on`` -- the latest one not in the future."""
-    snapshots = _snapshots(utility, tariff)
+    utility_id = Utility(utility)
+    snapshots = _snapshots(utility_id, tariff)
     applicable = [s for s in snapshots if s.effective <= on]
     if not applicable:
         raise DataError(
-            f"{utility}/{tariff}: no snapshot effective on or before {on}; "
+            f"{utility_id.value}/{tariff}: no snapshot effective on or before {on}; "
             f"earliest vendored is {snapshots[0].effective}"
         )
     return applicable[-1]

{tariffkit-0.2.2 → tariffkit-0.2.3}/tests/test_eelec.py

@@ -6,7 +6,7 @@ from datetime import date, datetime, timedelta
 
 import pytest
 
-from tariffkit import Config, Season, Supplier, TouPeriod
+from tariffkit import Config, Season, Supplier, TouPeriod, Utility
 from tariffkit.config import CcaConfig
 from tariffkit.errors import ConfigError
 from tariffkit.tariff.retail import RetailTariff, load_snapshot
@@ -38,7 +38,7 @@ def test_components_sum_to_published_total(season: str, period: str, published:
 
     This is the check that catches a mistyped digit in the vendored tariff.
     """
-    snapshot = load_snapshot("PGE", "E-ELEC", date(2026, 6, 1))
+    snapshot = load_snapshot(Utility.PACIFIC_GAS_AND_ELECTRIC, "E-ELEC", date(2026, 6, 1))
     energy = snapshot.raw["energy"][season][period]
     total = sum(energy.values()) + sum(snapshot.raw["adders"].values())
     assert total == pytest.approx(published, abs=5e-6)
@@ -125,10 +125,14 @@ def test_effective_dated_snapshot_selection() -> None:
     (Advice 7846-E, effective 2026-03-01), not from the later reissue of the
     totals page; see tools/regen_tariff.py::pick_effective.
     """
-    assert load_snapshot("PGE", "E-ELEC", date(2026, 7, 1)).effective == date(2026, 3, 1)
-    assert load_snapshot("PGE", "E-ELEC", date(2026, 4, 15)).effective == date(2026, 3, 1)
+    assert load_snapshot(
+        Utility.PACIFIC_GAS_AND_ELECTRIC, "E-ELEC", date(2026, 7, 1)
+    ).effective == date(2026, 3, 1)
+    assert load_snapshot(
+        Utility.PACIFIC_GAS_AND_ELECTRIC, "E-ELEC", date(2026, 4, 15)
+    ).effective == date(2026, 3, 1)
     with pytest.raises(Exception, match="no snapshot effective"):
-        load_snapshot("PGE", "E-ELEC", date(2020, 1, 1))
+        load_snapshot(Utility.PACIFIC_GAS_AND_ELECTRIC, "E-ELEC", date(2020, 1, 1))
 
 
 def test_base_services_charge_is_daily_and_excluded_from_energy_price(
@@ -212,7 +216,7 @@ class TestCca:
         pcia_vintage is documented as resolving both; this is what makes that
         true rather than true-for-now.
         """
-        cca = load_snapshot("PGE", "E-ELEC", date(2026, 6, 1)).raw["cca"]
+        cca = load_snapshot(Utility.PACIFIC_GAS_AND_ELECTRIC, "E-ELEC", date(2026, 6, 1)).raw["cca"]
         assert set(cca["pcia_vintages"]) == set(cca["franchise_fee_vintages"])
 
     @pytest.mark.parametrize(

{tariffkit-0.2.2 → tariffkit-0.2.3}/tests/test_engine.py

@@ -6,9 +6,9 @@ from datetime import UTC, date, datetime, timedelta
 
 import pytest
 
-from tariffkit import Config, RateEngine, Supplier
+from tariffkit import Config, RateEngine, Supplier, Utility
 from tariffkit.config import CcaConfig
-from tariffkit.errors import ConfigError, OutOfRangeError
+from tariffkit.errors import ConfigError, DataError, OutOfRangeError
 from tariffkit.timeutil import (
     PACIFIC,
     DayType,
@@ -278,6 +278,29 @@ class TestConfigValidation:
         assert config.cca is not None
         assert config.cca.name == "MCE"
 
+    def test_canonical_utility_identifier_is_emitted(self) -> None:
+        config = Config()
+
+        assert config.utility is Utility.PACIFIC_GAS_AND_ELECTRIC
+        assert config.to_dict()["utility"] == Utility.PACIFIC_GAS_AND_ELECTRIC.value
+        assert RateEngine(config).describe()["utility"] == Utility.PACIFIC_GAS_AND_ELECTRIC.value
+        assert (
+            RateEngine(config).tariff.snapshot_for(pt(2026, 8, 16, 9)).raw["utility"]
+            == Utility.PACIFIC_GAS_AND_ELECTRIC.value
+        )
+
+    def test_uppercase_pge_is_not_a_utility_identifier(self) -> None:
+        with pytest.raises(ConfigError, match="is not a valid Utility"):
+            Config.from_dict({"utility": "PGE"})
+
+    def test_lowercase_pge_identifies_portland_without_loading_california_rates(self) -> None:
+        config = Config.from_dict({"utility": "pge"})
+
+        assert config.utility is Utility.PORTLAND_GENERAL_ELECTRIC
+        assert config.to_dict()["utility"] == "pge"
+        with pytest.raises(DataError, match="Portland General Electric pricing is not supported"):
+            RateEngine(config)
+
     def test_from_dict_rejects_unknown_keys(self) -> None:
         with pytest.raises(ConfigError, match="unknown config keys"):
             Config.from_dict({"supplier": "bundled", "nonsense": 1})
@@ -306,6 +329,7 @@ def test_describe_reports_provenance(engine: RateEngine) -> None:
     assert info["export_vintage"] == "NBT26"
     assert info["tariff_effective"] == "2026-03-01"
     assert info["tariff_advice_letter"] == "7846-E"
+    assert info["pto_date"] == "2026-06-03"
     assert info["lock_end"] == "2035-06-02"
 
 

{tariffkit-0.2.2 → tariffkit-0.2.3}/tests/test_integrations.py

@@ -89,6 +89,10 @@ class TestDiscovery:
         self, payloads: list[tuple[str, dict[str, Any]]]
     ) -> None:
         assert {p["device"]["identifiers"][0] for _, p in payloads} == {"tariffkit"}
+        assert {p["device"]["manufacturer"] for _, p in payloads} == {
+            "Pacific Gas and Electric Company"
+        }
+        assert {p["device"]["name"] for _, p in payloads} == {"PG&E Rates"}
         assert all(p["availability_topic"] == "tariffkit/status" for _, p in payloads)
 
     def test_unique_ids_are_distinct(self, payloads: list[tuple[str, dict[str, Any]]]) -> None:

{tariffkit-0.2.2 → tariffkit-0.2.3}/tests/test_mce.py

@@ -10,7 +10,7 @@ from datetime import date, datetime
 
 import pytest
 
-from tariffkit import Config, RateEngine, Supplier
+from tariffkit import Config, RateEngine, Supplier, Utility
 from tariffkit.cca import load_rate_card
 from tariffkit.config import CcaConfig
 from tariffkit.errors import DataError
@@ -67,6 +67,10 @@ def test_cost_relief_credit_expires_at_the_end_of_2026() -> None:
     )
 
 
+def test_rate_card_uses_canonical_utility_identifier() -> None:
+    assert load_rate_card("mce", CARD_DATE).raw["utility"] == "pacific_gas_and_electric"
+
+
 @pytest.mark.parametrize("schedule", ["E-ELEC", "E-TOU-C", "EV2-A"])
 def test_mce_generation_is_at_parity_with_pge_today(schedule: str) -> None:
     """Parity is real but not guaranteed -- fail loudly if MCE diverges.
@@ -75,7 +79,7 @@ def test_mce_generation_is_at_parity_with_pge_today(schedule: str) -> None:
     a bug in the engine. Checked per schedule, since MCE prices each separately.
     """
     card = load_rate_card("mce", CARD_DATE)
-    snapshot = load_snapshot("PGE", schedule, date(2026, 6, 1))
+    snapshot = load_snapshot(Utility.PACIFIC_GAS_AND_ELECTRIC, schedule, date(2026, 6, 1))
     for season, periods in snapshot.raw["energy"].items():
         for period, components in periods.items():
             assert card.generation(schedule, season, period) == pytest.approx(

{tariffkit-0.2.2 → tariffkit-0.2.3}/tests/test_schedules.py

@@ -11,7 +11,7 @@ from datetime import date, datetime, timedelta
 
 import pytest
 
-from tariffkit import Config, RateEngine, Season, TouPeriod
+from tariffkit import Config, RateEngine, Season, TouPeriod, Utility
 from tariffkit.billing.engine import BillEngine
 from tariffkit.billing.models import Bill, BillingPeriod, IntervalReading
 from tariffkit.errors import ConfigError
@@ -26,7 +26,7 @@ def cells() -> list[tuple[str, str, str]]:
     """(tariff, season, period) for every rate the sheets publish."""
     found = []
     for tariff in SCHEDULES:
-        totals = load_snapshot("PGE", tariff, EFFECTIVE).raw["totals"]
+        totals = load_snapshot(Utility.PACIFIC_GAS_AND_ELECTRIC, tariff, EFFECTIVE).raw["totals"]
         for season, periods in totals.items():
             found.extend((tariff, season, period) for period in periods)
     return found
@@ -40,7 +40,7 @@ def test_components_sum_to_published_total(tariff: str, season: str, period: str
     On E-TOU-C the total is the over-baseline one, because [adders] carries the
     over-baseline Conservation Incentive Adjustment.
     """
-    raw = load_snapshot("PGE", tariff, EFFECTIVE).raw
+    raw = load_snapshot(Utility.PACIFIC_GAS_AND_ELECTRIC, tariff, EFFECTIVE).raw
     total = sum(raw["energy"][season][period].values()) + sum(raw["adders"].values())
     assert total == pytest.approx(raw["totals"][season][period], abs=5e-6)
 
@@ -49,7 +49,7 @@ def test_components_sum_to_published_total(tariff: str, season: str, period: str
 def test_every_published_cell_is_reachable_by_pricing(tariff: str) -> None:
     """Guards against a rate table nothing can select, e.g. a stray period."""
     engine = RateEngine(Config(tariff=tariff))
-    totals = load_snapshot("PGE", tariff, EFFECTIVE).raw["totals"]
+    totals = load_snapshot(Utility.PACIFIC_GAS_AND_ELECTRIC, tariff, EFFECTIVE).raw["totals"]
     priced = {
         (str(p.import_price.season), str(p.import_price.period))
         for month in (7, 12)
@@ -111,9 +111,14 @@ class TestSharedRiders:
 
     @pytest.mark.parametrize("table", ["pcia_vintages", "franchise_fee_vintages"])
     def test_all_schedules_agree(self, table: str) -> None:
-        reference = load_snapshot("PGE", "E-ELEC", EFFECTIVE).raw["cca"][table]
+        reference = load_snapshot(Utility.PACIFIC_GAS_AND_ELECTRIC, "E-ELEC", EFFECTIVE).raw["cca"][
+            table
+        ]
         for tariff in SCHEDULES:
-            assert load_snapshot("PGE", tariff, EFFECTIVE).raw["cca"][table] == reference, tariff
+            assert (
+                load_snapshot(Utility.PACIFIC_GAS_AND_ELECTRIC, tariff, EFFECTIVE).raw["cca"][table]
+                == reference
+            ), tariff
 
     @pytest.mark.parametrize("tariff", SCHEDULES)
     def test_base_services_charge_is_the_same_ab205_charge(self, tariff: str) -> None:
@@ -149,7 +154,7 @@ class TestBaseline:
 
     def test_credit_is_the_spread_between_the_two_cia_rates(self) -> None:
         """The bill prints one credit; the sheet implements it as two rates."""
-        raw = load_snapshot("PGE", "E-TOU-C", EFFECTIVE).raw["baseline"]
+        raw = load_snapshot(Utility.PACIFIC_GAS_AND_ELECTRIC, "E-TOU-C", EFFECTIVE).raw["baseline"]
         assert raw["over_rate"] - raw["within_rate"] == pytest.approx(raw["credit"])
         price = RateEngine(Config(tariff="E-TOU-C")).price_at(self.midday(12)).import_price
         assert price.baseline_credit == pytest.approx(0.08140)