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.
- utility_tariffs_lib/README.md +41 -0
- utility_tariffs_lib/__init__.py +0 -0
- utility_tariffs_lib/py.typed +0 -0
- utility_tariffs_lib/tariff/__init__.py +164 -0
- utility_tariffs_lib/tariff/accumulator.py +195 -0
- utility_tariffs_lib/tariff/bands.py +124 -0
- utility_tariffs_lib/tariff/bill_days.py +73 -0
- utility_tariffs_lib/tariff/billing.py +28 -0
- utility_tariffs_lib/tariff/compile.py +124 -0
- utility_tariffs_lib/tariff/config.py +208 -0
- utility_tariffs_lib/tariff/defaults.py +16 -0
- utility_tariffs_lib/tariff/definition.py +321 -0
- utility_tariffs_lib/tariff/definition_parse.py +765 -0
- utility_tariffs_lib/tariff/definition_savings.py +116 -0
- utility_tariffs_lib/tariff/demand.py +44 -0
- utility_tariffs_lib/tariff/engine.py +284 -0
- utility_tariffs_lib/tariff/index.py +309 -0
- utility_tariffs_lib/tariff/period_bill.py +136 -0
- utility_tariffs_lib/tariff/periods.py +34 -0
- utility_tariffs_lib/tariff/price_curve.py +142 -0
- utility_tariffs_lib/tariff/price_series.py +137 -0
- utility_tariffs_lib/tariff/price_stats.py +194 -0
- utility_tariffs_lib/tariff/price_timeline.py +139 -0
- utility_tariffs_lib/tariff/reprice.py +106 -0
- utility_tariffs_lib/tariff/savings.py +118 -0
- utility_tariffs_lib/tariff/slot_history.py +128 -0
- utility_tariffs_lib/tariff/slots.py +266 -0
- utility_tariffs_lib/tariff/stored_energy.py +64 -0
- utility_tariffs_lib/tariff/windows.py +119 -0
- utility_tariffs_lib/tariffranking/__init__.py +39 -0
- utility_tariffs_lib/tariffranking/search.py +189 -0
- utility_tariffs_lib/tariffstore/__init__.py +13 -0
- utility_tariffs_lib/tariffstore/client.py +406 -0
- utility_tariffs_lib/tariffstore/compile.py +157 -0
- utility_tariffs_lib/tariffstore/index.py +188 -0
- utility_tariffs_lib/tariffstore/layout.py +39 -0
- utility_tariffs_lib/tariffstore/price_client.py +87 -0
- utility_tariffs_lib/tariffstore/prices.py +127 -0
- utility_tariffs_lib/tariffstore/schema.py +550 -0
- utility_tariffs_lib/timeutil/__init__.py +5 -0
- utility_tariffs_lib/timeutil/real_time.py +52 -0
- utility_tariffs_lib-0.1.0.dist-info/METADATA +61 -0
- utility_tariffs_lib-0.1.0.dist-info/RECORD +46 -0
- utility_tariffs_lib-0.1.0.dist-info/WHEEL +5 -0
- utility_tariffs_lib-0.1.0.dist-info/licenses/LICENSE +21 -0
- 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
|