elec-tariffs 0.1.0__tar.gz

elec_tariffs-0.1.0/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    groups:
+      python:
+        patterns: ["*"]

elec_tariffs-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,9 @@
+## What changes
+
+## Why
+
+## How it was tested
+
+- [ ] `ruff check`, `ruff format --check` and `mypy` pass
+- [ ] `pytest --cov` passes and covers the change
+- [ ] README updated if the public API or behaviour changed

elec_tariffs-0.1.0/.github/release.yml

@@ -0,0 +1,12 @@
+changelog:
+  exclude:
+    labels: [ignore-for-release]
+  categories:
+    - title: Breaking changes
+      labels: [breaking-change]
+    - title: New features
+      labels: [enhancement]
+    - title: Bug fixes
+      labels: [bug]
+    - title: Other changes
+      labels: ["*"]

elec_tariffs-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint and types
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.14"
+          cache: pip
+          cache-dependency-path: requirements-dev.txt
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -r requirements-dev.txt -e .
+      - run: ruff check
+      - run: ruff format --check
+      - run: mypy
+
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.14"
+          cache: pip
+          cache-dependency-path: requirements-dev.txt
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -r requirements-dev.txt -e .
+      - run: pytest --cov --cov-report=term-missing
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.14"
+      - run: python -m pip install build==1.6.1
+      - run: python -m build
+      - name: Install the wheel in a clean environment
+        run: |
+          python -m venv /tmp/check
+          /tmp/check/bin/pip install dist/*.whl
+          /tmp/check/bin/python -c "import elec_tariffs; print(elec_tariffs.__version__)"

elec_tariffs-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions: {}
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.14"
+      - name: Check that the tag matches the version
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          version=$(python -c 'import runpy; print(runpy.run_path("src/elec_tariffs/_version.py")["__version__"])')
+          if [ "$TAG" != "v$version" ]; then
+            echo "Tag $TAG does not match version $version" >&2
+            exit 1
+          fi
+      - run: python -m pip install build==1.6.1
+      - run: python -m build
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/elec-tariffs
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

elec_tariffs-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.coverage
+coverage.xml
+htmlcov/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.env
+*.env

elec_tariffs-0.1.0/CLAUDE.md

@@ -0,0 +1,25 @@
+# elec-tariffs
+
+Library behind the Electricity Contracts Home Assistant integration (damou8/electricity_contracts). No Home Assistant import here.
+
+## Commands
+
+```bash
+.venv/bin/pip install -r requirements-dev.txt -e .
+.venv/bin/ruff check && .venv/bin/ruff format --check && .venv/bin/mypy
+.venv/bin/pytest --cov   # fails under 95 % coverage
+```
+
+## Conventions
+
+- Python 3.14, `mypy --strict`, ruff `ALL`. Annotations are lazy: no `TYPE_CHECKING` blocks.
+- Keep `aiohttp` in `requirements-dev.txt` at Home Assistant's pin (`homeassistant/package_constraints.txt`).
+- The version lives in `src/elec_tariffs/_version.py`; the release tag must be `v` + that version.
+- Tests make no network request: recorded answers in `tests/fixtures/`, HTTP through the `server` fixture (a local aiohttp server) and the clients' `base_url` / `urls` arguments.
+
+## Pitfalls
+
+- aioresponses 0.7.9 doesn't work with aiohttp 3.14 (`ClientResponse` needs `stream_writer`): don't bring it back.
+- aiohttp 3.14 deprecates `BasicAuth`; the official RTE client builds the header itself.
+- aiohttp retries a GET once when a reused connection drops: a test of a dropped connection must queue the failure twice.
+- The public RTE endpoint is undocumented. Keep its parsing strict (`TempoFormatError` on anything unexpected) rather than lenient.

elec_tariffs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 damou8
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

elec_tariffs-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: elec-tariffs
+Version: 0.1.0
+Summary: Cost French electricity consumption hour by hour under Base, HP/HC and Tempo contracts
+Project-URL: Homepage, https://github.com/damou8/elec-tariffs
+Project-URL: Issues, https://github.com/damou8/elec-tariffs/issues
+Author: damou8
+License-Expression: MIT
+License-File: LICENSE
+Keywords: edf,electricity,home-assistant,linky,rte,tariff,tempo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: aiohttp>=3.10
+Description-Content-Type: text/markdown
+
+# elec-tariffs
+
+Cost French electricity consumption hour by hour under Base, HP/HC and Tempo contracts.
+
+`elec-tariffs` takes hourly consumption (as a Linky meter reports it) and works out what it cost under one or more contracts: which tranche each hour falls into, its price on that day, and its share of the yearly subscription. It also downloads the data that needs:
+
+- the regulated prices (Tarif Bleu) of every period since 2012, from [data.gouv.fr](https://www.data.gouv.fr/fr/datasets/historique-des-tarifs-reglementes-de-vente-delectricite-pour-les-consommateurs-residentiels/);
+- the color of each Tempo day, from RTE.
+
+It is async (aiohttp), fully typed and has no dependency on Home Assistant. It was written for the [Electricity Contracts](https://github.com/damou8/electricity_contracts) Home Assistant integration.
+
+It is not affiliated with EDF, RTE or Enedis.
+
+## Install
+
+```bash
+pip install elec-tariffs
+```
+
+Python 3.14 or later.
+
+## Use
+
+```python
+import asyncio
+from datetime import date, datetime
+from zoneinfo import ZoneInfo
+
+import aiohttp
+
+from elec_tariffs import (
+    ContractKind,
+    ContractRules,
+    RtePublicTempoClient,
+    TrvClient,
+    cost_hour,
+)
+
+PARIS = ZoneInfo("Europe/Paris")
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        prices = await TrvClient(session).async_price_periods(ContractKind.TEMPO, 6)
+        colors = await RtePublicTempoClient(session).async_calendar(
+            date(2026, 1, 4), date(2026, 1, 5)
+        )
+
+    # 1.8 kWh used from 19:00 to 20:00 on 5 January 2026.
+    cost = cost_hour(
+        datetime(2026, 1, 5, 19, tzinfo=PARIS),
+        1.8,
+        ContractRules(kind=ContractKind.TEMPO),
+        prices,
+        colors,
+    )
+    print(cost.energy, cost.variable, cost.fixed, cost.total)
+
+
+asyncio.run(main())
+```
+
+An HP/HC contract takes its own off-peak ranges, to the half hour, and can make weekends off-peak:
+
+```python
+from datetime import time
+
+from elec_tariffs import ContractKind, ContractRules, TimeRange
+
+rules = ContractRules(
+    kind=ContractKind.HPHC,
+    off_peak=(
+        TimeRange(start=time(12, 30), end=time(14)),
+        TimeRange(start=time(22), end=time(6, 30)),
+    ),
+    weekend_off_peak=True,
+)
+```
+
+Prices you set yourself are `PricePeriod` objects: a first and last day (`None` while in force), the yearly fixed part and a price per tranche, all with taxes.
+
+## How an hour is costed
+
+- **Tranches.** Each hour is split into two half hours with half the energy each, so an off-peak range that starts or ends on a half hour is followed. This assumes the consumption is even within the hour.
+- **Tempo.** A Tempo day runs from 6:00 to 6:00, so a night takes the color of the day that started the evening before. Off-peak hours are 22:00 to 6:00.
+- **Prices** change at midnight on the first day of a price period (1 February and 1 August for the regulated prices). An hour uses the prices of its calendar day.
+- **Subscription.** The yearly fixed part is spread evenly over the hours of the year (8,760, or 8,784 in a leap year).
+- **Missing data.** An hour whose Tempo color or price isn't known raises `MissingColorError` or `MissingPriceError` instead of guessing.
+
+## Tempo calendar sources
+
+| Source | Account | Notes |
+| --- | --- | --- |
+| `RtePublicTempoClient` | none | The backend of RTE's public [Tempo calendar page](https://www.services-rte.com/fr/visualisez-les-donnees-publiees-par-rte/calendrier-des-offres-de-fourniture-de-type-tempo.html). It isn't documented and RTE can change it without notice, so its answers are checked strictly: an unexpected format raises `TempoFormatError` instead of giving wrong colors. |
+| `RteOfficialTempoClient` | free [data.rte-france.com](https://data.rte-france.com/catalog/-/api/consumption/Tempo-Like-Supply-Contract/v1.1) application | RTE's documented "Tempo Like Supply Contract" API, with OAuth2 client credentials. The token is kept until it expires and renewed once if refused. Long ranges are split into requests of 366 days at most. **Not yet tested against the live API**: its tests follow the format used by other clients. |
+
+`FallbackTempoSource` asks each source in turn, for example the public one first and the official one when it fails. It records which source answered and the errors of the others.
+
+Past colors never change, so callers should cache them and only ask for the current season and the next day.
+
+To create the official API application: sign up on data.rte-france.com, open the "Tempo Like Supply Contract" API, choose "S'abonner à l'API" (this creates an application), then copy its client ID and secret.
+
+## Errors
+
+Every error derives from `ElecTariffsError`:
+
+- `MissingColorError`, `MissingPriceError` (with the `day` concerned);
+- `TrvServerError`, `TrvFormatError` for data.gouv.fr;
+- `TempoServerError` (network or 5xx), `TempoRateLimitError` (429), `TempoAuthError` (credentials refused) and `TempoFormatError` for the Tempo sources.
+
+## Development
+
+```bash
+python3.14 -m venv .venv
+.venv/bin/pip install -r requirements-dev.txt -e .
+.venv/bin/ruff check && .venv/bin/ruff format --check && .venv/bin/mypy
+.venv/bin/pytest --cov
+```
+
+The tests use recorded answers in `tests/fixtures/` and a local HTTP server; they make no network requests.
+
+Releases are published to PyPI by GitHub Actions when a GitHub release is published; the tag (`vX.Y.Z`) must match `src/elec_tariffs/_version.py`.
+
+## License
+
+[MIT](LICENSE)

elec_tariffs-0.1.0/README.md

@@ -0,0 +1,126 @@
+# elec-tariffs
+
+Cost French electricity consumption hour by hour under Base, HP/HC and Tempo contracts.
+
+`elec-tariffs` takes hourly consumption (as a Linky meter reports it) and works out what it cost under one or more contracts: which tranche each hour falls into, its price on that day, and its share of the yearly subscription. It also downloads the data that needs:
+
+- the regulated prices (Tarif Bleu) of every period since 2012, from [data.gouv.fr](https://www.data.gouv.fr/fr/datasets/historique-des-tarifs-reglementes-de-vente-delectricite-pour-les-consommateurs-residentiels/);
+- the color of each Tempo day, from RTE.
+
+It is async (aiohttp), fully typed and has no dependency on Home Assistant. It was written for the [Electricity Contracts](https://github.com/damou8/electricity_contracts) Home Assistant integration.
+
+It is not affiliated with EDF, RTE or Enedis.
+
+## Install
+
+```bash
+pip install elec-tariffs
+```
+
+Python 3.14 or later.
+
+## Use
+
+```python
+import asyncio
+from datetime import date, datetime
+from zoneinfo import ZoneInfo
+
+import aiohttp
+
+from elec_tariffs import (
+    ContractKind,
+    ContractRules,
+    RtePublicTempoClient,
+    TrvClient,
+    cost_hour,
+)
+
+PARIS = ZoneInfo("Europe/Paris")
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        prices = await TrvClient(session).async_price_periods(ContractKind.TEMPO, 6)
+        colors = await RtePublicTempoClient(session).async_calendar(
+            date(2026, 1, 4), date(2026, 1, 5)
+        )
+
+    # 1.8 kWh used from 19:00 to 20:00 on 5 January 2026.
+    cost = cost_hour(
+        datetime(2026, 1, 5, 19, tzinfo=PARIS),
+        1.8,
+        ContractRules(kind=ContractKind.TEMPO),
+        prices,
+        colors,
+    )
+    print(cost.energy, cost.variable, cost.fixed, cost.total)
+
+
+asyncio.run(main())
+```
+
+An HP/HC contract takes its own off-peak ranges, to the half hour, and can make weekends off-peak:
+
+```python
+from datetime import time
+
+from elec_tariffs import ContractKind, ContractRules, TimeRange
+
+rules = ContractRules(
+    kind=ContractKind.HPHC,
+    off_peak=(
+        TimeRange(start=time(12, 30), end=time(14)),
+        TimeRange(start=time(22), end=time(6, 30)),
+    ),
+    weekend_off_peak=True,
+)
+```
+
+Prices you set yourself are `PricePeriod` objects: a first and last day (`None` while in force), the yearly fixed part and a price per tranche, all with taxes.
+
+## How an hour is costed
+
+- **Tranches.** Each hour is split into two half hours with half the energy each, so an off-peak range that starts or ends on a half hour is followed. This assumes the consumption is even within the hour.
+- **Tempo.** A Tempo day runs from 6:00 to 6:00, so a night takes the color of the day that started the evening before. Off-peak hours are 22:00 to 6:00.
+- **Prices** change at midnight on the first day of a price period (1 February and 1 August for the regulated prices). An hour uses the prices of its calendar day.
+- **Subscription.** The yearly fixed part is spread evenly over the hours of the year (8,760, or 8,784 in a leap year).
+- **Missing data.** An hour whose Tempo color or price isn't known raises `MissingColorError` or `MissingPriceError` instead of guessing.
+
+## Tempo calendar sources
+
+| Source | Account | Notes |
+| --- | --- | --- |
+| `RtePublicTempoClient` | none | The backend of RTE's public [Tempo calendar page](https://www.services-rte.com/fr/visualisez-les-donnees-publiees-par-rte/calendrier-des-offres-de-fourniture-de-type-tempo.html). It isn't documented and RTE can change it without notice, so its answers are checked strictly: an unexpected format raises `TempoFormatError` instead of giving wrong colors. |
+| `RteOfficialTempoClient` | free [data.rte-france.com](https://data.rte-france.com/catalog/-/api/consumption/Tempo-Like-Supply-Contract/v1.1) application | RTE's documented "Tempo Like Supply Contract" API, with OAuth2 client credentials. The token is kept until it expires and renewed once if refused. Long ranges are split into requests of 366 days at most. **Not yet tested against the live API**: its tests follow the format used by other clients. |
+
+`FallbackTempoSource` asks each source in turn, for example the public one first and the official one when it fails. It records which source answered and the errors of the others.
+
+Past colors never change, so callers should cache them and only ask for the current season and the next day.
+
+To create the official API application: sign up on data.rte-france.com, open the "Tempo Like Supply Contract" API, choose "S'abonner à l'API" (this creates an application), then copy its client ID and secret.
+
+## Errors
+
+Every error derives from `ElecTariffsError`:
+
+- `MissingColorError`, `MissingPriceError` (with the `day` concerned);
+- `TrvServerError`, `TrvFormatError` for data.gouv.fr;
+- `TempoServerError` (network or 5xx), `TempoRateLimitError` (429), `TempoAuthError` (credentials refused) and `TempoFormatError` for the Tempo sources.
+
+## Development
+
+```bash
+python3.14 -m venv .venv
+.venv/bin/pip install -r requirements-dev.txt -e .
+.venv/bin/ruff check && .venv/bin/ruff format --check && .venv/bin/mypy
+.venv/bin/pytest --cov
+```
+
+The tests use recorded answers in `tests/fixtures/` and a local HTTP server; they make no network requests.
+
+Releases are published to PyPI by GitHub Actions when a GitHub release is published; the tag (`vX.Y.Z`) must match `src/elec_tariffs/_version.py`.
+
+## License
+
+[MIT](LICENSE)

elec_tariffs-0.1.0/SECURITY.md

@@ -0,0 +1,6 @@
+# Security policy
+
+Only the latest release gets fixes.
+
+Report a vulnerability privately with the **Report a vulnerability** button in the
+repository's **Security** tab, not in a public issue.

elec_tariffs-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "elec-tariffs"
+dynamic = ["version"]
+description = "Cost French electricity consumption hour by hour under Base, HP/HC and Tempo contracts"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "damou8" }]
+requires-python = ">=3.14"
+dependencies = ["aiohttp>=3.10"]
+keywords = ["electricity", "tariff", "tempo", "edf", "rte", "linky", "home-assistant"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/damou8/elec-tariffs"
+Issues = "https://github.com/damou8/elec-tariffs/issues"
+
+[tool.hatch.version]
+path = "src/elec_tariffs/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/elec_tariffs"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+filterwarnings = ["error"]
+testpaths = ["tests"]
+addopts = "--strict-markers"
+
+[tool.coverage.run]
+source = ["elec_tariffs"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 95
+show_missing = true
+exclude_also = ["if TYPE_CHECKING:", "raise NotImplementedError", "\\.\\.\\."]
+
+[tool.mypy]
+strict = true
+python_version = "3.14"
+files = ["src", "tests"]
+
+[tool.ruff]
+target-version = "py314"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "ANN401",  # Any is needed for JSON payloads
+    "COM812",  # incompatible with the formatter
+    "CPY001",  # the license is in LICENSE
+    "D203",    # incompatible with D211
+    "D213",    # incompatible with D212
+    "ISC001",  # incompatible with the formatter
+    "TC",      # annotations are lazy since Python 3.14, no TYPE_CHECKING blocks
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",     # pytest asserts
+    "PLR2004",  # magic values are the expected results
+    "D103",     # test names say what they check
+    "SLF001",   # tests read private state on purpose
+]

elec_tariffs-0.1.0/requirements-dev.txt

@@ -0,0 +1,8 @@
+# Tools and test dependencies, pinned. aiohttp follows Home Assistant's pin.
+aiohttp==3.14.5
+build==1.6.1
+mypy==2.4.1
+pytest==9.2.0
+pytest-asyncio==1.4.1.post1
+pytest-cov==7.1.0
+ruff==0.17.4