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,188 @@
|
|
|
1
|
+
"""Build and check the indexes. Pure functions over parsed JSON, standard library only.
|
|
2
|
+
|
|
3
|
+
A country index is the country block (the values every tariff in the country shares, edited by
|
|
4
|
+
hand) followed by `providers`, the tariff collection, which is derived from the tariff files and
|
|
5
|
+
from nothing else. So the same files always give the same index, byte for byte.
|
|
6
|
+
"""
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import re
|
|
10
|
+
|
|
11
|
+
from .compile import CompileError, check_references, compile_area
|
|
12
|
+
from .schema import (
|
|
13
|
+
SLUG,
|
|
14
|
+
Doc,
|
|
15
|
+
checksum,
|
|
16
|
+
validate_country,
|
|
17
|
+
validate_tariff,
|
|
18
|
+
validate_unavailable,
|
|
19
|
+
)
|
|
20
|
+
|
|
21
|
+
SCHEMA = 1
|
|
22
|
+
PATH = re.compile(r"^([a-z0-9-]+)/([a-z0-9-]+)/([1-9][0-9]*)\.json$")
|
|
23
|
+
OPEN = "9999-12-31"
|
|
24
|
+
Revisions = dict[int, Doc]
|
|
25
|
+
Tariffs = dict[tuple[str, str], Revisions]
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def block_of(index: Doc) -> Doc:
|
|
29
|
+
"""The hand-maintained part of a country index: everything but the tariff collection."""
|
|
30
|
+
return {k: v for k, v in index.items() if k != "providers"}
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def group(files: dict[str, Doc]) -> tuple[Tariffs, list[str]]:
|
|
34
|
+
"""{(provider id, tariff id): {revision: file}}, and the paths that are not
|
|
35
|
+
provider/tariff/n.json."""
|
|
36
|
+
tariffs: Tariffs = {}
|
|
37
|
+
bad = []
|
|
38
|
+
for path in sorted(files):
|
|
39
|
+
match = PATH.match(path)
|
|
40
|
+
if not match or not SLUG.match(match.group(1)) or not SLUG.match(match.group(2)):
|
|
41
|
+
bad.append(f"{path}: must be <provider-id>/<tariff-id>/<revision>.json")
|
|
42
|
+
continue
|
|
43
|
+
tariffs.setdefault((match.group(1), match.group(2)), {})[int(match.group(3))] = files[path]
|
|
44
|
+
return tariffs, bad
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def end_of(revisions: Revisions, number: int) -> str | None:
|
|
48
|
+
"""When a revision stops: its own `effective_to`, or else the day the next revision starts."""
|
|
49
|
+
own: str | None = revisions[number].get("effective_to")
|
|
50
|
+
following = revisions.get(number + 1)
|
|
51
|
+
start: str | None = following["effective_from"] if following else None
|
|
52
|
+
return own or start
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def _revision_problems(key: str, revisions: Revisions) -> list[str]:
|
|
56
|
+
numbers = sorted(revisions)
|
|
57
|
+
if numbers != list(range(1, len(numbers) + 1)):
|
|
58
|
+
return [f"{key}: revisions must be numbered 1, 2, 3 with none missing"]
|
|
59
|
+
problems = []
|
|
60
|
+
for number in numbers[1:]:
|
|
61
|
+
before, this = revisions[number - 1], revisions[number]
|
|
62
|
+
if this["effective_from"] <= before["effective_from"]:
|
|
63
|
+
problems.append(f"{key}/{number}: must start after revision {number - 1}")
|
|
64
|
+
elif before.get("effective_to", this["effective_from"]) > this["effective_from"]:
|
|
65
|
+
problems.append(f"{key}/{number}: starts before revision {number - 1} ends")
|
|
66
|
+
if this.get("direction") != before.get("direction"):
|
|
67
|
+
problems.append(f"{key}/{number}: a tariff cannot change direction")
|
|
68
|
+
return problems
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def _overlaps(revisions: Revisions, other: Revisions) -> bool:
|
|
72
|
+
spans = [(r["effective_from"], end_of(revs, n) or OPEN)
|
|
73
|
+
for revs in (revisions, other) for n, r in revs.items()]
|
|
74
|
+
mine, theirs = spans[:len(revisions)], spans[len(revisions):]
|
|
75
|
+
return any(a < d and c < b for a, b in mine for c, d in theirs)
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def _export_problem(doc: Doc, number: int, tariffs: Tariffs, code: str) -> list[str]:
|
|
79
|
+
"""What is wrong with the export tariff an import file names, if it names one."""
|
|
80
|
+
target = doc.get("export")
|
|
81
|
+
if not target:
|
|
82
|
+
return []
|
|
83
|
+
provider, _, tariff = target.partition("/")
|
|
84
|
+
other = tariffs.get((provider, tariff))
|
|
85
|
+
if not other:
|
|
86
|
+
return [f"export {target} does not exist in {code}"]
|
|
87
|
+
if other[max(other)].get("direction") != "export":
|
|
88
|
+
return [f"export {target} is not an export file"]
|
|
89
|
+
if not _overlaps({number: doc}, other):
|
|
90
|
+
return [f"export {target} has no revision overlapping its dates"]
|
|
91
|
+
return []
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def _compile_problems(doc: Doc, block: Doc, meta: Doc) -> list[str]:
|
|
95
|
+
"""Each area of an import file must compile into a definition the engine reads."""
|
|
96
|
+
found = []
|
|
97
|
+
for area in doc["areas"]:
|
|
98
|
+
try:
|
|
99
|
+
compile_area(doc, area, block=block, meta=meta, on=doc["effective_from"])
|
|
100
|
+
except (CompileError, KeyError) as error:
|
|
101
|
+
found.append(f"area {area} does not compile: {error}")
|
|
102
|
+
return found
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def _holiday_problem(doc: Doc, block: Doc) -> list[str]:
|
|
106
|
+
"""A band priced by public holidays needs the country to hold them."""
|
|
107
|
+
if "holidays" in block or not any("holidays" in band for band in doc["bands"]):
|
|
108
|
+
return []
|
|
109
|
+
return ["a band counts public holidays, and the country block holds none"]
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def _file_problems(doc: Doc, meta: Doc, block: Doc, tariffs: Tariffs) -> list[str]:
|
|
113
|
+
found = check_references(doc, block) + _holiday_problem(doc, block)
|
|
114
|
+
found += _export_problem(doc, meta["revision"], tariffs, meta["country"])
|
|
115
|
+
if doc.get("direction") != "export":
|
|
116
|
+
found += _compile_problems(doc, block, meta)
|
|
117
|
+
return found
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def problems(code: str, block: Doc, files: dict[str, Doc]) -> list[str]:
|
|
121
|
+
"""Everything wrong with one country's block and tariff files. Empty means it can be indexed."""
|
|
122
|
+
found = [f"country block: {e}" for e in validate_country(block)]
|
|
123
|
+
if not found and block["country"] != code:
|
|
124
|
+
found.append(f"country block: country must be {code}")
|
|
125
|
+
tariffs, bad = group(files)
|
|
126
|
+
found += bad
|
|
127
|
+
for path in sorted(files):
|
|
128
|
+
found += [f"{path}: {e}" for e in validate_tariff(files[path])]
|
|
129
|
+
if found:
|
|
130
|
+
return found
|
|
131
|
+
for (provider, tariff), revisions in tariffs.items():
|
|
132
|
+
key = f"{provider}/{tariff}"
|
|
133
|
+
found += _revision_problems(key, revisions)
|
|
134
|
+
for number, doc in revisions.items():
|
|
135
|
+
meta = {"country": code, "provider": provider, "tariff": tariff, "revision": number}
|
|
136
|
+
found += [f"{key}/{number}: {p}" for p in _file_problems(doc, meta, block, tariffs)]
|
|
137
|
+
return found
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
def _tariff_entry(revisions: Revisions) -> Doc:
|
|
141
|
+
latest = revisions[max(revisions)]
|
|
142
|
+
entry: Doc = {"name": latest["name"]}
|
|
143
|
+
if latest.get("direction") == "export":
|
|
144
|
+
entry["direction"] = "export"
|
|
145
|
+
entry["revisions"] = {
|
|
146
|
+
str(n): {"effective_from": doc["effective_from"], "effective_to": end_of(revisions, n),
|
|
147
|
+
"checksum": checksum(doc)} for n, doc in sorted(revisions.items())}
|
|
148
|
+
return entry
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def country_index(block: Doc, files: dict[str, Doc]) -> Doc:
|
|
152
|
+
"""The country index: the block, then the tariff collection derived from the files."""
|
|
153
|
+
providers: dict[str, Doc] = {}
|
|
154
|
+
for (provider, tariff), revisions in group(files)[0].items():
|
|
155
|
+
latest = revisions[max(revisions)]
|
|
156
|
+
entry = _tariff_entry(revisions)
|
|
157
|
+
slot = providers.setdefault(
|
|
158
|
+
provider, {"name": latest["provider"], "newest": "", "tariffs": {}})
|
|
159
|
+
if latest["effective_from"] >= slot["newest"]: # the newest file names the provider
|
|
160
|
+
slot["name"], slot["newest"] = latest["provider"], latest["effective_from"]
|
|
161
|
+
slot["tariffs"][tariff] = entry
|
|
162
|
+
for slot in providers.values():
|
|
163
|
+
del slot["newest"]
|
|
164
|
+
return {**block, "schema": SCHEMA, "providers": providers}
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
def _root_entry(code: str, index: Doc) -> Doc:
|
|
168
|
+
entry: Doc = {"availability": index.get("availability", "available"),
|
|
169
|
+
"path": f"{code.lower()}/index.json", "checksum": checksum(index),
|
|
170
|
+
"providers": len(index["providers"]),
|
|
171
|
+
"tariffs": sum(len(p["tariffs"]) for p in index["providers"].values())}
|
|
172
|
+
if index.get("reason"):
|
|
173
|
+
entry["reason"] = index["reason"]
|
|
174
|
+
return entry
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
def root_index(countries: dict[str, Doc], unavailable: Doc) -> Doc:
|
|
178
|
+
"""The countries index: one small entry per country, so a client sees what changed."""
|
|
179
|
+
errors = validate_unavailable(unavailable)
|
|
180
|
+
clash = sorted(set(unavailable.get("countries", {})) & set(countries)) if not errors else []
|
|
181
|
+
if errors or clash:
|
|
182
|
+
raise ValueError("unavailable.json: "
|
|
183
|
+
+ "; ".join(errors or [f"{c} has tariff files" for c in clash]))
|
|
184
|
+
out = {code: _root_entry(code, index) for code, index in countries.items()}
|
|
185
|
+
for code, entry in unavailable["countries"].items():
|
|
186
|
+
out[code] = {"availability": "unavailable", "reason": entry["reason"],
|
|
187
|
+
"checked": entry["checked"]}
|
|
188
|
+
return {"schema": SCHEMA, "countries": dict(sorted(out.items()))}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
"""How the JSON files are written: single values first, the collection last, two-space indent.
|
|
2
|
+
|
|
3
|
+
One writer for every file, so a rebuild of unchanged data changes no byte. The order never changes
|
|
4
|
+
a checksum, which sorts keys itself.
|
|
5
|
+
"""
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
import json
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
INDEX_FIRST = ("schema", "country", "currency", "timezone", "vat_percent", "availability", "reason",
|
|
12
|
+
"inputs", "bill", "holidays")
|
|
13
|
+
TARIFF_FIRST = ("schema", "name", "provider", "service", "customer_class", "direction", "timezone",
|
|
14
|
+
"effective_from", "effective_to", "source", "prices_include_tax", "export")
|
|
15
|
+
TARIFF_LAST = ("bands", "areas")
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def _sorted(value: object) -> Any:
|
|
19
|
+
return json.loads(json.dumps(value, sort_keys=True))
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def dumps(doc: dict[str, Any], first: tuple[str, ...] = (), last: tuple[str, ...] = ()) -> str:
|
|
23
|
+
head = [k for k in first if k in doc]
|
|
24
|
+
tail = [k for k in last if k in doc]
|
|
25
|
+
middle = sorted(k for k in doc if k not in head and k not in tail)
|
|
26
|
+
return json.dumps({k: _sorted(doc[k]) for k in head + middle + tail}, indent=2,
|
|
27
|
+
ensure_ascii=False) + "\n"
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def dumps_index(doc: dict[str, Any]) -> str:
|
|
31
|
+
return dumps(doc, first=INDEX_FIRST, last=("providers",))
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def dumps_root(doc: dict[str, Any]) -> str:
|
|
35
|
+
return dumps(doc, first=("schema",), last=("countries",))
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def dumps_tariff(doc: dict[str, Any]) -> str:
|
|
39
|
+
return dumps(doc, first=TARIFF_FIRST, last=TARIFF_LAST)
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
"""Read dynamic price day files from the `prices` branch. Standard library only.
|
|
2
|
+
|
|
3
|
+
A `PriceStore` is given one function, `read(path) -> bytes`, like `Store`, but for the prices
|
|
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.
|
|
8
|
+
|
|
9
|
+
The feed index lists a checksum for each month, not for each day, so it is not needed to read one
|
|
10
|
+
day. A client that wants to know the newest day published reads `latest()`.
|
|
11
|
+
"""
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import json
|
|
15
|
+
from collections.abc import Callable
|
|
16
|
+
from datetime import date, timedelta
|
|
17
|
+
from typing import Any
|
|
18
|
+
|
|
19
|
+
from .client import FolderCache, MemoryCache, StoreError, _safe
|
|
20
|
+
from .prices import day_path, index_path, validate_day
|
|
21
|
+
|
|
22
|
+
Doc = dict[str, Any]
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class PriceStore:
|
|
26
|
+
"""Dynamic prices, read through `read` and kept in `cache`."""
|
|
27
|
+
|
|
28
|
+
def __init__(self, read: Callable[[str], bytes],
|
|
29
|
+
cache: MemoryCache | FolderCache | None = None) -> None:
|
|
30
|
+
self._read = read
|
|
31
|
+
self._cache = cache if cache is not None else MemoryCache()
|
|
32
|
+
|
|
33
|
+
def _parsed(self, path: str, raw: bytes) -> Doc:
|
|
34
|
+
try:
|
|
35
|
+
doc = json.loads(raw)
|
|
36
|
+
except ValueError as error:
|
|
37
|
+
raise StoreError(f"{path}: not JSON ({error})") from error
|
|
38
|
+
if not isinstance(doc, dict):
|
|
39
|
+
raise StoreError(f"{path}: not a JSON object")
|
|
40
|
+
return doc
|
|
41
|
+
|
|
42
|
+
def _fetch(self, path: str) -> bytes:
|
|
43
|
+
try:
|
|
44
|
+
return self._read(_safe(path))
|
|
45
|
+
except OSError as error:
|
|
46
|
+
raise StoreError(f"{path}: cannot be read ({error})") from error
|
|
47
|
+
|
|
48
|
+
def latest(self, country: str, feed: str, area: str) -> date | None:
|
|
49
|
+
"""The newest day the feed index lists, or None when it holds no day. Always read afresh."""
|
|
50
|
+
path = index_path(country, feed, area)
|
|
51
|
+
doc = self._parsed(path, self._fetch(path))
|
|
52
|
+
latest = doc.get("latest")
|
|
53
|
+
try:
|
|
54
|
+
return date.fromisoformat(latest) if latest else None
|
|
55
|
+
except (TypeError, ValueError):
|
|
56
|
+
raise StoreError(f"{path}: latest is not a date") from None
|
|
57
|
+
|
|
58
|
+
def day(self, country: str, feed: str, area: str, day: date) -> Doc:
|
|
59
|
+
"""The valid day file for one day. Raises `StoreError` when it cannot be read or checked."""
|
|
60
|
+
path = day_path(country, feed, area, day)
|
|
61
|
+
held = self._cache.get(path)
|
|
62
|
+
raw = held if held is not None else self._fetch(path)
|
|
63
|
+
doc = self._parsed(path, raw)
|
|
64
|
+
problems = validate_day(doc)
|
|
65
|
+
if not problems and (doc["feed"], doc["area"], doc["date"]) != (
|
|
66
|
+
feed, area, day.isoformat()):
|
|
67
|
+
problems = ["the file is for another feed, area or day"]
|
|
68
|
+
if problems:
|
|
69
|
+
raise StoreError(f"{path}: " + "; ".join(problems))
|
|
70
|
+
if held is None:
|
|
71
|
+
self._cache.put(path, raw)
|
|
72
|
+
return doc
|
|
73
|
+
|
|
74
|
+
def days(self, country: str, feed: str, area: str, first: date, # noqa: PLR0913
|
|
75
|
+
last: date) -> tuple[list[Doc], list[date]]:
|
|
76
|
+
"""(day files held, days missing) from `first` to `last`, both included, earliest first.
|
|
77
|
+
A day that cannot be read or is refused is missing."""
|
|
78
|
+
held: list[Doc] = []
|
|
79
|
+
missing: list[date] = []
|
|
80
|
+
day = first
|
|
81
|
+
while day <= last:
|
|
82
|
+
try:
|
|
83
|
+
held.append(self.day(country, feed, area, day))
|
|
84
|
+
except StoreError:
|
|
85
|
+
missing.append(day)
|
|
86
|
+
day += timedelta(days=1)
|
|
87
|
+
return held, missing
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
"""The stored format of dynamic prices: one file per feed, area and day, and a small index per feed.
|
|
2
|
+
|
|
3
|
+
Dynamic prices change every half hour, so they are written by a machine and cannot be reviewed one
|
|
4
|
+
by one. This module is the only definition of what a file may hold, and the update script writes
|
|
5
|
+
nothing it refuses. Standard library only. docs/format.md describes the format in words.
|
|
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.
|
|
9
|
+
"""
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import hashlib
|
|
13
|
+
import json
|
|
14
|
+
import re
|
|
15
|
+
from datetime import date, datetime, time, timedelta
|
|
16
|
+
from decimal import Decimal
|
|
17
|
+
from typing import Any
|
|
18
|
+
from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
|
|
19
|
+
|
|
20
|
+
DAY_KEYS = {"schema", "feed", "area", "date", "timezone", "interval_minutes", "prices"}
|
|
21
|
+
INTERVALS = (15, 30, 60)
|
|
22
|
+
DECIMAL = re.compile(r"^-?\d+(\.\d+)?$")
|
|
23
|
+
SLUG = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
|
|
24
|
+
DAY = re.compile(r"^\d{4}-\d{2}-\d{2}$")
|
|
25
|
+
# A price per kWh in the major currency unit. Wider than any real market, narrow enough to refuse
|
|
26
|
+
# a feed that switched to pence or to MWh.
|
|
27
|
+
LOW, HIGH = Decimal("-1"), Decimal("5")
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def day_path(country: str, feed: str, area: str, day: date | str) -> str:
|
|
31
|
+
"""`gb/octopus-agile/a/2026/11/17.json`, under the prices folder."""
|
|
32
|
+
year, month, dom = str(day).split("-")
|
|
33
|
+
return f"{country.lower()}/{feed}/{area}/{year}/{month}/{dom}.json"
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def index_path(country: str, feed: str, area: str) -> str:
|
|
37
|
+
return f"{country.lower()}/{feed}/{area}/index.json"
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def slots_in_day(day: date, timezone: str, interval_minutes: int) -> int:
|
|
41
|
+
"""How many intervals the local day has, which is fewer or more on a clock change."""
|
|
42
|
+
zone = ZoneInfo(timezone)
|
|
43
|
+
start = datetime.combine(day, time(0), zone).astimezone(ZoneInfo("UTC"))
|
|
44
|
+
end = datetime.combine(day + timedelta(days=1), time(0), zone).astimezone(ZoneInfo("UTC"))
|
|
45
|
+
return int((end - start).total_seconds() // (interval_minutes * 60))
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def validate_day(doc: Any) -> list[str]:
|
|
49
|
+
"""What is wrong with a day file, in plain words. An empty list means it may be stored."""
|
|
50
|
+
if not isinstance(doc, dict):
|
|
51
|
+
return ["the file must be an object"]
|
|
52
|
+
errors = [f"unknown field {k}" for k in sorted(set(doc) - DAY_KEYS)]
|
|
53
|
+
errors += [f"missing field {k}" for k in sorted(DAY_KEYS - set(doc))]
|
|
54
|
+
if errors:
|
|
55
|
+
return errors
|
|
56
|
+
errors = _labels(doc)
|
|
57
|
+
day = _day(doc["date"])
|
|
58
|
+
if day is None:
|
|
59
|
+
errors.append("date must be a calendar date, YYYY-MM-DD")
|
|
60
|
+
try:
|
|
61
|
+
ZoneInfo(str(doc["timezone"]))
|
|
62
|
+
except (ZoneInfoNotFoundError, ValueError):
|
|
63
|
+
errors.append("timezone must be an IANA zone")
|
|
64
|
+
return errors if errors else _prices(doc, day)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def _labels(doc: dict[str, Any]) -> list[str]:
|
|
68
|
+
errors = []
|
|
69
|
+
if doc["schema"] != 1:
|
|
70
|
+
errors.append("schema must be 1")
|
|
71
|
+
errors += [f"{k} must be a lower case slug" for k in ("feed", "area")
|
|
72
|
+
if not isinstance(doc[k], str) or not SLUG.match(doc[k])]
|
|
73
|
+
if doc["interval_minutes"] not in INTERVALS:
|
|
74
|
+
errors.append(f"interval_minutes must be one of {INTERVALS}")
|
|
75
|
+
return errors
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def _day(text: object) -> date | None:
|
|
79
|
+
if not isinstance(text, str) or not DAY.match(text):
|
|
80
|
+
return None
|
|
81
|
+
try:
|
|
82
|
+
return date.fromisoformat(text)
|
|
83
|
+
except ValueError:
|
|
84
|
+
return None
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def _prices(doc: dict[str, Any], day: date | None) -> list[str]:
|
|
88
|
+
prices = doc["prices"]
|
|
89
|
+
if not isinstance(prices, list) or not all(
|
|
90
|
+
isinstance(p, str) and DECIMAL.match(p) for p in prices):
|
|
91
|
+
return ["prices must be a list of decimal strings"]
|
|
92
|
+
errors = []
|
|
93
|
+
expected = slots_in_day(day, doc["timezone"], doc["interval_minutes"]) if day else 0
|
|
94
|
+
if len(prices) != expected:
|
|
95
|
+
errors.append(f"a {doc['interval_minutes']} minute day on {doc['date']} has {expected} "
|
|
96
|
+
f"prices, not {len(prices)}")
|
|
97
|
+
outside = [p for p in prices if not LOW <= Decimal(p) <= HIGH]
|
|
98
|
+
if outside:
|
|
99
|
+
errors.append(f"{len(outside)} prices are outside {LOW} to {HIGH} per kWh, "
|
|
100
|
+
f"for example {outside[0]}")
|
|
101
|
+
return errors
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def dumps_day(doc: dict[str, Any]) -> str:
|
|
105
|
+
"""The one way a day file is written: keys sorted, prices one per line, so a diff reads."""
|
|
106
|
+
head = {k: doc[k] for k in sorted(doc) if k != "prices"}
|
|
107
|
+
text = json.dumps(head, indent=2, ensure_ascii=False)[:-2]
|
|
108
|
+
body = ",\n".join(f" {json.dumps(p)}" for p in doc["prices"])
|
|
109
|
+
return f'{text},\n "prices": [\n{body}\n ]\n}}\n'
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def day_checksum(text: str) -> str:
|
|
113
|
+
return "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest()
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def month_checksum(days: dict[str, str]) -> str:
|
|
117
|
+
"""One checksum for a month, from its day checksums in date order."""
|
|
118
|
+
return day_checksum("\n".join(f"{day} {days[day]}" for day in sorted(days)))
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def feed_index(feed: str, area: str, days: dict[str, str]) -> dict[str, Any]:
|
|
122
|
+
"""The index of one feed and area: the latest day and a checksum for each month held."""
|
|
123
|
+
months: dict[str, dict[str, str]] = {}
|
|
124
|
+
for day, checksum in days.items():
|
|
125
|
+
months.setdefault(day[:7], {})[day] = checksum
|
|
126
|
+
return {"schema": 1, "feed": feed, "area": area, "latest": max(days) if days else None,
|
|
127
|
+
"months": {m: month_checksum(d) for m, d in sorted(months.items())}}
|