utility-tariffs-lib 0.1.0__py3-none-any.whl

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 (46) hide show
  1. utility_tariffs_lib/README.md +41 -0
  2. utility_tariffs_lib/__init__.py +0 -0
  3. utility_tariffs_lib/py.typed +0 -0
  4. utility_tariffs_lib/tariff/__init__.py +164 -0
  5. utility_tariffs_lib/tariff/accumulator.py +195 -0
  6. utility_tariffs_lib/tariff/bands.py +124 -0
  7. utility_tariffs_lib/tariff/bill_days.py +73 -0
  8. utility_tariffs_lib/tariff/billing.py +28 -0
  9. utility_tariffs_lib/tariff/compile.py +124 -0
  10. utility_tariffs_lib/tariff/config.py +208 -0
  11. utility_tariffs_lib/tariff/defaults.py +16 -0
  12. utility_tariffs_lib/tariff/definition.py +321 -0
  13. utility_tariffs_lib/tariff/definition_parse.py +765 -0
  14. utility_tariffs_lib/tariff/definition_savings.py +116 -0
  15. utility_tariffs_lib/tariff/demand.py +44 -0
  16. utility_tariffs_lib/tariff/engine.py +284 -0
  17. utility_tariffs_lib/tariff/index.py +309 -0
  18. utility_tariffs_lib/tariff/period_bill.py +136 -0
  19. utility_tariffs_lib/tariff/periods.py +34 -0
  20. utility_tariffs_lib/tariff/price_curve.py +142 -0
  21. utility_tariffs_lib/tariff/price_series.py +137 -0
  22. utility_tariffs_lib/tariff/price_stats.py +194 -0
  23. utility_tariffs_lib/tariff/price_timeline.py +139 -0
  24. utility_tariffs_lib/tariff/reprice.py +106 -0
  25. utility_tariffs_lib/tariff/savings.py +118 -0
  26. utility_tariffs_lib/tariff/slot_history.py +128 -0
  27. utility_tariffs_lib/tariff/slots.py +266 -0
  28. utility_tariffs_lib/tariff/stored_energy.py +64 -0
  29. utility_tariffs_lib/tariff/windows.py +119 -0
  30. utility_tariffs_lib/tariffranking/__init__.py +39 -0
  31. utility_tariffs_lib/tariffranking/search.py +189 -0
  32. utility_tariffs_lib/tariffstore/__init__.py +13 -0
  33. utility_tariffs_lib/tariffstore/client.py +406 -0
  34. utility_tariffs_lib/tariffstore/compile.py +157 -0
  35. utility_tariffs_lib/tariffstore/index.py +188 -0
  36. utility_tariffs_lib/tariffstore/layout.py +39 -0
  37. utility_tariffs_lib/tariffstore/price_client.py +87 -0
  38. utility_tariffs_lib/tariffstore/prices.py +127 -0
  39. utility_tariffs_lib/tariffstore/schema.py +550 -0
  40. utility_tariffs_lib/timeutil/__init__.py +5 -0
  41. utility_tariffs_lib/timeutil/real_time.py +52 -0
  42. utility_tariffs_lib-0.1.0.dist-info/METADATA +61 -0
  43. utility_tariffs_lib-0.1.0.dist-info/RECORD +46 -0
  44. utility_tariffs_lib-0.1.0.dist-info/WHEEL +5 -0
  45. utility_tariffs_lib-0.1.0.dist-info/licenses/LICENSE +21 -0
  46. utility_tariffs_lib-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,406 @@
1
+ """Find, fetch and check tariffs from the store. Standard library only.
2
+
3
+ A `Store` is given one function, `read(path) -> bytes`, that returns a file under `tariffs/`. It
4
+ may read a folder, a URL or a test dictionary. The store walks three levels and checks each one
5
+ against the level above before it is trusted:
6
+
7
+ index.json the countries, each with the checksum of its index
8
+ <cc>/index.json the country's values, then providers, tariffs and revisions
9
+ <cc>/<provider>/<tariff>/<n>.json one revision of one tariff
10
+
11
+ `definition()` returns the document the bill engine reads (`lib.tariff.load_definition`), so a
12
+ caller goes from a country code, a provider, a tariff and a date to a priced bill.
13
+
14
+ What the store hands over is kept in a cache, laid out like the store itself. `FolderCache` keeps
15
+ it on disk, so a tariff is downloaded once, and a caller that has used a tariff can price it again
16
+ with no network. No separate list of what is held is kept: the cached indexes carry the checksum
17
+ of every file, so a cached file is used exactly when it is the one its index describes. Only the
18
+ countries index has an age. `custom_definition()` prices a tariff the store does not hold.
19
+ """
20
+ from __future__ import annotations
21
+
22
+ import json
23
+ import os
24
+ import re
25
+ import time
26
+ import urllib.request
27
+ from collections.abc import Callable
28
+ from datetime import date
29
+ from pathlib import Path
30
+
31
+ from .compile import CompileError, compile_area
32
+ from .index import SCHEMA, block_of
33
+ from .schema import Doc, checksum, holiday_years, validate_country, validate_tariff
34
+
35
+ OPEN = "9999-12-31"
36
+ USER_AGENT = "tariffstore-client/1"
37
+ DAY_SECONDS = 86400.0
38
+ ROOT = "index.json"
39
+ SAFE_PATH = re.compile(r"^[a-z0-9-]+(/[a-z0-9-]+)*\.json$")
40
+ CUSTOM = "custom"
41
+ CUSTOM_SOURCE = {"id": CUSTOM, "url": "https://example.invalid/custom"}
42
+
43
+
44
+ class StoreError(LookupError):
45
+ """Something asked for is not in the store, or a file is not the one its index describes."""
46
+
47
+
48
+ def folder_reader(tariffs: Path) -> Callable[[str], bytes]:
49
+ return lambda path: (Path(tariffs) / path).read_bytes()
50
+
51
+
52
+ def url_reader(base: str, timeout: float = 30) -> Callable[[str], bytes]:
53
+ """Read from an https base such as a raw file host. `base` is the address of `tariffs/`."""
54
+ if not base.startswith("https://"):
55
+ raise ValueError("the store is read over https only")
56
+
57
+ def read(path: str) -> bytes:
58
+ request = urllib.request.Request(f"{base.rstrip('/')}/{path}",
59
+ headers={"User-Agent": USER_AGENT})
60
+ # The base is https, checked above, so no file or other scheme can reach this call.
61
+ with urllib.request.urlopen(request, timeout=timeout) as response: # nosec B310
62
+ body: bytes = response.read()
63
+ return body
64
+ return read
65
+
66
+
67
+ def _safe(path: str) -> str:
68
+ if not SAFE_PATH.match(path):
69
+ raise StoreError(f"{path}: not a path inside the store")
70
+ return path
71
+
72
+
73
+ class MemoryCache:
74
+ """Keeps what was read for as long as the object lives."""
75
+
76
+ def __init__(self, clock: Callable[[], float] = time.time) -> None:
77
+ self._files: dict[str, tuple[bytes, float]] = {}
78
+ self._clock = clock
79
+
80
+ def get(self, path: str) -> bytes | None:
81
+ held = self._files.get(path)
82
+ return held[0] if held else None
83
+
84
+ def put(self, path: str, raw: bytes) -> None:
85
+ self._files[path] = (raw, self._clock())
86
+
87
+ def age(self, path: str) -> float | None:
88
+ """Seconds since the file was kept, or None when it is not held."""
89
+ held = self._files.get(path)
90
+ return self._clock() - held[1] if held else None
91
+
92
+
93
+ class FolderCache:
94
+ """Keeps what was read in a folder on disk, at the same paths as the store, so it lasts
95
+ between runs and can be read by hand. Deleting the folder, or any file in it, is safe."""
96
+
97
+ def __init__(self, folder: Path | str, clock: Callable[[], float] = time.time) -> None:
98
+ self._folder = Path(folder)
99
+ self._clock = clock
100
+
101
+ def get(self, path: str) -> bytes | None:
102
+ try:
103
+ return (self._folder / _safe(path)).read_bytes()
104
+ except OSError:
105
+ return None
106
+
107
+ def put(self, path: str, raw: bytes) -> None:
108
+ target = self._folder / _safe(path)
109
+ target.parent.mkdir(parents=True, exist_ok=True)
110
+ # Written beside the file and moved into place, so a reader never sees half a file.
111
+ partial = target.with_name(target.name + ".part")
112
+ partial.write_bytes(raw)
113
+ os.replace(partial, target)
114
+
115
+ def age(self, path: str) -> float | None:
116
+ try:
117
+ return self._clock() - (self._folder / _safe(path)).stat().st_mtime
118
+ except OSError:
119
+ return None
120
+
121
+
122
+ class Store:
123
+ """The tariff store, read through `read`, with what it reads kept in `cache`.
124
+
125
+ The countries index is read again once it is older than `max_age` seconds. Everything below
126
+ it is read again only when its checksum in the level above has changed. When the store cannot
127
+ be reached, what the cache holds is used and `offline` is true."""
128
+
129
+ def __init__(self, read: Callable[[str], bytes],
130
+ cache: MemoryCache | FolderCache | None = None, *,
131
+ max_age: float = DAY_SECONDS) -> None:
132
+ self._read = read
133
+ self._cache = cache if cache is not None else MemoryCache()
134
+ self._max_age = max_age
135
+ self._root: Doc | None = None
136
+ self._countries: dict[str, Doc] = {}
137
+ self._forced = False
138
+ self.offline = False
139
+
140
+ @classmethod
141
+ def cached(cls, base: str, folder: Path | str, *, max_age: float = DAY_SECONDS) -> Store:
142
+ """A store read from an https address, with a cache in `folder`."""
143
+ return cls(url_reader(base), FolderCache(folder), max_age=max_age)
144
+
145
+ def _parsed(self, path: str, raw: bytes) -> Doc:
146
+ try:
147
+ doc = json.loads(raw)
148
+ except ValueError as error:
149
+ raise StoreError(f"{path}: not JSON ({error})") from error
150
+ if not isinstance(doc, dict):
151
+ raise StoreError(f"{path}: not a JSON object")
152
+ return doc
153
+
154
+ def _fetch(self, path: str) -> bytes:
155
+ try:
156
+ return self._read(_safe(path))
157
+ except OSError as error:
158
+ raise StoreError(f"{path}: cannot be read ({error})") from error
159
+
160
+ def _checked(self, path: str, wanted: str) -> Doc:
161
+ """The file at `path` whose checksum is `wanted`: from the cache when it holds that very
162
+ file, else from the store, and then kept."""
163
+ held = self._cache.get(path)
164
+ if held is not None:
165
+ kept: Doc | None
166
+ try:
167
+ kept = self._parsed(path, held)
168
+ except StoreError:
169
+ kept = None
170
+ if kept is not None and checksum(kept) == wanted:
171
+ return kept
172
+ raw = self._fetch(path)
173
+ doc = self._parsed(path, raw)
174
+ if checksum(doc) != wanted:
175
+ raise StoreError(f"{path}: does not match its checksum")
176
+ self._cache.put(path, raw)
177
+ return doc
178
+
179
+ def _read_root(self) -> Doc:
180
+ held, age = self._cache.get(ROOT), self._cache.age(ROOT)
181
+ if held is not None and not self._forced and age is not None and age <= self._max_age:
182
+ return self._parsed(ROOT, held)
183
+ try:
184
+ raw = self._fetch(ROOT)
185
+ root = self._parsed(ROOT, raw)
186
+ except StoreError:
187
+ # Unreachable, or an answer that is not the index (a sign-in page, say).
188
+ if held is None:
189
+ raise
190
+ self.offline = True
191
+ return self._parsed(ROOT, held)
192
+ self._cache.put(ROOT, raw)
193
+ self._forced = self.offline = False
194
+ return root
195
+
196
+ def refresh(self) -> None:
197
+ """Read the countries index from the store again on the next call, whatever its age.
198
+ Files whose checksum has not changed are not downloaded again."""
199
+ self._root, self._countries = None, {}
200
+ self._forced = True
201
+
202
+ # Finding
203
+
204
+ def countries(self) -> dict[str, Doc]:
205
+ """{country code: {availability, reason, providers, tariffs}} for every country listed."""
206
+ if self._root is None:
207
+ root = self._read_root()
208
+ if root.get("schema") != SCHEMA or not isinstance(root.get("countries"), dict):
209
+ raise StoreError(f"index.json: not a schema {SCHEMA} countries index")
210
+ self._root = root
211
+ countries: dict[str, Doc] = self._root["countries"]
212
+ return countries
213
+
214
+ def country(self, code: str) -> Doc:
215
+ """The country's index, checked against the countries index: its values and its tariffs."""
216
+ code = code.upper()
217
+ if code not in self._countries:
218
+ entry = self.countries().get(code)
219
+ if entry is None or "path" not in entry:
220
+ reason = f": {entry['reason']}" if entry else ""
221
+ raise StoreError(f"{code}: no tariffs are held{reason}")
222
+ self._countries[code] = self._checked(entry["path"], entry["checksum"])
223
+ return self._countries[code]
224
+
225
+ def providers(self, code: str) -> dict[str, str]:
226
+ """{provider id: provider name} in one country."""
227
+ return {key: p["name"] for key, p in self.country(code)["providers"].items()}
228
+
229
+ def tariffs(self, code: str, provider: str, *, direction: str = "import",
230
+ on: date | None = None) -> dict[str, str]:
231
+ """{tariff id: name} for one provider. `on` keeps only tariffs with a revision in force."""
232
+ try:
233
+ entries = self.country(code)["providers"][provider]["tariffs"]
234
+ except KeyError:
235
+ raise StoreError(f"{code}: no provider {provider}") from None
236
+ return {key: t["name"] for key, t in entries.items()
237
+ if t.get("direction", "import") == direction
238
+ and (on is None or _in_force(t, on) is not None)}
239
+
240
+ def revision(self, code: str, provider: str, tariff: str, on: date) -> tuple[int, Doc]:
241
+ """(revision number, its index entry) in force on a day."""
242
+ try:
243
+ entry = self.country(code)["providers"][provider]["tariffs"][tariff]
244
+ except KeyError:
245
+ raise StoreError(f"{code}: no tariff {provider}/{tariff}") from None
246
+ number = _in_force(entry, on)
247
+ if number is None:
248
+ raise StoreError(f"{code}/{provider}/{tariff}: no revision is in force on {on}")
249
+ return number, entry["revisions"][str(number)]
250
+
251
+ def revision_starts(self, code: str, provider: str, tariff: str, on: date, # noqa: PLR0913
252
+ until: date) -> list[tuple[date, int]]:
253
+ """(first day, revision number) of every revision that starts after `on`, up to and
254
+ including `until`, earliest first. The revision in force on `on` is not listed."""
255
+ try:
256
+ entry = self.country(code)["providers"][provider]["tariffs"][tariff]
257
+ except KeyError:
258
+ raise StoreError(f"{code}: no tariff {provider}/{tariff}") from None
259
+ found = [(date.fromisoformat(r["effective_from"]), int(number))
260
+ for number, r in entry["revisions"].items()
261
+ if on < date.fromisoformat(r["effective_from"]) <= until]
262
+ return sorted(found)
263
+
264
+ # Fetching
265
+
266
+ def tariff(self, code: str, provider: str, tariff: str, on: date) -> tuple[int, Doc]:
267
+ """(revision number, tariff file) in force on a day, checked against its checksum and
268
+ valid."""
269
+ number, entry = self.revision(code, provider, tariff, on)
270
+ path = f"{code.lower()}/{provider}/{tariff}/{number}.json"
271
+ doc = self._checked(path, entry["checksum"])
272
+ errors = validate_tariff(doc)
273
+ if errors:
274
+ raise StoreError(f"{path}: " + "; ".join(errors))
275
+ return number, doc
276
+
277
+ def fetch_country(self, code: str, *, on: date | None = None) -> int:
278
+ """Bring a whole country into the cache, for comparing many tariffs or for use with no
279
+ network. `on` keeps it to the revisions in force on that day. Returns the number of
280
+ tariff files now held."""
281
+ count = 0
282
+ for provider, entry in self.country(code)["providers"].items():
283
+ for tariff, listed in entry["tariffs"].items():
284
+ for number, revision in listed["revisions"].items():
285
+ if on is not None and _in_force(listed, on) != int(number):
286
+ continue
287
+ path = f"{code.lower()}/{provider}/{tariff}/{number}.json"
288
+ self._checked(path, revision["checksum"])
289
+ count += 1
290
+ return count
291
+
292
+ def is_holiday(self, code: str, region: str | None = None) -> Callable[[date], bool]:
293
+ """Whether a day is a public holiday in the country, for the engine to price a band that
294
+ treats one as a weekend day. `region` is an ISO 3166-2 code, for a country whose regions
295
+ keep different days.
296
+
297
+ A country that holds no holidays is refused here. A day in a year that is not held is
298
+ refused when it is asked about, because a missing year is not a year without holidays."""
299
+ years = holiday_years(self.country(code), region)
300
+ if years is None:
301
+ raise StoreError(f"{code.upper()}: no public holidays are held")
302
+
303
+ def is_holiday(day: date) -> bool:
304
+ if day.year not in years:
305
+ raise StoreError(f"{code.upper()}: no public holidays are held for {day.year}")
306
+ return day.isoformat() in years[day.year]
307
+ return is_holiday
308
+
309
+ def areas(self, code: str, provider: str, tariff: str, on: date) -> dict[str, str]:
310
+ """{area key: label} a customer chooses from. A tariff with one price has the area `all`."""
311
+ _, doc = self.tariff(code, provider, tariff, on)
312
+ return {key: row.get("label", doc["name"]) for key, row in doc["areas"].items()}
313
+
314
+ def _export_file(self, code: str, target: str, on: date) -> Doc:
315
+ """The stored export tariff named `provider-id/tariff-id`."""
316
+ provider, _, tariff = target.partition("/")
317
+ doc = self.tariff(code, provider, tariff, on)[1]
318
+ if doc.get("direction") != "export":
319
+ raise StoreError(f"{target}: not an export tariff")
320
+ return doc
321
+
322
+ def definition(self, code: str, provider: str, tariff: str, on: date, *, # noqa: PLR0913
323
+ area: str = "all", export: str | None = None) -> Doc:
324
+ """The engine's definition for one area of a tariff on a day.
325
+
326
+ `export` names an export tariff as `provider-id/tariff-id` to pay for exported energy. Left
327
+ out, the export tariff the import tariff itself names is used, if it names one."""
328
+ code = code.upper()
329
+ number, doc = self.tariff(code, provider, tariff, on)
330
+ if doc.get("direction") == "export":
331
+ raise StoreError(f"{provider}/{tariff}: an export tariff is paired with an import "
332
+ "tariff, it has no bill of its own")
333
+ target = export or doc.get("export")
334
+ export_file = self._export_file(code, target, on) if target else None
335
+ _, entry = self.revision(code, provider, tariff, on)
336
+ meta = {"country": code, "provider": provider, "tariff": tariff, "revision": number,
337
+ "effective_to": entry["effective_to"]}
338
+ return compile_area(doc, area, block=block_of(self.country(code)), meta=meta,
339
+ on=on.isoformat(), export_file=export_file)
340
+
341
+ # A tariff the store does not hold
342
+
343
+ def _custom_export(self, code: str, export: str | Doc | None, on: date) -> Doc | None:
344
+ if export is None:
345
+ return None
346
+ if isinstance(export, str):
347
+ provider, _, tariff = export.partition("/")
348
+ found = self.tariff(code, provider, tariff, on)[1]
349
+ else:
350
+ found = _custom(export)
351
+ if found.get("direction") != "export":
352
+ raise StoreError("custom tariff: the export given is not an export tariff")
353
+ return found
354
+
355
+ def custom_definition(self, code: str, doc: Doc, on: date, *, # noqa: PLR0913
356
+ area: str = "all", export: str | Doc | None = None,
357
+ block: Doc | None = None) -> Doc:
358
+ """The engine's definition for a tariff the caller supplies, written like a tariff file.
359
+
360
+ The country's currency, time zone, tax and standard bill come from the store, so the
361
+ caller types only names, dates, bands and prices. `provider` and `source` may be left
362
+ out. `export` is a stored export tariff (`provider-id/tariff-id`) or a custom export
363
+ file. For a country the store does not hold, pass its values as `block`, written like the
364
+ top of a country index. The document is checked by the same rules as a stored tariff."""
365
+ code = code.upper()
366
+ doc = _custom(doc)
367
+ if doc.get("direction") == "export":
368
+ raise StoreError("custom tariff: pass an export tariff as `export`, with an import "
369
+ "tariff")
370
+ if block is None:
371
+ block = block_of(self.country(code))
372
+ else:
373
+ _refuse("custom country", validate_country(block))
374
+ export_file = self._custom_export(code, export, on)
375
+ meta = {"country": code, "provider": CUSTOM, "tariff": CUSTOM, "revision": 1,
376
+ "effective_to": doc.get("effective_to")}
377
+ try:
378
+ out = compile_area(doc, area, block=block, meta=meta, on=on.isoformat(),
379
+ export_file=export_file)
380
+ except CompileError as error:
381
+ raise StoreError(f"custom tariff: {error}") from error
382
+ if doc["source"] == CUSTOM_SOURCE:
383
+ out["source_url"] = None
384
+ return out
385
+
386
+
387
+ def _refuse(what: str, errors: list[str]) -> None:
388
+ if errors:
389
+ raise StoreError(f"{what}: " + "; ".join(errors))
390
+
391
+
392
+ def _custom(doc: Doc) -> Doc:
393
+ """A supplied tariff with the fields a person need not type filled in, then validated."""
394
+ if not isinstance(doc, dict):
395
+ raise StoreError("custom tariff: not a JSON object")
396
+ full = {"schema": 1, "provider": "Custom", "source": dict(CUSTOM_SOURCE), **doc}
397
+ _refuse("custom tariff", validate_tariff(full))
398
+ return full
399
+
400
+
401
+ def _in_force(entry: Doc, on: date) -> int | None:
402
+ day = on.isoformat()
403
+ for number, revision in entry["revisions"].items():
404
+ if revision["effective_from"] <= day < (revision["effective_to"] or OPEN):
405
+ return int(number)
406
+ return None
@@ -0,0 +1,157 @@
1
+ """Build the full definition the bill engine (lib/tariff) reads, from a tariff file and its
2
+ country block. Standard library only.
3
+
4
+ The tariff file has bands and one row of rates per area. The country block has the currency, the
5
+ time zone, the VAT rate and the standard bill. `$country.name` takes a value from the country block
6
+ and `$input.name` becomes a reference to a customer input. Nothing here changes a price.
7
+ """
8
+ from __future__ import annotations
9
+
10
+ import copy
11
+ import json
12
+ import re
13
+ from collections.abc import Iterator
14
+ from typing import Any
15
+
16
+ from .schema import REF, Doc, vat_on
17
+
18
+
19
+ class CompileError(ValueError):
20
+ pass
21
+
22
+
23
+ def _country_value(match: re.Match[str], block: Doc, on: str, path: str) -> Any:
24
+ if match.group(1) != "country":
25
+ raise CompileError(f"{path}: $input is only allowed in the bill period")
26
+ name = match.group(2)
27
+ value = vat_on(block, on) if name == "vat_percent" else block.get(name)
28
+ if value is None or isinstance(value, (dict, list)):
29
+ raise CompileError(f"{path}: country has no value for {name} on {on}")
30
+ return value
31
+
32
+
33
+ def _resolve(node: Any, block: Doc, on: str, path: str = "") -> Any:
34
+ """Copy of a bill tree with `$country.x` replaced by its value."""
35
+ if isinstance(node, dict):
36
+ return {k: _resolve(v, block, on, f"{path}.{k}") for k, v in node.items()}
37
+ match = REF.match(node) if isinstance(node, str) else None
38
+ return _country_value(match, block, on, path) if match else node
39
+
40
+
41
+ def _nodes(node: Doc) -> Iterator[Doc]:
42
+ yield node
43
+ child = node.get("of")
44
+ if isinstance(child, dict):
45
+ if "kind" in child:
46
+ yield from _nodes(child)
47
+ else:
48
+ for sub in child.values():
49
+ yield from _nodes(sub)
50
+
51
+
52
+ def _add_export_credit(total: Doc) -> None:
53
+ """Add an export_credit line to the outermost sum, so a paired export price is paid."""
54
+ node = total
55
+ while node["kind"] != "sum":
56
+ if "of" not in node or "kind" not in node["of"]:
57
+ raise CompileError("no sum in the bill to add an export credit to")
58
+ node = node["of"]
59
+ node["of"].setdefault("export", {"kind": "export_credit"})
60
+
61
+
62
+ def _zone(band: Doc, priority: int, price: str) -> Doc:
63
+ zone = {"name": band["name"], "priority": priority, "hours": band["hours"], "price": price}
64
+ zone.update({k: band[k] for k in ("days", "months", "holidays") if k in band})
65
+ return zone
66
+
67
+
68
+ def _prices(bands: list[Doc], rates: dict[str, str]) -> Doc:
69
+ """The engine's price table: the first band is the base, each later band a zone that wins
70
+ over the ones before it."""
71
+ base = {"name": bands[0]["name"], "price": rates[bands[0]["name"]]}
72
+ zones = [_zone(band, i, rates[band["name"]]) for i, band in enumerate(bands[1:], 1)]
73
+ return {"base": base, "zones": zones}
74
+
75
+
76
+ def export_prices(export_file: Doc, area: str = "all") -> Doc:
77
+ """The export prices for `area`, flat or by time of day. An export file with no row for the
78
+ area pays its first row, which is how a single national export price is written."""
79
+ areas = export_file["areas"]
80
+ row = areas.get(area) or next(iter(areas.values()))
81
+ prices = _prices(export_file["bands"], row["rates"])
82
+ return prices if prices["zones"] else {"base": prices["base"]}
83
+
84
+
85
+ def _period(bill: Doc, block: Doc, inputs: Doc) -> Doc:
86
+ """The bill period, with each `$input.name` turned into the engine's input reference.
87
+
88
+ A tariff's own period replaces the country's whole period, so the two are never mixed."""
89
+ period: Doc = bill.get("period") or copy.deepcopy(block["bill"]["period"])
90
+ for key in ("start_day", "months", "start_month"):
91
+ value = period.get(key)
92
+ if isinstance(value, str):
93
+ match = REF.match(value)
94
+ if not match or match.group(1) != "input" or match.group(2) not in inputs:
95
+ raise CompileError(f"bill.period.{key}: {value} is not a declared input")
96
+ period[key] = {"input": match.group(2)}
97
+ return period
98
+
99
+
100
+ def _total(bill: Doc, block: Doc, on: str, standing: object) -> Doc:
101
+ """The bill tree with country values filled in and the area's standing charge on each day."""
102
+ total: Doc = _resolve(bill["total"], block, on)
103
+ for node in _nodes(total):
104
+ if node.get("kind") == "per_day" and node.get("amount") is None:
105
+ node["amount"] = standing
106
+ return total
107
+
108
+
109
+ def _netting(bill: Doc) -> Doc:
110
+ """The bill's netting rule, written only when it is not the default."""
111
+ return {"netting": bill["netting"]} if bill.get("netting", "none") != "none" else {}
112
+
113
+
114
+ def compile_area(tariff: Doc, area: str, *, block: Doc, meta: Doc, # noqa: PLR0913
115
+ on: str, export_file: Doc | None = None) -> Doc:
116
+ """The engine's definition for one area of a tariff, priced on the ISO date `on`.
117
+
118
+ `meta` is what the path says: country, provider id, tariff id and revision number."""
119
+ if area not in tariff["areas"]:
120
+ raise CompileError(f"no area {area}; this tariff has {', '.join(tariff['areas'])}")
121
+ row = tariff["areas"][area]
122
+ bill = copy.deepcopy({**block["bill"], **tariff.get("bill", {})})
123
+ inputs = {**copy.deepcopy(block.get("inputs", {})), **tariff.get("inputs", {})}
124
+ period = _period(bill, block, inputs)
125
+ total = _total(bill, block, on, row["standing"])
126
+ export: Doc = {"base": {"name": "Export", "price": "0"}}
127
+ if export_file is not None:
128
+ _add_export_credit(total)
129
+ export = export_prices(export_file, area)
130
+ revision = int(meta["revision"])
131
+ return {
132
+ "schema": 1,
133
+ "id": meta["tariff"] if area == "all" else f"{meta['tariff']}-{area}",
134
+ "revision": revision, "supersedes": revision - 1 or None,
135
+ "name": tariff["name"] if area == "all" else f"{tariff['name']} ({row['label']})",
136
+ "service": tariff.get("service", "electricity"),
137
+ "customer_class": tariff.get("customer_class", "residential"),
138
+ "provider": {"id": meta["provider"], "name": tariff["provider"]},
139
+ "country": meta["country"], "region": None,
140
+ "currency": block["currency"], "timezone": tariff.get("timezone", block["timezone"]),
141
+ "effective_from": tariff["effective_from"], "effective_to": meta.get("effective_to"),
142
+ "source_url": tariff["source"]["url"], "last_verified": None,
143
+ "completeness": "complete" if tariff.get("checks") else "partial",
144
+ "inputs": inputs, "import": _prices(tariff["bands"], row["rates"]), "export": export,
145
+ "bill": {"period": period, "total": total, **_netting(bill)},
146
+ "checks": tariff.get("checks", {}),
147
+ }
148
+
149
+
150
+ def check_references(tariff: Doc, block: Doc) -> list[str]:
151
+ """Every `$country.x` the tariff or the country bill uses must exist in the country block."""
152
+ problems = []
153
+ for where, tree in (("tariff", tariff.get("bill")), ("country bill", block["bill"])):
154
+ for ref in re.findall(r"\$country\.([a-z][a-z0-9_]*)", json.dumps(tree or {})):
155
+ if ref not in block:
156
+ problems.append(f"{where}: $country.{ref} is not in the country block")
157
+ return problems