Skip to main content

Energy cost

Python package to model your energy bill based on your energy consumption.

This energy bill is calculated based on a Contract or even a ContractHistory, which is a collection of contracts that can change over time. A contract consists of 5 parts:

  • supplier: the Tariff of your energy supplier
  • distributor: the Tariff of your energy distributor
  • fees: the government fees applicable to you, als defined as a Tariff
  • taxes: the government Taxes applicable to each cost component of your bill
  • timezone: the timezone in which all calculations will be done

You can also specify a region, connection_type, customer_type and distributor_key in your contract, which will automatically fetch the applicable distributor tariffs, fees, taxes and timezone for you from our built in data. If your region is not yet supported, you can contribute the data for your region, see CONTRIBUTING.md for how to do that.

Contracts can be defined in a yaml file, which makes it easy to manage and update your contract over time. See notebooks/contract.ipynb for more info on how to define your contract in a yaml file.

We also have more detailed documentation on the different components of a contract, see notebooks for all available notebooks. You can find example yaml files for tariffs and taxes in the examples directory.

A lot of tariffs are based on an Index, which is a price that changes over time based on the market price of energy, see notebooks/index.ipynb for more info. Indexes and suppliers are registered by name in a global registry; to use separate sets in one process, see the Catalog section in notebooks/contract.ipynb.

Note on units: all consumption based costs are in €/MWh, all energy values are in MWh. All monetary values are in €.

Note on timezones: every method that takes timestamps as input also takes a timezone as input. All timestamps will be aligned to this timezone, and all outputs will be in this timezone as well. By default, the timezone is set by the regional data, but you can override it in your contract if needed.

Example usage

You can define your contract in a yaml file like this:

supplier:
- start: 2025-01-01T00:00:00+01:00
  consumption:
    constant_cost: 90.0
region: be_flanders
connection_type: electricity
customer_type: residential
distributor_key: fluvius_imewo

Then, you can use the Contract class to calculate your costs based on your consumption data:

from energy_cost import Contract, Meter, TimeseriesFrame

contract = Contract.from_yaml("../examples/contracts/inline.yml")

consumption = Meter(
    measurements=TimeseriesFrame(
        {
            "timestamp": pd.date_range("2024-01-01T00:00:00+01:00", "2024-03-01T00:00:00+01:00", freq="15min"),
            "value": 0.0002,
        }
    )
)

contract.apply(consumption)

For more detailed examples, see the notebooks in the notebooks directory.

JSON schema and storage

All models are pydantic models, so you can get a JSON schema with e.g. Contract.model_json_schema() or TypeAdapter(Formula).json_schema(). This schema is meant to be usable for generating forms:

  • every model and field has a short description
  • fields most users can leave untouched are marked with "x-advanced": true
  • strings that refer to a named entry use a format

Development

Prerequisites

  • Python 3.12+
  • uv (fast Python package manager)

1. Install dependencies

uv sync
uv tool install poethepoet

2. Notebooks

You can easilly test the project using our notebooks. They are located in the notebooks directory and can be run with:

poe notebooks

Some notebooks make use of external APIs and require API keys. You can set these in a .env file in the root of the project, using the .env.example file as a template.

If you add new features, please add a new notebook to demonstrate them.

3. Run tests

poe test

4. Code quality (pre-commit)

Pre-commit hooks are configured out of the box. Install them once:

pre-commit install

Every commit will automatically run:

Tool Task Command
Ruff Linting + auto-fix poe lint
Ruff Formatting poe format
ty Type checking poe check

You can also run them manually at any time.

Contributing

Contributions are welcome! See CONTRIBUTING.md for how to get started, including how to add support for new regions.

License

MIT

Metadata

Release files for energy-cost 0.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for energy-cost 0.9.0
File Size Uploaded Provenance Actions
energy_cost-0.9.0.tar.gz 6.9 MB Without provenance Details for energy_cost-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for energy-cost 0.9.0
File Interpreter ABI Platform Actions
energy_cost-0.9.0-py3-none-any.whl Python 3 none any Details for energy_cost-0.9.0-py3-none-any.whl

Total release size: 14.0 MB

Release files / energy_cost-0.9.0.tar.gz

Download URL energy_cost-0.9.0.tar.gz
Size 6.9 MB
Tags Source
SHA-256 checksum
How to use checksums
fdb1e2dc3d6bcc18b36d72591ebe51692f19a981b99de0d9bd3b06b71514fac0
BLAKE2b-256 checksum
How to use checksums
261adc7bf4f330c08b8f5ab2eecb19f45efc08909636c28b74f2835f99c5bf9c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / energy_cost-0.9.0-py3-none-any.whl

Download URL energy_cost-0.9.0-py3-none-any.whl
Size 7.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
e1ddfea4ffe14acbc810fc67cc585d317d92f9927249ca93d2a343546a7a4466
BLAKE2b-256 checksum
How to use checksums
2d174a25c28ca5cfa9941229ac0ea64c5f9ca466a6ede1b2ce22ab79e0d2c1e6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for energy-cost 0.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page