utility-tariffs-lib 0.1.0__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 (81) hide show
  1. utility_tariffs_lib-0.1.0/LICENSE +21 -0
  2. utility_tariffs_lib-0.1.0/PKG-INFO +61 -0
  3. utility_tariffs_lib-0.1.0/README.md +81 -0
  4. utility_tariffs_lib-0.1.0/lib/README.md +41 -0
  5. utility_tariffs_lib-0.1.0/lib/__init__.py +0 -0
  6. utility_tariffs_lib-0.1.0/lib/py.typed +0 -0
  7. utility_tariffs_lib-0.1.0/lib/tariff/__init__.py +164 -0
  8. utility_tariffs_lib-0.1.0/lib/tariff/accumulator.py +195 -0
  9. utility_tariffs_lib-0.1.0/lib/tariff/bands.py +124 -0
  10. utility_tariffs_lib-0.1.0/lib/tariff/bill_days.py +73 -0
  11. utility_tariffs_lib-0.1.0/lib/tariff/billing.py +28 -0
  12. utility_tariffs_lib-0.1.0/lib/tariff/compile.py +124 -0
  13. utility_tariffs_lib-0.1.0/lib/tariff/config.py +208 -0
  14. utility_tariffs_lib-0.1.0/lib/tariff/defaults.py +16 -0
  15. utility_tariffs_lib-0.1.0/lib/tariff/definition.py +321 -0
  16. utility_tariffs_lib-0.1.0/lib/tariff/definition_parse.py +765 -0
  17. utility_tariffs_lib-0.1.0/lib/tariff/definition_savings.py +116 -0
  18. utility_tariffs_lib-0.1.0/lib/tariff/demand.py +44 -0
  19. utility_tariffs_lib-0.1.0/lib/tariff/engine.py +284 -0
  20. utility_tariffs_lib-0.1.0/lib/tariff/index.py +309 -0
  21. utility_tariffs_lib-0.1.0/lib/tariff/period_bill.py +136 -0
  22. utility_tariffs_lib-0.1.0/lib/tariff/periods.py +34 -0
  23. utility_tariffs_lib-0.1.0/lib/tariff/price_curve.py +142 -0
  24. utility_tariffs_lib-0.1.0/lib/tariff/price_series.py +137 -0
  25. utility_tariffs_lib-0.1.0/lib/tariff/price_stats.py +194 -0
  26. utility_tariffs_lib-0.1.0/lib/tariff/price_timeline.py +139 -0
  27. utility_tariffs_lib-0.1.0/lib/tariff/reprice.py +106 -0
  28. utility_tariffs_lib-0.1.0/lib/tariff/savings.py +118 -0
  29. utility_tariffs_lib-0.1.0/lib/tariff/slot_history.py +128 -0
  30. utility_tariffs_lib-0.1.0/lib/tariff/slots.py +266 -0
  31. utility_tariffs_lib-0.1.0/lib/tariff/stored_energy.py +64 -0
  32. utility_tariffs_lib-0.1.0/lib/tariff/windows.py +119 -0
  33. utility_tariffs_lib-0.1.0/lib/tariffranking/__init__.py +39 -0
  34. utility_tariffs_lib-0.1.0/lib/tariffranking/search.py +189 -0
  35. utility_tariffs_lib-0.1.0/lib/tariffstore/__init__.py +13 -0
  36. utility_tariffs_lib-0.1.0/lib/tariffstore/client.py +406 -0
  37. utility_tariffs_lib-0.1.0/lib/tariffstore/compile.py +157 -0
  38. utility_tariffs_lib-0.1.0/lib/tariffstore/index.py +188 -0
  39. utility_tariffs_lib-0.1.0/lib/tariffstore/layout.py +39 -0
  40. utility_tariffs_lib-0.1.0/lib/tariffstore/price_client.py +87 -0
  41. utility_tariffs_lib-0.1.0/lib/tariffstore/prices.py +127 -0
  42. utility_tariffs_lib-0.1.0/lib/tariffstore/schema.py +550 -0
  43. utility_tariffs_lib-0.1.0/lib/timeutil/__init__.py +5 -0
  44. utility_tariffs_lib-0.1.0/lib/timeutil/real_time.py +52 -0
  45. utility_tariffs_lib-0.1.0/pyproject.toml +69 -0
  46. utility_tariffs_lib-0.1.0/setup.cfg +4 -0
  47. utility_tariffs_lib-0.1.0/tests/test_build.py +124 -0
  48. utility_tariffs_lib-0.1.0/tests/test_client.py +388 -0
  49. utility_tariffs_lib-0.1.0/tests/test_compile.py +159 -0
  50. utility_tariffs_lib-0.1.0/tests/test_eia861_map.py +115 -0
  51. utility_tariffs_lib-0.1.0/tests/test_end_to_end.py +154 -0
  52. utility_tariffs_lib-0.1.0/tests/test_index.py +129 -0
  53. utility_tariffs_lib-0.1.0/tests/test_lib_release_notes.py +42 -0
  54. utility_tariffs_lib-0.1.0/tests/test_packaging.py +33 -0
  55. utility_tariffs_lib-0.1.0/tests/test_price_client.py +90 -0
  56. utility_tariffs_lib-0.1.0/tests/test_price_format.py +74 -0
  57. utility_tariffs_lib-0.1.0/tests/test_prices.py +142 -0
  58. utility_tariffs_lib-0.1.0/tests/test_prices_comed.py +90 -0
  59. utility_tariffs_lib-0.1.0/tests/test_prices_energinet.py +88 -0
  60. utility_tariffs_lib-0.1.0/tests/test_prices_energy_charts.py +94 -0
  61. utility_tariffs_lib-0.1.0/tests/test_prices_energyzero.py +75 -0
  62. utility_tariffs_lib-0.1.0/tests/test_prices_runner.py +34 -0
  63. utility_tariffs_lib-0.1.0/tests/test_repo_rules.py +112 -0
  64. utility_tariffs_lib-0.1.0/tests/test_schema.py +381 -0
  65. utility_tariffs_lib-0.1.0/tests/test_sources_dk.py +92 -0
  66. utility_tariffs_lib-0.1.0/tests/test_sources_electric_ireland.py +234 -0
  67. utility_tariffs_lib-0.1.0/tests/test_sources_gb.py +304 -0
  68. utility_tariffs_lib-0.1.0/tests/test_sources_hq.py +118 -0
  69. utility_tariffs_lib-0.1.0/tests/test_sources_ie.py +203 -0
  70. utility_tariffs_lib-0.1.0/tests/test_sources_other.py +380 -0
  71. utility_tariffs_lib-0.1.0/tests/test_sources_pt.py +165 -0
  72. utility_tariffs_lib-0.1.0/tests/test_sources_us.py +132 -0
  73. utility_tariffs_lib-0.1.0/tests/test_stored_tariffs.py +130 -0
  74. utility_tariffs_lib-0.1.0/tests/test_sync_core.py +275 -0
  75. utility_tariffs_lib-0.1.0/tests/test_sync_run.py +162 -0
  76. utility_tariffs_lib-0.1.0/tests/test_tariffs_through_lib.py +600 -0
  77. utility_tariffs_lib-0.1.0/tests/test_urdb_convert.py +263 -0
  78. utility_tariffs_lib-0.1.0/utility_tariffs_lib.egg-info/PKG-INFO +61 -0
  79. utility_tariffs_lib-0.1.0/utility_tariffs_lib.egg-info/SOURCES.txt +79 -0
  80. utility_tariffs_lib-0.1.0/utility_tariffs_lib.egg-info/dependency_links.txt +1 -0
  81. utility_tariffs_lib-0.1.0/utility_tariffs_lib.egg-info/top_level.txt +1 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 macuistin
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,61 @@
1
+ Metadata-Version: 2.4
2
+ Name: utility-tariffs-lib
3
+ Version: 0.1.0
4
+ Summary: Tariff model, bill engine, price series, store client and plan ranking
5
+ Author: macuistin
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/macuistin/utility-tariffs
8
+ Project-URL: Issues, https://github.com/macuistin/utility-tariffs/issues
9
+ Project-URL: Changelog, https://github.com/macuistin/utility-tariffs/releases
10
+ Keywords: tariff,electricity,energy,billing,home-assistant
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3.14
14
+ Classifier: Topic :: Software Development :: Libraries
15
+ Classifier: Typing :: Typed
16
+ Requires-Python: >=3.14
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Dynamic: license-file
20
+
21
+ # lib/
22
+
23
+ The store library and the bill engine. This repository is where both are written and tested, and
24
+ it is the source of truth for all tariff and billing code and calculations. They use only the
25
+ standard library, so any script, skill or integration can import or copy them.
26
+
27
+ | Folder | What it holds |
28
+ | --- | --- |
29
+ | `tariff/` | The tariff definition reader, the bill engine, band assignment, half-hourly slots and repricing. `tariff/README.md` lists the public names |
30
+ | `tariffstore/` | The store's own code: validator, checksum, index build, compile step and the client (`Store`) |
31
+ | `tariffranking/` | Prices every plan over the same measured usage and ranks them, with the current plan's rank. Imports `tariff/` only |
32
+ | `timeutil/` | Clock helpers that `tariff/` imports (`shift_real`, `elapsed_seconds`, `local_time_on`) |
33
+
34
+ ## Using it from another project
35
+
36
+ Copy the folders as they stand and do not edit the copy. Record the commit copied, so a
37
+ later copy can be compared. The Home Assistant integration `macuistin/givenergy_inverter_manager`
38
+ does this with a script, a weekly workflow that opens a pull request, and a release check. Change
39
+ the code here, with its tests, and let the copy follow.
40
+
41
+ `tariff/` and `timeutil/` began in that integration and moved here on 2026-11-11, unchanged from
42
+ its commit `68ec1923ac68817032dfaa51cc3c82817d2ce115`.
43
+
44
+ The code uses Python 3.14 syntax (for example `except A, B:`), so it needs Python 3.14 or newer.
45
+
46
+ ## Known gaps between the tariff files and the engine
47
+
48
+ Found by `tests/test_tariffs_through_lib.py`. A tariff file is not what the engine reads. The
49
+ compile step (`lib/tariffstore/compile.py`) builds the library's definition from a tariff file and its
50
+ country block, and closes most gaps itself. What remains is work in `lib/tariff`.
51
+
52
+ 1. The library accepts only ISO 3166-2 region codes. Our area `region` codes (`GSP-A`,
53
+ `OFGEM-EASTERN`) are not, so compile leaves the region null. A customer's region is chosen by the
54
+ area key.
55
+ 2. Closed. The library prices an export by time of day (export
56
+ `zones`), so Prime Outgoing's 16:00 to 19:00 rate is credited by band.
57
+ 3. The library requires an `export` price in every definition. With no export file paired, compile
58
+ supplies 0 and adds no export line, so an unpaired tariff credits nothing. The library cannot say
59
+ "unknown".
60
+ 4. A bill period is a whole number of calendar months. The library has no period of a fixed
61
+ number of days, and no volume tiers, demand charges or dynamic prices. `docs/design.md` lists what each would need.
@@ -0,0 +1,81 @@
1
+ # Tariff prices
2
+
3
+ Open, versioned electricity tariff definitions, an index to find them by country, provider and
4
+ tariff, and a small library that fetches one, checks it and hands it to a bill engine. Each tariff
5
+ is a JSON document. No tariff contains code or formulas.
6
+
7
+ ## Layout
8
+
9
+ | Path | Role |
10
+ | --- | --- |
11
+ | `tariffs/electricity/index.json` | The countries index: each country's index path, checksum and counts. Generated |
12
+ | `tariffs/electricity/<cc>/index.json` | One country: its shared values at the top (currency, time zone, VAT, standard bill), edited by hand, then `providers`, the tariff collection, generated. Holds no prices |
13
+ | `tariffs/electricity/<cc>/<provider>/<tariff>/<n>.json` | One revision of one tariff: name, provider, dates, source, bands, one row of rates per area |
14
+ | `lib/tariffstore/` | The format in code: validator, checksum, index build, compile step and the client. Standard library only. Scripts and clients share it |
15
+ | `lib/tariff/`, `lib/timeutil/` | The bill engine: the tariff model, bill maths, bands, half-hourly slots and repricing. Written here, and copied by the projects that use it. See `lib/README.md` |
16
+ | `scripts/` | `build` (write or check the indexes) and `sync` (read the sources). See `scripts/README.md` |
17
+ | `sources/` | One note per upstream source: what it covers, how it is read, how often |
18
+ | `.github/workflows/` | `ci.yml` checks every change. `sync.yml` runs the sources on a schedule and opens a pull request |
19
+ | `docs/` | `using-the-library.md` (how to use it end to end), `format.md` (the files), `diagrams.md` (the flows), `design.md` (why it is this way, what runs where, what is not built) |
20
+ | `tests/` | Tests for the library, the scripts and every stored tariff |
21
+ | `CONTRIBUTING.md`, `CLAUDE.md`, `.claude/rules/` | How to change the store, how things are named, and the rules for AI assistants (`AGENTS.md` is the same file) |
22
+
23
+ ## Rules
24
+
25
+ 1. **Definitions are data.** Unknown or malformed fields are refused, not repaired.
26
+ 2. **Money is exact.** Prices are decimal strings, never floats.
27
+ 3. **Revisions are permanent.** A price change is a new numbered file. A published file is never
28
+ edited, except to add `effective_to` when a tariff is withdrawn. CI enforces this.
29
+ 4. **Every tariff names its source.** Each file carries the source id and the link it was read from.
30
+ 5. **The indexes are built** from the files and nothing else, so the same files always give the
31
+ same bytes. CI fails if a committed index differs from a fresh build.
32
+ 6. **Changes arrive as pull requests** that pass CI. A synced change is never merged without review.
33
+
34
+ ## Using it from a library
35
+
36
+ `docs/using-the-library.md` takes the library from install to a ranked list of plans, including bills, price series and percentiles, and the sync and release. The short version is below.
37
+
38
+ ```python
39
+ from datetime import date
40
+ from lib.tariffstore import Store, url_reader
41
+
42
+ store = Store(url_reader("https://raw.githubusercontent.com/<owner>/<repo>/main/tariffs/electricity"))
43
+ store.countries() # {"GB": {"availability": "available", ...}, ...}
44
+ store.providers("GB") # {"octopus-energy": "Octopus Energy", ...}
45
+ store.tariffs("GB", "octopus-energy") # {"octopus-var-22-11-01": "Flexible Octopus", ...}
46
+ store.areas("GB", "octopus-energy", "octopus-var-22-11-01", date.today()) # {"a": "Eastern England (A)", ...}
47
+ definition = store.definition("GB", "octopus-energy", "octopus-var-22-11-01", date.today(), area="c")
48
+ ```
49
+
50
+ `definition` is the document `lib.tariff.load_definition` reads, so the next line prices a bill
51
+ (`price_bill`) or the half-hourly history (`price_period`). Every file is checked against the
52
+ checksum in the level above it before it is used. `docs/design.md` has the details.
53
+
54
+ Keep what is fetched on disk, so a tariff is downloaded once and still works with no network:
55
+
56
+ ```python
57
+ store = Store.cached("https://raw.githubusercontent.com/<owner>/<repo>/main/tariffs/electricity",
58
+ "/path/to/cache")
59
+ store.fetch_country("IE", on=date.today()) # every tariff on offer, to compare bills
60
+ ```
61
+
62
+ Price a tariff the store does not hold. It is written like a tariff file, and the country's
63
+ currency, time zone, tax and standard bill come from the store:
64
+
65
+ ```python
66
+ mine = {"name": "My tariff", "effective_from": "2026-01-01",
67
+ "bands": [{"name": "Day"}, {"name": "Night", "hours": "23:00-08:00"}],
68
+ "areas": {"all": {"standing": "0.90", "rates": {"Day": "0.31", "Night": "0.14"}}}}
69
+ definition = store.custom_definition("IE", mine, date.today())
70
+ ```
71
+
72
+ ## Working on it
73
+
74
+ python3 -m scripts.build # rewrite the indexes after editing a tariff or a country block
75
+ python3 -m scripts.build --check # what CI runs
76
+ python3 -m scripts.sync all # read every source and write new revisions
77
+ python3 -m pytest tests -q # needs Python 3.14 and pytest
78
+
79
+ ## Licence
80
+
81
+ The code and the tariff files in this repository are under the MIT licence (`LICENSE`). See `docs/licence.md` for what that covers.
@@ -0,0 +1,41 @@
1
+ # lib/
2
+
3
+ The store library and the bill engine. This repository is where both are written and tested, and
4
+ it is the source of truth for all tariff and billing code and calculations. They use only the
5
+ standard library, so any script, skill or integration can import or copy them.
6
+
7
+ | Folder | What it holds |
8
+ | --- | --- |
9
+ | `tariff/` | The tariff definition reader, the bill engine, band assignment, half-hourly slots and repricing. `tariff/README.md` lists the public names |
10
+ | `tariffstore/` | The store's own code: validator, checksum, index build, compile step and the client (`Store`) |
11
+ | `tariffranking/` | Prices every plan over the same measured usage and ranks them, with the current plan's rank. Imports `tariff/` only |
12
+ | `timeutil/` | Clock helpers that `tariff/` imports (`shift_real`, `elapsed_seconds`, `local_time_on`) |
13
+
14
+ ## Using it from another project
15
+
16
+ Copy the folders as they stand and do not edit the copy. Record the commit copied, so a
17
+ later copy can be compared. The Home Assistant integration `macuistin/givenergy_inverter_manager`
18
+ does this with a script, a weekly workflow that opens a pull request, and a release check. Change
19
+ the code here, with its tests, and let the copy follow.
20
+
21
+ `tariff/` and `timeutil/` began in that integration and moved here on 2026-11-11, unchanged from
22
+ its commit `68ec1923ac68817032dfaa51cc3c82817d2ce115`.
23
+
24
+ The code uses Python 3.14 syntax (for example `except A, B:`), so it needs Python 3.14 or newer.
25
+
26
+ ## Known gaps between the tariff files and the engine
27
+
28
+ Found by `tests/test_tariffs_through_lib.py`. A tariff file is not what the engine reads. The
29
+ compile step (`lib/tariffstore/compile.py`) builds the library's definition from a tariff file and its
30
+ country block, and closes most gaps itself. What remains is work in `lib/tariff`.
31
+
32
+ 1. The library accepts only ISO 3166-2 region codes. Our area `region` codes (`GSP-A`,
33
+ `OFGEM-EASTERN`) are not, so compile leaves the region null. A customer's region is chosen by the
34
+ area key.
35
+ 2. Closed. The library prices an export by time of day (export
36
+ `zones`), so Prime Outgoing's 16:00 to 19:00 rate is credited by band.
37
+ 3. The library requires an `export` price in every definition. With no export file paired, compile
38
+ supplies 0 and adds no export line, so an unpaired tariff credits nothing. The library cannot say
39
+ "unknown".
40
+ 4. A bill period is a whole number of calendar months. The library has no period of a fixed
41
+ number of days, and no volume tiers, demand charges or dynamic prices. `docs/design.md` lists what each would need.
File without changes
File without changes
@@ -0,0 +1,164 @@
1
+ """Tariff model, energy and cost accumulation, and bill maths. No knowledge of Home Assistant."""
2
+
3
+ from .accumulator import CounterMemory, EnergyAccumulator
4
+ from .bands import band_at, export_band_at, export_by_band, no_holidays
5
+ from .billing import BillBreakdown, money
6
+ from .compile import Locale, definition_from_config
7
+ from .config import TariffConfig, cheapest_period
8
+ from .definition import SCHEMA_VERSION, DefinitionError, TariffDefinition
9
+ from .definition_parse import load_definition, parse_definition
10
+ from .definition_savings import DefinitionSavings, SavingsOptions, definition_savings
11
+ from .demand import peak_kw_by_window
12
+ from .engine import (
13
+ BillInputs,
14
+ CheckFailed,
15
+ Line,
16
+ MissingPeak,
17
+ MissingSeries,
18
+ PricedBill,
19
+ price_bill,
20
+ verify_checks,
21
+ )
22
+ from .index import (
23
+ ChecksumMismatch,
24
+ StaticSource,
25
+ TariffIndex,
26
+ TariffSource,
27
+ build_index,
28
+ checksum_of,
29
+ find_tariff,
30
+ load_revision,
31
+ parse_index,
32
+ revision_in_force,
33
+ )
34
+ from .period_bill import (
35
+ PeriodBill,
36
+ PeriodRules,
37
+ bill_period_bounds,
38
+ months_of,
39
+ price_period,
40
+ start_day_of,
41
+ start_month_of,
42
+ )
43
+ from .periods import RatePeriod
44
+ from .price_curve import MarginalPrices, PriceSlot, marginal_prices, price_curve
45
+ from .price_series import (
46
+ MissingPrice,
47
+ PriceSeries,
48
+ feed_of,
49
+ series_cost,
50
+ series_from_days,
51
+ series_names,
52
+ series_runs,
53
+ )
54
+ from .price_stats import (
55
+ HistoryPercentiles,
56
+ PriceStats,
57
+ history_percentiles,
58
+ next_at_or_below,
59
+ price_level,
60
+ price_percentiles,
61
+ price_rating,
62
+ price_stats,
63
+ )
64
+ from .price_timeline import Revision, known_until, price_timeline, series_curve, series_factor
65
+ from .reprice import BillPeriod, Repriced, Rounding, import_by_band, reprice
66
+ from .savings import Battery, Savings, savings
67
+ from .slot_history import SlotHistory
68
+ from .slots import DEFAULT_LOADS, FLOWS, SlotDay, SlotEnergy, StoredSlotDay
69
+ from .stored_energy import StoredEnergy, stored_energy_change, value_per_stored_kwh
70
+ from .windows import Window, WindowSearch, find_window
71
+
72
+ __all__ = [
73
+ "SCHEMA_VERSION",
74
+ "ChecksumMismatch",
75
+ "StaticSource",
76
+ "TariffIndex",
77
+ "TariffSource",
78
+ "build_index",
79
+ "checksum_of",
80
+ "find_tariff",
81
+ "load_revision",
82
+ "parse_index",
83
+ "revision_in_force",
84
+ "Locale",
85
+ "definition_from_config",
86
+ "band_at",
87
+ "export_band_at",
88
+ "export_by_band",
89
+ "no_holidays",
90
+ "DefinitionSavings",
91
+ "SavingsOptions",
92
+ "definition_savings",
93
+ "PeriodBill",
94
+ "PeriodRules",
95
+ "bill_period_bounds",
96
+ "price_period",
97
+ "start_day_of",
98
+ "months_of",
99
+ "start_month_of",
100
+ "BillInputs",
101
+ "CheckFailed",
102
+ "Line",
103
+ "MissingPeak",
104
+ "MissingPrice",
105
+ "MissingSeries",
106
+ "PriceSeries",
107
+ "series_cost",
108
+ "series_from_days",
109
+ "PricedBill",
110
+ "peak_kw_by_window",
111
+ "price_bill",
112
+ "verify_checks",
113
+ "BillPeriod",
114
+ "DefinitionError",
115
+ "TariffDefinition",
116
+ "load_definition",
117
+ "parse_definition",
118
+ "MarginalPrices",
119
+ "PriceSlot",
120
+ "marginal_prices",
121
+ "price_curve",
122
+ "HistoryPercentiles",
123
+ "Revision",
124
+ "feed_of",
125
+ "history_percentiles",
126
+ "known_until",
127
+ "next_at_or_below",
128
+ "price_level",
129
+ "price_percentiles",
130
+ "price_timeline",
131
+ "series_curve",
132
+ "series_factor",
133
+ "series_names",
134
+ "series_runs",
135
+ "PriceStats",
136
+ "price_rating",
137
+ "price_stats",
138
+ "Battery",
139
+ "Savings",
140
+ "savings",
141
+ "Window",
142
+ "WindowSearch",
143
+ "find_window",
144
+ "Repriced",
145
+ "Rounding",
146
+ "import_by_band",
147
+ "reprice",
148
+ "BillBreakdown",
149
+ "CounterMemory",
150
+ "EnergyAccumulator",
151
+ "DEFAULT_LOADS",
152
+ "FLOWS",
153
+ "RatePeriod",
154
+ "SlotDay",
155
+ "SlotEnergy",
156
+ "SlotHistory",
157
+ "StoredSlotDay",
158
+ "StoredEnergy",
159
+ "TariffConfig",
160
+ "cheapest_period",
161
+ "money",
162
+ "stored_energy_change",
163
+ "value_per_stored_kwh",
164
+ ]
@@ -0,0 +1,195 @@
1
+ """accumulator.py: running energy and cost totals for a billing period."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass, field
6
+ from datetime import datetime
7
+
8
+
9
+ @dataclass
10
+ class CounterMemory:
11
+ """The last reading of each inverter daily counter, and which ones to stop trusting.
12
+
13
+ A daily counter drops to zero at midnight. The memory outlives the midnight reset so a
14
+ stale reading just after it is not added a second time. lib/guards/counter.py judges each
15
+ reading against this memory.
16
+
17
+ Only the AC charge baseline is saved. The other readings, their times and the list of
18
+ counters that jumped live in memory, so a restart starts them fresh.
19
+ """
20
+
21
+ ac_charge_kwh: float = 0.0
22
+ readings: dict[str, tuple[float, datetime]] = field(
23
+ default_factory=dict, compare=False, repr=False
24
+ )
25
+ distrusted: set[str] = field(default_factory=set, compare=False, repr=False)
26
+ # The last reading of each counter that passed, to recognise a counter coming back.
27
+ last_trusted: dict[str, tuple[float, datetime]] = field(
28
+ default_factory=dict, compare=False, repr=False
29
+ )
30
+ # The AC charge rise the last screening allowed. It is the only rise that is booked.
31
+ ac_charge_rise_kwh: float = field(default=0.0, compare=False, repr=False)
32
+
33
+
34
+ @dataclass
35
+ class EnergyAccumulator:
36
+ """
37
+ Tracks energy and cost accumulation over a billing period (resets at midnight).
38
+
39
+ Fields are grouped by what they enable:
40
+ Basic flows — solar, import, export, house, zappi, immersion
41
+ Rate breakdown — import split by cheap (timed) vs peak (base) rate
42
+ Cost attribution — cost per load type and per rate tier
43
+ Savings — value delivered by the integration
44
+ Battery health — throughput for cycle and depreciation tracking
45
+ """
46
+
47
+ # ── Basic energy flows ────────────────────────────────────────────────────
48
+ import_kwh: float = 0.0
49
+ export_kwh: float = 0.0
50
+ solar_kwh: float = 0.0
51
+ battery_discharge_kwh: float = 0.0
52
+ battery_charge_kwh: float = 0.0
53
+ zappi_kwh: float = 0.0
54
+ immersion_kwh: float = 0.0
55
+ house_kwh: float = 0.0
56
+ # The part of import_kwh that went into the battery (the inverter's AC charge counter). It is
57
+ # stored, not used, so it does not count as the grid supplying the house.
58
+ grid_to_battery_kwh: float = 0.0
59
+ # What the grid energy that went into the battery cost, and the kWh that cost covers. Both
60
+ # are kept by the integration from the moment it prices the AC charge counter, so
61
+ # grid_to_battery_priced_kwh can be less than grid_to_battery_kwh on the day it is
62
+ # first installed. Today's accumulator only. See core/stored_energy.py.
63
+ grid_to_battery_cost: float = 0.0
64
+ grid_to_battery_priced_kwh: float = 0.0
65
+ # The battery's state of charge at the start of the period, None until the first reading.
66
+ # A bookmark, not an accumulated figure, so it is left out of equality: a period with
67
+ # nothing else on it still counts as empty.
68
+ soc_at_start_pct: float | None = field(default=None, compare=False)
69
+
70
+ # ── Rate-tier import breakdown ────────────────────────────────────────────
71
+ # "cheap" = any timed rate period active (Night, Nightboost, etc.)
72
+ # "peak" = base/day rate (no timed period active)
73
+ import_kwh_cheap: float = 0.0 # kWh imported at timed cheap rate
74
+ import_kwh_peak: float = 0.0 # kWh imported at base/peak rate
75
+ import_cost_cheap: float = 0.0 # cost at cheap rate
76
+ import_cost_peak: float = 0.0 # cost at peak rate
77
+
78
+ # ── Cost attribution per rate period and load ─────────────────────────────
79
+ import_cost_by_period: dict[str, float] = field(default_factory=dict)
80
+ # kWh imported, and kWh the house used, in each rate period. They are what the bill audit
81
+ # lists beside the cost, and are empty on a period that began before they were kept.
82
+ import_kwh_by_period: dict[str, float] = field(default_factory=dict)
83
+ house_kwh_by_period: dict[str, float] = field(default_factory=dict)
84
+ export_earnings: float = 0.0
85
+ zappi_cost: float = 0.0
86
+ immersion_cost: float = 0.0 # import cost attributable to immersion heater
87
+ house_cost: float = 0.0 # import cost attributable to rest-of-house load
88
+
89
+ # ── Counterfactual ────────────────────────────────────────────────────────
90
+ # What the house load would have cost bought from the grid at the rate in force
91
+ # when it ran. The saving from solar and battery is this minus what was paid.
92
+ grid_equivalent_load_cost: float = 0.0
93
+
94
+ # ── Integration savings ───────────────────────────────────────────────────
95
+ # immersion_solar_kwh: solar kWh diverted to immersion that would otherwise
96
+ # have been exported at the lower export rate.
97
+ # immersion_savings: (import_rate - export_rate) × immersion_solar_kwh
98
+ immersion_solar_kwh: float = 0.0
99
+ immersion_savings: float = 0.0
100
+
101
+ # ── Battery throughput ────────────────────────────────────────────────────
102
+ # Total kWh cycled through the battery (in + out). Divide by 2 × capacity
103
+ # to get fractional cycles. Multiply by (replacement_cost / rated_cycles)
104
+ # to estimate depreciation cost.
105
+ battery_throughput_kwh: float = 0.0
106
+
107
+ # ── Missed solar (self-consumption opportunity) ───────────────────────────
108
+ # kWh exported while battery is full, solar generating, and no flex load
109
+ # active — represents solar that could have been self-consumed.
110
+ missed_solar_kwh: float = 0.0
111
+
112
+ # ── Inverter derating ──────────────────────────────────────────────────────
113
+ # Minutes the inverter spent above the derating temperature threshold today.
114
+ inverter_derating_minutes: float = 0.0
115
+
116
+ @property
117
+ def total_import_cost(self) -> float:
118
+ return sum(self.import_cost_by_period.values())
119
+
120
+ @property
121
+ def total_cost(self) -> float:
122
+ """Total import cost today (standing charges tracked separately in accrued_bill)."""
123
+ return self.total_import_cost
124
+
125
+ @property
126
+ def net_position(self) -> float:
127
+ """Negative = net cost, positive = net earnings."""
128
+ return self.export_earnings - self.total_cost
129
+
130
+ @property
131
+ def peak_import_fraction(self) -> float:
132
+ """Fraction of import that occurred at peak (base) rate. 0–1."""
133
+ total = self.import_kwh
134
+ return (self.import_kwh_peak / total) if total > 0 else 0.0
135
+
136
+ @property
137
+ def cheap_import_fraction(self) -> float:
138
+ """Fraction of import that occurred at cheap (timed) rate. 0–1."""
139
+ total = self.import_kwh
140
+ return (self.import_kwh_cheap / total) if total > 0 else 0.0
141
+
142
+ @property
143
+ def grid_to_house_kwh(self) -> float:
144
+ """Import that went to the house, not into the battery. Never negative.
145
+
146
+ Without a grid-to-battery reading the figure is the whole import.
147
+ """
148
+ return max(0.0, self.import_kwh - self.grid_to_battery_kwh)
149
+
150
+ @property
151
+ def supplied_without_grid_kwh(self) -> float:
152
+ """The house load not drawn from the grid at the time: solar, and battery discharge."""
153
+ return max(0.0, self.house_kwh - self.grid_to_house_kwh)
154
+
155
+ @property
156
+ def self_sufficiency_pct(self) -> float:
157
+ """Percentage of the house's consumption that did not have to be drawn from the grid.
158
+
159
+ house_kwh is the whole load, EV and immersion included, so they are not added again.
160
+ Grid energy the battery stored (grid_to_battery_kwh) is not counted against it.
161
+ Later discharge of that stored energy counts as supplied from storage. EV and
162
+ immersion energy bought from the grid is in house_kwh, so it still counts as grid.
163
+ With no grid-to-battery reading, all import counts, as it did before the reading
164
+ existed.
165
+ """
166
+ if self.house_kwh <= 0:
167
+ return 100.0
168
+ return max(0.0, min(100.0, (1 - self.grid_to_house_kwh / self.house_kwh) * 100))
169
+
170
+ @property
171
+ def solar_share_pct(self) -> float:
172
+ """Percentage of the house's consumption met by solar generated and kept on site.
173
+
174
+ Solar kept on site is generation less export. It includes solar stored in the
175
+ battery, which counts when it is generated, not when it is later discharged.
176
+ It does not count battery discharge, so energy the battery took from the grid
177
+ never raises the figure. It ignores grid import, so buying cheap energy does not
178
+ lower it. Compare self_sufficiency_pct, which counts all the house did not draw from the
179
+ grid.
180
+
181
+ house_kwh is the whole load, EV and immersion included, so they are not added again.
182
+ With no consumption the share is 0, not 100 as for self-sufficiency: no solar was
183
+ used, and a day with nothing to power should not read as fully solar powered.
184
+ """
185
+ if self.house_kwh <= 0:
186
+ return 0.0
187
+ solar_kept_kwh = max(0.0, self.solar_kwh - self.export_kwh)
188
+ return min(100.0, solar_kept_kwh / self.house_kwh * 100)
189
+
190
+ @property
191
+ def self_consumption_pct(self) -> float:
192
+ """Percentage of solar generation consumed on-site."""
193
+ if self.solar_kwh == 0:
194
+ return 0.0
195
+ return min(100.0, (1 - self.export_kwh / self.solar_kwh) * 100)