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.

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.8.4

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.8.4
File Size Uploaded Provenance Actions
energy_cost-0.8.4.tar.gz 6.9 MB Without provenance Details for energy_cost-0.8.4.tar.gz

Built distribution (wheel)

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

Total release size: 14.0 MB

Release files / energy_cost-0.8.4.tar.gz

Download URL energy_cost-0.8.4.tar.gz
Size 6.9 MB
Tags Source
SHA-256 checksum
How to use checksums
8ea4fd1439561a5acc1adf6ea35dba50e242567cbcb3bce7301b5a33bfdeff5a
BLAKE2b-256 checksum
How to use checksums
d0af5c920bb7056046f3cbb08f770885a2e7fe5e5b6bbfc5f553365965e7b53f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","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.8.4-py3-none-any.whl

Download URL energy_cost-0.8.4-py3-none-any.whl
Size 7.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
12d91d8b76b1fbfedc4f874bb6420c8343c7d35a7f6c3ee998dfeff07dd62510
BLAKE2b-256 checksum
How to use checksums
74c692b98264e16c69272439a8b7926efd57f2933058a5889ac7867b3038d1e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","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.8.4

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