utility-tariffs-lib 0.2.0__tar.gz → 0.3.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. {utility_tariffs_lib-0.2.0/utility_tariffs_lib.egg-info → utility_tariffs_lib-0.3.1}/PKG-INFO +1 -1
  2. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/README.md +33 -0
  3. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/__init__.py +2 -0
  4. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/definition.py +26 -1
  5. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/definition_parse.py +55 -4
  6. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/engine.py +19 -1
  7. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/period_bill.py +6 -2
  8. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/price_curve.py +20 -3
  9. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/price_timeline.py +11 -4
  10. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariffranking/search.py +6 -3
  11. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariffstore/aclient.py +21 -3
  12. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariffstore/price_client.py +24 -7
  13. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariffstore/price_rules.py +14 -2
  14. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariffstore/prices.py +3 -2
  15. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariffstore/schema.py +40 -0
  16. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/pyproject.toml +1 -1
  17. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_async_client.py +18 -0
  18. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_price_client.py +42 -1
  19. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_prices.py +12 -6
  20. utility_tariffs_lib-0.3.1/tests/test_prices_bord_gais.py +89 -0
  21. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_schema.py +29 -0
  22. utility_tariffs_lib-0.3.1/tests/test_sources_at.py +65 -0
  23. utility_tariffs_lib-0.3.1/tests/test_sources_bord_gais.py +207 -0
  24. utility_tariffs_lib-0.3.1/tests/test_sources_br.py +55 -0
  25. utility_tariffs_lib-0.3.1/tests/test_sources_ca_manitoba.py +43 -0
  26. utility_tariffs_lib-0.3.1/tests/test_sources_ca_nb.py +42 -0
  27. utility_tariffs_lib-0.3.1/tests/test_sources_ch.py +103 -0
  28. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_sources_ie.py +88 -0
  29. utility_tariffs_lib-0.3.1/tests/test_sources_in.py +125 -0
  30. utility_tariffs_lib-0.3.1/tests/test_sources_sg.py +48 -0
  31. utility_tariffs_lib-0.3.1/tests/test_sources_zm.py +55 -0
  32. utility_tariffs_lib-0.3.1/tests/test_status.py +80 -0
  33. utility_tariffs_lib-0.3.1/tests/test_status_docs.py +117 -0
  34. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_sync_core.py +12 -0
  35. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_sync_run.py +30 -0
  36. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_tariffs_through_lib.py +47 -8
  37. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1/utility_tariffs_lib.egg-info}/PKG-INFO +1 -1
  38. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/utility_tariffs_lib.egg-info/SOURCES.txt +12 -0
  39. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/LICENSE +0 -0
  40. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/README.md +0 -0
  41. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/__init__.py +0 -0
  42. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/py.typed +0 -0
  43. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/accumulator.py +0 -0
  44. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/bands.py +0 -0
  45. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/bill_days.py +0 -0
  46. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/billing.py +0 -0
  47. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/compile.py +0 -0
  48. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/config.py +0 -0
  49. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/defaults.py +0 -0
  50. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/definition_savings.py +0 -0
  51. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/demand.py +0 -0
  52. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/index.py +0 -0
  53. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/periods.py +0 -0
  54. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/price_series.py +0 -0
  55. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/price_stats.py +0 -0
  56. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/reprice.py +0 -0
  57. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/savings.py +0 -0
  58. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/slot_history.py +0 -0
  59. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/slots.py +0 -0
  60. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/stored_energy.py +0 -0
  61. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariff/windows.py +0 -0
  62. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariffranking/__init__.py +0 -0
  63. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariffstore/__init__.py +0 -0
  64. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariffstore/client.py +0 -0
  65. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariffstore/compile.py +0 -0
  66. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariffstore/core.py +0 -0
  67. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariffstore/index.py +0 -0
  68. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/tariffstore/layout.py +0 -0
  69. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/timeutil/__init__.py +0 -0
  70. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/lib/timeutil/real_time.py +0 -0
  71. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/setup.cfg +0 -0
  72. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_build.py +0 -0
  73. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_client.py +0 -0
  74. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_compile.py +0 -0
  75. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_eia861_map.py +0 -0
  76. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_end_to_end.py +0 -0
  77. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_index.py +0 -0
  78. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_lib_release_notes.py +0 -0
  79. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_packaging.py +0 -0
  80. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_price_format.py +0 -0
  81. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_prices_comed.py +0 -0
  82. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_prices_energinet.py +0 -0
  83. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_prices_energy_charts.py +0 -0
  84. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_prices_energyzero.py +0 -0
  85. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_prices_runner.py +0 -0
  86. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_repo_rules.py +0 -0
  87. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_sources_dk.py +0 -0
  88. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_sources_electric_ireland.py +0 -0
  89. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_sources_gb.py +0 -0
  90. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_sources_hq.py +0 -0
  91. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_sources_other.py +0 -0
  92. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_sources_pt.py +0 -0
  93. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_sources_us.py +0 -0
  94. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_stored_tariffs.py +0 -0
  95. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/tests/test_urdb_convert.py +0 -0
  96. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/utility_tariffs_lib.egg-info/dependency_links.txt +0 -0
  97. {utility_tariffs_lib-0.2.0 → utility_tariffs_lib-0.3.1}/utility_tariffs_lib.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: utility-tariffs-lib
3
- Version: 0.2.0
3
+ Version: 0.3.1
4
4
  Summary: Tariff model, bill engine, price series, store client and plan ranking
5
5
  Author: macuistin
6
6
  License-Expression: MIT
@@ -1,5 +1,15 @@
1
1
  # Tariff prices
2
2
 
3
+ > **Note on the data.** The tariffs here are gathered by the methods described in this
4
+ > repository, and each source has its own way of being read. Some sources will need updating over
5
+ > time and may change significantly. We will try to keep on top of as many as we can. The list is
6
+ > not exhaustive, because not every tariff is easy to gather. We will try to add more over time.
7
+ >
8
+ > **No manually entered tariffs.** A tariff typed in by hand goes out of date without notice, so
9
+ > this store holds only tariffs that a source reads from a published page, file or feed. If you know
10
+ > a place that publishes tariffs, [suggest a source](../../issues/new?template=suggestion.md). Feedback
11
+ > is welcome there too.
12
+
3
13
  Open, versioned electricity tariff definitions, an index to find them by country, provider and
4
14
  tariff, and a small library that fetches one, checks it and hands it to a bill engine. Each tariff
5
15
  is a JSON document. No tariff contains code or formulas.
@@ -69,6 +79,29 @@ mine = {"name": "My tariff", "effective_from": "2026-01-01",
69
79
  definition = store.custom_definition("IE", mine, date.today())
70
80
  ```
71
81
 
82
+ ## How tariffs are kept current
83
+
84
+ Nothing is typed in again by hand once a source is added. The sources are read on a schedule by
85
+ plain Python on a GitHub runner, with no AI and no private machine:
86
+
87
+ | What | When | Result |
88
+ | --- | --- | --- |
89
+ | Supplier and regulator sources (`sync.yml`) | Mondays 05:17 UTC | One pull request when a price changed. A person reviews and merges it |
90
+ | US plans (`sync-us.yml`) | The 3rd of each month, 04:43 UTC | One pull request with the plans in force |
91
+ | Dynamic price feeds (`prices.yml`) | Daily at 06:17, 15:17 and 17:17 UTC | New complete days committed to the `prices` branch. A day is rewritten only when its prices change |
92
+
93
+ A source that cannot be read opens an issue labelled `sync-failed` and does not stop the others.
94
+ The store is synced whether or not any integration is released. Clients read the files as they
95
+ stand, so an older client sees new prices without an update.
96
+ A price change is a new numbered revision, never an edit of a published one.
97
+
98
+ Each weekly run also records when every source was read, on its own `status` branch (the file
99
+ `sources.json`), so `main` holds no timestamps and a quiet week needs no pull request. For each
100
+ source it keeps the time of the last attempt, the last successful read, the last time it wrote a
101
+ new tariff or revision, and whether the last attempt worked. A failed source keeps its earlier
102
+ good times. The format is in `docs/format.md`. The monthly US sync and the price feeds are not
103
+ recorded there yet: a feed's newest day is already visible in its own index.
104
+
72
105
  ## Working on it
73
106
 
74
107
  python3 -m scripts.build # rewrite the indexes after editing a tariff or a country block
@@ -13,6 +13,7 @@ from .engine import (
13
13
  BillInputs,
14
14
  CheckFailed,
15
15
  Line,
16
+ MissingLoad,
16
17
  MissingPeak,
17
18
  MissingSeries,
18
19
  PricedBill,
@@ -100,6 +101,7 @@ __all__ = [
100
101
  "BillInputs",
101
102
  "CheckFailed",
102
103
  "Line",
104
+ "MissingLoad",
103
105
  "MissingPeak",
104
106
  "MissingPrice",
105
107
  "MissingSeries",
@@ -220,6 +220,30 @@ class Demand:
220
220
  rounding: NodeRounding
221
221
 
222
222
 
223
+ @dataclass(frozen=True)
224
+ class LoadBand:
225
+ """One row of a connected load charge: the price per kW for a load up to *upto_kw*."""
226
+
227
+ upto_kw: Decimal | None # included. None for the last band, which has no top
228
+ price: Decimal # per kW
229
+
230
+
231
+ @dataclass(frozen=True)
232
+ class ConnectedLoad:
233
+ """A charge on the load a customer is connected for, in kW, such as a sanctioned load.
234
+
235
+ The load is not measured by the meter, so the caller gives it for *load* in `BillInputs`. The
236
+ band the load falls in sets one price, and that price applies to every kW (the whole load, not
237
+ each slice of it). A load below *min_kw* is billed as *min_kw*.
238
+ """
239
+
240
+ load: str # the name the load is given under, in `BillInputs` and in a check
241
+ bands: tuple[LoadBand, ...] # from the lowest load, the last without a top
242
+ per: str # "period": once for the bill, or "month": for each month of it
243
+ min_kw: Decimal # the least load billed, 0 for none
244
+ rounding: NodeRounding
245
+
246
+
223
247
  @dataclass(frozen=True)
224
248
  class Bound:
225
249
  """Wraps one node and sets a floor (`minimum`) or a cap (`maximum`) on its amount.
@@ -266,7 +290,7 @@ class Sum:
266
290
 
267
291
  Node = (
268
292
  EnergyByBand | SeriesEnergy | TieredEnergy | ExportCredit | PerDay | PerPeriod | PerKwh
269
- | Demand | Bound | Adjust | Tax | Sum
293
+ | Demand | ConnectedLoad | Bound | Adjust | Tax | Sum
270
294
  )
271
295
 
272
296
 
@@ -279,6 +303,7 @@ class Check:
279
303
  export_kwh: Decimal | Mapping[str, Decimal] # one total, or the kWh in each export band
280
304
  expected_total: Decimal
281
305
  peak_kw: Mapping[str, Decimal] = field(default_factory=dict) # kW by demand window
306
+ load_kw: Mapping[str, Decimal] = field(default_factory=dict) # connected kW by load name
282
307
 
283
308
 
284
309
  @dataclass(frozen=True)
@@ -36,6 +36,7 @@ from .definition import (
36
36
  Block,
37
37
  Bound,
38
38
  Check,
39
+ ConnectedLoad,
39
40
  DefinitionError,
40
41
  Demand,
41
42
  EnergyByBand,
@@ -43,6 +44,7 @@ from .definition import (
43
44
  ExportPrices,
44
45
  ImportPrices,
45
46
  InputSpec,
47
+ LoadBand,
46
48
  Node,
47
49
  NodeRounding,
48
50
  PerDay,
@@ -122,7 +124,8 @@ def parse_definition(data: object) -> TariffDefinition:
122
124
  import_prices, export_prices = _prices(doc)
123
125
  period, total = _bill(doc.child("bill"), inputs)
124
126
  _check_bands(total, _names(import_prices))
125
- checks = _checks(doc, import_prices, export_prices, set(demand_windows(total)))
127
+ named = (set(demand_windows(total)), connected_loads(total))
128
+ checks = _checks(doc, import_prices, export_prices, named)
126
129
  complete = doc.choice("completeness", ("complete", "partial")) == "complete"
127
130
  if complete and not checks:
128
131
  raise DefinitionError("completeness", "complete needs at least one entry in checks")
@@ -553,6 +556,12 @@ def demand_windows(total: Node) -> dict[str, Zone]:
553
556
  return windows
554
557
 
555
558
 
559
+ def connected_loads(total: Node) -> set[str]:
560
+ """The names of the connected loads a bill tree uses."""
561
+ nodes = (node for node, _ in _children_of(total, "bill.total"))
562
+ return {node.load for node in nodes if isinstance(node, ConnectedLoad)}
563
+
564
+
556
565
  def _blocks(fields: Fields) -> dict[str, Block]:
557
566
  blocks: list[tuple[str, Block]] = []
558
567
  for name, _ in fields.items():
@@ -647,6 +656,38 @@ def _hours(fields: Fields) -> tuple[time, time]:
647
656
  return start, end
648
657
 
649
658
 
659
+ def _load_bands(fields: Fields) -> tuple[LoadBand, ...]:
660
+ rows: list[LoadBand] = []
661
+ for name, _ in fields.items():
662
+ if not _NODE_NAME.match(name):
663
+ raise DefinitionError(fields.at(name), "is not a valid name")
664
+ row = fields.child(name)
665
+ row.only(required=("price",), optional=("upto_kw",))
666
+ top = row.money("upto_kw") if row.has("upto_kw") else None
667
+ rows.append(LoadBand(top, row.money("price")))
668
+ if not rows:
669
+ raise DefinitionError(fields.path, "needs at least one band")
670
+ rows.sort(key=lambda band: (band.upto_kw is None, band.upto_kw or Decimal(0)))
671
+ tops = [band.upto_kw for band in rows]
672
+ if tops[-1] is not None or None in tops[:-1] or len(set(tops)) != len(tops) or (
673
+ tops[0] is not None and tops[0] <= 0
674
+ ):
675
+ raise DefinitionError(
676
+ fields.path, "needs rising tops above 0 and a last band with no upto_kw"
677
+ )
678
+ return tuple(rows)
679
+
680
+
681
+ def _connected_load(fields: Fields, depth: int) -> Node:
682
+ fields.only(required=("kind", "load", "bands"), optional=("per", "min_kw", "round"))
683
+ name = fields.text("load")
684
+ if not _NODE_NAME.match(name):
685
+ raise DefinitionError(fields.at("load"), "must be a lower case name")
686
+ per = fields.choice("per", _PER) if fields.has("per") else "month"
687
+ least = fields.money("min_kw") if fields.has("min_kw") else Decimal(0)
688
+ return ConnectedLoad(name, _load_bands(fields.child("bands")), per, least, _rounding(fields))
689
+
690
+
650
691
  def _bound(kind: str) -> Callable[[Fields, int], Node]:
651
692
  def parse(fields: Fields, depth: int) -> Node:
652
693
  fields.only(required=("kind", "amount", "of"), optional=("per", "round"))
@@ -695,6 +736,7 @@ _NODE_PARSERS: dict[str, Callable[[Fields, int], Node]] = {
695
736
  "per_day": _per_day,
696
737
  "per_kwh": _per_kwh,
697
738
  "demand": _demand,
739
+ "connected_load": _connected_load,
698
740
  "per_period": _per_period,
699
741
  "minimum": _bound("minimum"),
700
742
  "maximum": _bound("maximum"),
@@ -705,11 +747,12 @@ _NODE_PARSERS: dict[str, Callable[[Fields, int], Node]] = {
705
747
 
706
748
 
707
749
  def _checks(
708
- doc: Fields, import_prices: ImportPrices, export_prices: ExportPrices, windows: Collection[str]
750
+ doc: Fields, import_prices: ImportPrices, export_prices: ExportPrices,
751
+ named: tuple[Collection[str], Collection[str]],
709
752
  ) -> dict[str, Check]:
710
753
  if not doc.has("checks"):
711
754
  return {}
712
- bands = _Bands(_names(import_prices), _names(export_prices), windows)
755
+ bands = _Bands(_names(import_prices), _names(export_prices), named[0], named[1])
713
756
  fields = doc.child("checks")
714
757
  checks: dict[str, Check] = {}
715
758
  for name, _ in fields.items():
@@ -723,6 +766,7 @@ class _Bands(NamedTuple):
723
766
  imported: Collection[str]
724
767
  exported: Collection[str]
725
768
  windows: Collection[str]
769
+ loads: Collection[str]
726
770
 
727
771
 
728
772
  def _names(prices: ImportPrices | ExportPrices) -> set[str]:
@@ -732,7 +776,7 @@ def _names(prices: ImportPrices | ExportPrices) -> set[str]:
732
776
  def _check(fields: Fields, bands: _Bands) -> Check:
733
777
  fields.only(
734
778
  required=("period_days", "import_kwh_by_band", "export_kwh", "expected_total"),
735
- optional=("peak_kw",),
779
+ optional=("peak_kw", "load_kw"),
736
780
  )
737
781
  # A plain export figure is paid at the base export price. An object names the bands.
738
782
  export: Decimal | dict[str, Decimal]
@@ -747,6 +791,7 @@ def _check(fields: Fields, bands: _Bands) -> Check:
747
791
  export_kwh=export,
748
792
  expected_total=fields.signed("expected_total"),
749
793
  peak_kw=_peaks(fields, bands),
794
+ load_kw=_loads(fields, bands),
750
795
  )
751
796
 
752
797
 
@@ -756,6 +801,12 @@ def _peaks(fields: Fields, bands: _Bands) -> dict[str, Decimal]:
756
801
  return _kwh_by_band(fields.child("peak_kw"), bands.windows, "a demand window")
757
802
 
758
803
 
804
+ def _loads(fields: Fields, bands: _Bands) -> dict[str, Decimal]:
805
+ if not fields.has("load_kw"):
806
+ return {}
807
+ return _kwh_by_band(fields.child("load_kw"), bands.loads, "a connected load")
808
+
809
+
759
810
  def _kwh_by_band(by_band: Fields, bands: Collection[str], what: str) -> dict[str, Decimal]:
760
811
  kwh: dict[str, Decimal] = {}
761
812
  for band, _ in by_band.items():
@@ -20,6 +20,7 @@ from .definition import (
20
20
  Adjust,
21
21
  Block,
22
22
  Bound,
23
+ ConnectedLoad,
23
24
  Demand,
24
25
  EnergyByBand,
25
26
  ExportCredit,
@@ -47,6 +48,10 @@ class MissingPeak(ValueError):
47
48
  """A bill has a demand charge and no peak kW was given for its window."""
48
49
 
49
50
 
51
+ class MissingLoad(ValueError):
52
+ """A bill has a connected load charge and no load in kW was given for its name."""
53
+
54
+
50
55
  class MissingSeries(ValueError):
51
56
  """A bill has a series energy node and no cost was given for its series."""
52
57
 
@@ -65,6 +70,9 @@ class BillInputs:
65
70
  # The highest half-hour kW in each demand window of the bill. A window the tree uses and this
66
71
  # leaves out is refused, never priced as zero.
67
72
  peak_kw: Mapping[str, Decimal] = field(default_factory=dict)
73
+ # The kW a customer is connected for, by the name a connected load node gives it. A load the
74
+ # tree uses and this leaves out is refused, never priced as zero.
75
+ load_kw: Mapping[str, Decimal] = field(default_factory=dict)
68
76
  # The cost of the import kWh under each price series the tree names, from `series_cost`. A
69
77
  # series the tree uses and this leaves out is refused, never priced as zero.
70
78
  import_cost_by_series: Mapping[str, Decimal] = field(default_factory=dict)
@@ -102,7 +110,7 @@ def verify_checks(definition: TariffDefinition) -> None:
102
110
  for name, check in definition.checks.items():
103
111
  inputs = BillInputs(
104
112
  check.period_days, check.period_days, check.import_kwh_by_band, check.export_kwh,
105
- peak_kw=check.peak_kw,
113
+ peak_kw=check.peak_kw, load_kw=check.load_kw,
106
114
  )
107
115
  total = price_bill(definition, inputs).total
108
116
  if total != check.expected_total:
@@ -177,6 +185,8 @@ class _Pricer:
177
185
  return self._per_kwh(node)
178
186
  if isinstance(node, Demand):
179
187
  return self._demand(node)
188
+ if isinstance(node, ConnectedLoad):
189
+ return self._connected_load(node)
180
190
  if isinstance(node, PerPeriod):
181
191
  return self._per_period(node)
182
192
  return None
@@ -255,6 +265,14 @@ class _Pricer:
255
265
  amount = node.price * self._inputs.peak_kw[node.window] * months
256
266
  return Line("demand", self._round(amount, node.rounding))
257
267
 
268
+ def _connected_load(self, node: ConnectedLoad) -> Line:
269
+ if node.load not in self._inputs.load_kw:
270
+ raise MissingLoad(f"no load in kW was given for {node.load!r}")
271
+ kw = max(self._inputs.load_kw[node.load], node.min_kw)
272
+ band = next((b for b in node.bands if b.upto_kw is None or kw <= b.upto_kw), node.bands[-1])
273
+ months = Decimal(self._months) if node.per == "month" else Decimal(1)
274
+ return Line("connected_load", self._round(band.price * kw * months, node.rounding))
275
+
258
276
  def _per_period(self, node: PerPeriod) -> Line:
259
277
  amount = node.amount * self._months if node.per == "month" else node.amount
260
278
  if node.share == "days_in_period":
@@ -13,7 +13,7 @@ from __future__ import annotations
13
13
 
14
14
  import calendar
15
15
  from collections.abc import Callable, Mapping
16
- from dataclasses import dataclass
16
+ from dataclasses import dataclass, field
17
17
  from datetime import date
18
18
  from decimal import Decimal
19
19
 
@@ -32,6 +32,8 @@ class PeriodRules:
32
32
  months: int | None = None # calendar months in one bill period
33
33
  start_month: int | None = None # a month a period starts in
34
34
  is_holiday: Callable[[date], bool] = no_holidays
35
+ # The kW the customer is connected for, by name, for a tariff with a connected load charge.
36
+ load_kw: Mapping[str, Decimal] = field(default_factory=dict)
35
37
 
36
38
 
37
39
  @dataclass(frozen=True)
@@ -111,7 +113,9 @@ def price_period(
111
113
  else:
112
114
  export = _decimal(sum(day.total("export") for day in days))
113
115
  length = (through - first).days + 1
114
- inputs = BillInputs(length, (following - first).days, bands, export, months)
116
+ inputs = BillInputs(
117
+ length, (following - first).days, bands, export, months, load_kw=rules.load_kw
118
+ )
115
119
  return PeriodBill(
116
120
  first_day=first,
117
121
  next_first_day=following,
@@ -22,6 +22,7 @@ from decimal import Decimal
22
22
  from .bands import band_at, export_band_at, no_holidays
23
23
  from .defaults import SLOT_SECONDS
24
24
  from .definition import ExportPrices, ImportPrices, TariffDefinition
25
+ from .definition_parse import connected_loads, demand_windows
25
26
  from .engine import BillInputs, price_bill
26
27
  from .price_series import series_names
27
28
 
@@ -99,14 +100,30 @@ def price_curve(
99
100
  return tuple(slots)
100
101
 
101
102
 
103
+ def unit_inputs(
104
+ definition: TariffDefinition,
105
+ imported: Mapping[str, Decimal],
106
+ exported: Decimal | Mapping[str, Decimal],
107
+ cost_by_series: Mapping[str, Decimal] | None = None,
108
+ ) -> BillInputs:
109
+ """Inputs for a bill used only to take a difference, so a charge that does not follow the
110
+ energy cancels. A demand window and a connected load are given zero kW: they are the same in
111
+ both bills and so are not part of any price."""
112
+ zero = {name: Decimal(0) for name in series_names(definition)}
113
+ return BillInputs(
114
+ _DAYS, _DAYS, imported, exported,
115
+ import_cost_by_series=zero if cost_by_series is None else cost_by_series,
116
+ peak_kw=dict.fromkeys(demand_windows(definition.total), Decimal(0)),
117
+ load_kw=dict.fromkeys(connected_loads(definition.total), Decimal(0)),
118
+ )
119
+
120
+
102
121
  def _bill(
103
122
  definition: TariffDefinition,
104
123
  imported: Mapping[str, Decimal],
105
124
  exported: Decimal | Mapping[str, Decimal],
106
125
  ) -> Decimal:
107
- zero = {name: Decimal(0) for name in series_names(definition)}
108
- inputs = BillInputs(_DAYS, _DAYS, imported, exported, import_cost_by_series=zero)
109
- return price_bill(definition, inputs).total
126
+ return price_bill(definition, unit_inputs(definition, imported, exported)).total
110
127
 
111
128
 
112
129
  def _export(definition: TariffDefinition, name: str) -> Decimal | Mapping[str, Decimal]:
@@ -20,8 +20,15 @@ from decimal import Decimal
20
20
 
21
21
  from .bands import band_at, export_band_at, no_holidays
22
22
  from .definition import TariffDefinition
23
- from .engine import BillInputs, price_bill
24
- from .price_curve import _STEP, MarginalPrices, PriceSlot, marginal_prices, price_curve
23
+ from .engine import price_bill
24
+ from .price_curve import (
25
+ _STEP,
26
+ MarginalPrices,
27
+ PriceSlot,
28
+ marginal_prices,
29
+ price_curve,
30
+ unit_inputs,
31
+ )
25
32
  from .price_series import PriceSeries, series_names
26
33
 
27
34
 
@@ -41,9 +48,9 @@ def series_factor(definition: TariffDefinition, name: str) -> Decimal:
41
48
  """What one unit of a series price becomes in the bill: 1 when nothing follows the energy
42
49
  line, and for example 1.05 when VAT is added after it."""
43
50
  names = {other: Decimal(0) for other in series_names(definition)}
44
- base = price_bill(definition, BillInputs(30, 30, {}, Decimal(0), import_cost_by_series=names))
51
+ base = price_bill(definition, unit_inputs(definition, {}, Decimal(0), names))
45
52
  names[name] = _STEP
46
- more = price_bill(definition, BillInputs(30, 30, {}, Decimal(0), import_cost_by_series=names))
53
+ more = price_bill(definition, unit_inputs(definition, {}, Decimal(0), names))
47
54
  return (more.total - base.total) / _STEP
48
55
 
49
56
 
@@ -14,8 +14,8 @@ export rate of 0 is a real choice for it.
14
14
 
15
15
  from __future__ import annotations
16
16
 
17
- from collections.abc import Callable, Sequence
18
- from dataclasses import dataclass, replace
17
+ from collections.abc import Callable, Mapping, Sequence
18
+ from dataclasses import dataclass, field, replace
19
19
  from datetime import date, timedelta
20
20
  from decimal import Decimal
21
21
  from enum import Enum
@@ -122,6 +122,8 @@ class Usage:
122
122
  history: SlotHistory
123
123
  spans: Sequence[DayRange]
124
124
  is_holiday: Callable[[date], bool] = no_holidays
125
+ # The kW the customer is connected for, by name, for plans with a connected load charge.
126
+ load_kw: Mapping[str, Decimal] = field(default_factory=dict)
125
127
 
126
128
 
127
129
  def price_ranges(usage: Usage, definition: TariffDefinition) -> Decimal:
@@ -137,7 +139,8 @@ def price_ranges(usage: Usage, definition: TariffDefinition) -> Decimal:
137
139
  export = Decimal(repr(round(sum(d.total("export") for d in days), 6)))
138
140
  length = (span.last - span.first).days + 1
139
141
  inputs = BillInputs(
140
- length, span.period_days, import_by_band(days, definition, is_holiday), export
142
+ length, span.period_days, import_by_band(days, definition, is_holiday), export,
143
+ load_kw=usage.load_kw,
141
144
  )
142
145
  total += price_bill(definition, inputs).total
143
146
  return total
@@ -240,6 +240,14 @@ class AsyncStore(_Reading):
240
240
  class AsyncPriceStore(_Reading):
241
241
  """Dynamic prices for an event loop. See `PriceStore`."""
242
242
 
243
+ def __init__(self, read: AsyncReader, cache: AsyncCache | None = None, *,
244
+ max_age: float = price_rules.REFRESH_SECONDS,
245
+ today: Callable[[], date] = date.today) -> None:
246
+ super().__init__(read, cache)
247
+ self._max_age = max_age
248
+ self._today = today
249
+ self.stale: list[str] = []
250
+
243
251
  async def latest(self, country: str, feed: str, area: str) -> date | None:
244
252
  path = price_rules.index_path(country, feed, area)
245
253
  return price_rules.latest_of(path, await self._fetch(path))
@@ -247,10 +255,20 @@ class AsyncPriceStore(_Reading):
247
255
  async def day(self, country: str, feed: str, area: str, day: date) -> Doc:
248
256
  path = price_rules.day_path(country, feed, area, day)
249
257
  held = await self._cache.get(path)
250
- raw = held if held is not None else await self._fetch(path)
258
+ age = await self._cache.age(path)
259
+ fetched: bytes | None = None
260
+ if held is None or price_rules.needs_refresh(day, age, self._today(), self._max_age):
261
+ try:
262
+ fetched = await self._fetch(path)
263
+ except StoreError:
264
+ if held is None:
265
+ raise
266
+ self.stale.append(path)
267
+ raw = fetched if fetched is not None else held
268
+ assert raw is not None # nosec B101
251
269
  doc = price_rules.valid_day(path, raw, feed, area, day)
252
- if held is None:
253
- await self._cache.put(path, raw)
270
+ if fetched is not None:
271
+ await self._cache.put(path, fetched)
254
272
  return doc
255
273
 
256
274
  async def days(self, country: str, feed: str, area: str, first: date, # noqa: PLR0913
@@ -2,9 +2,10 @@
2
2
 
3
3
  A `PriceStore` is given one function, `read(path) -> bytes`, like `Store`, but for the prices
4
4
  folder (the root of the `prices` branch). Each day file is checked with `validate_day` before it is
5
- trusted, and must say the country feed, area and date it was asked for. A published day is never
6
- changed, so a day that is held is never fetched again. A day that cannot be read is reported as
7
- missing and never guessed.
5
+ trusted, and must say the country feed, area and date it was asked for. A day that is held is not
6
+ fetched again, except a recent one older than `max_age` (six hours): the update rewrites a day
7
+ whose prices changed, so a recent day is read again, and the kept copy is used when the store
8
+ cannot be reached. A day that cannot be read is reported as missing and never guessed.
8
9
 
9
10
  The feed index lists a checksum for each month, not for each day, so it is not needed to read one
10
11
  day. A client that wants to know the newest day published reads `latest()`.
@@ -26,9 +27,15 @@ class PriceStore:
26
27
  client for an event loop, and both apply the rules in `price_rules`."""
27
28
 
28
29
  def __init__(self, read: Callable[[str], bytes],
29
- cache: MemoryCache | FolderCache | None = None) -> None:
30
+ cache: MemoryCache | FolderCache | None = None, *,
31
+ max_age: float = price_rules.REFRESH_SECONDS,
32
+ today: Callable[[], date] = date.today) -> None:
30
33
  self._read = read
31
34
  self._cache = cache if cache is not None else MemoryCache()
35
+ self._max_age = max_age
36
+ self._today = today
37
+ # Recent days kept past `max_age` because the store could not be read.
38
+ self.stale: list[str] = []
32
39
 
33
40
  def _fetch(self, path: str) -> bytes:
34
41
  try:
@@ -45,10 +52,20 @@ class PriceStore:
45
52
  """The valid day file for one day. Raises `StoreError` when it cannot be read or checked."""
46
53
  path = price_rules.day_path(country, feed, area, day)
47
54
  held = self._cache.get(path)
48
- raw = held if held is not None else self._fetch(path)
55
+ age = self._cache.age(path)
56
+ fetched: bytes | None = None
57
+ if held is None or price_rules.needs_refresh(day, age, self._today(), self._max_age):
58
+ try:
59
+ fetched = self._fetch(path)
60
+ except StoreError:
61
+ if held is None:
62
+ raise
63
+ self.stale.append(path) # offline: the kept copy is better than none
64
+ raw = fetched if fetched is not None else held
65
+ assert raw is not None # nosec B101
49
66
  doc = price_rules.valid_day(path, raw, feed, area, day)
50
- if held is None:
51
- self._cache.put(path, raw)
67
+ if fetched is not None:
68
+ self._cache.put(path, fetched)
52
69
  return doc
53
70
 
54
71
  def days(self, country: str, feed: str, area: str, first: date, # noqa: PLR0913
@@ -1,13 +1,25 @@
1
1
  """What `PriceStore` and `AsyncPriceStore` share: reading a price day file, with no I/O."""
2
2
  from __future__ import annotations
3
3
 
4
- from datetime import date
4
+ from datetime import date, timedelta
5
5
 
6
6
  from .core import StoreError, parsed
7
7
  from .prices import day_path, index_path, validate_day
8
8
  from .schema import Doc
9
9
 
10
- __all__ = ["day_path", "index_path", "latest_of", "valid_day"]
10
+ __all__ = ["REFRESH_SECONDS", "RECENT_DAYS", "day_path", "index_path", "latest_of", "needs_refresh",
11
+ "valid_day"]
12
+
13
+ REFRESH_SECONDS = 6 * 3600.0 # how old a kept recent day may get before it is read again
14
+ RECENT_DAYS = 2 # a day this many days back or later may still be restated
15
+
16
+
17
+ def needs_refresh(day: date, age: float | None, today: date,
18
+ max_age: float = REFRESH_SECONDS) -> bool:
19
+ """True when a kept day is recent and older than `max_age`. The update rewrites a day whose
20
+ prices changed, so a recent day is read again now and then. An old day is final."""
21
+ return age is not None and age > max_age and day >= today - timedelta(days=RECENT_DAYS)
22
+
11
23
 
12
24
 
13
25
  def latest_of(path: str, raw: bytes) -> date | None:
@@ -4,8 +4,9 @@ Dynamic prices change every half hour, so they are written by a machine and cann
4
4
  by one. This module is the only definition of what a file may hold, and the update script writes
5
5
  nothing it refuses. Standard library only. docs/format.md describes the format in words.
6
6
 
7
- A day file lists the prices of one local day from local midnight, one per interval. A published
8
- day is never changed. A day with a daylight saving change has 23 or 25 hours of prices.
7
+ A day file lists the prices of one local day from local midnight, one per interval. A day is
8
+ rewritten only when its prices change. A day with a daylight saving change has 23 or 25 hours of
9
+ prices.
9
10
  """
10
11
  from __future__ import annotations
11
12
 
@@ -43,6 +43,7 @@ NODE_FIELDS = {
43
43
  "per_day": {"kind", "amount", "round"},
44
44
  "per_kwh": {"kind", "amount", "on", "round"},
45
45
  "demand": {"kind", "window", "price", "per", "hours", "days", "months", "holidays", "round"},
46
+ "connected_load": {"kind", "load", "bands", "per", "min_kw", "round"},
46
47
  "per_period": {"kind", "amount", "share", "per", "round"},
47
48
  "adjust": {"kind", "name", "percent", "of", "round"},
48
49
  "tax": {"kind", "name", "percent", "mode", "of", "round"},
@@ -174,6 +175,43 @@ def _demand(node: Doc, path: str, errors: list[str]) -> None:
174
175
  _band_window({"hours": "00:00-12:00", **when}, path, errors)
175
176
 
176
177
 
178
+ def _load_band(name: str, row: object, path: str, errors: list[str]) -> tuple[bool, Decimal | None]:
179
+ """Check one band. Returns whether it was readable and its top, None for the open band."""
180
+ if not NAME.match(name) or not isinstance(row, dict) or not {"upto_kw", "price"} >= set(row):
181
+ errors.append(f"{path}: needs a name like a node and only upto_kw and price")
182
+ return False, None
183
+ before = len(errors)
184
+ for key in ("price", "upto_kw") if "upto_kw" in row else ("price",):
185
+ _price(row.get(key), f"{path}.{key}", errors)
186
+ if str(row.get(key)).startswith("-"):
187
+ errors.append(f"{path}.{key}: must be 0 or more")
188
+ if len(errors) > before:
189
+ return False, None
190
+ return True, Decimal(row["upto_kw"]) if "upto_kw" in row else None
191
+
192
+
193
+ def _connected_load(node: Doc, path: str, errors: list[str]) -> None:
194
+ """A charge on the connected load: a name, bands of price per kW and an optional least load."""
195
+ if not NAME.match(str(node.get("load"))):
196
+ errors.append(f"{path}.load: needs a name like a node")
197
+ if "min_kw" in node:
198
+ _price(node["min_kw"], f"{path}.min_kw", errors)
199
+ if str(node["min_kw"]).startswith("-"):
200
+ errors.append(f"{path}.min_kw: must be 0 or more")
201
+ bands = node.get("bands")
202
+ if not isinstance(bands, dict) or not bands:
203
+ errors.append(f"{path}.bands: needs one or more named bands")
204
+ return
205
+ rows = [_load_band(n, r, f"{path}.bands.{n}", errors) for n, r in bands.items()]
206
+ if not all(ok for ok, _ in rows):
207
+ return
208
+ tops = [top for _, top in rows]
209
+ shown = [top for top in tops if top is not None]
210
+ if tops.count(None) != 1 or len(set(shown)) != len(shown) or any(t <= 0 for t in shown):
211
+ errors.append(f"{path}.bands: needs different tops above 0 and one last band with "
212
+ "no upto_kw")
213
+
214
+
177
215
  def _per_rule(node: Doc, path: str, errors: list[str]) -> None:
178
216
  """`per` says what an amount is written for. A floor or cap may also be per day."""
179
217
  kind = node["kind"]
@@ -188,6 +226,8 @@ def _kind_rules(node: Doc, path: str, errors: list[str]) -> None:
188
226
  kind = node["kind"]
189
227
  if kind == "tiered_energy":
190
228
  _tiers(node, path, errors)
229
+ if kind == "connected_load":
230
+ _connected_load(node, path, errors)
191
231
  if kind == "demand":
192
232
  _demand(node, path, errors)
193
233
  else:
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "utility-tariffs-lib"
7
- version = "0.2.0"
7
+ version = "0.3.1"
8
8
  description = "Tariff model, bill engine, price series, store client and plan ranking"
9
9
  readme = "lib/README.md"
10
10
  license = "MIT"