gazpar2haws 0.2.1__tar.gz → 0.3.0b16__tar.gz

{gazpar2haws-0.2.1 → gazpar2haws-0.3.0b16}/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2025-02-02
+
+### Added
+
+[#31](https://github.com/ssenart/gazpar2haws/issues/31): Cost integration.
+
 ## [0.2.1] - 2025-01-24
 
 ### Fixed

{gazpar2haws-0.2.1 → gazpar2haws-0.3.0b16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: gazpar2haws
-Version: 0.2.1
+Version: 0.3.0b16
 Summary: Gazpar2HAWS is a gateway that reads data history from the GrDF (French gas provider) meter and send it to Home Assistant using WebSocket interface
 License: MIT License
          
@@ -29,6 +29,8 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: pydantic-extra-types (>=2.10.2,<3.0.0)
+Requires-Dist: pydantic[email] (>=2.10.6,<3.0.0)
 Requires-Dist: pygazpar (>=1.2.7)
 Requires-Dist: pyyaml (>=6.0.2)
 Requires-Dist: websockets (>=14.1)
@@ -216,6 +218,262 @@ The history is uploaded on the entities with names:
 
 `${name}` is 'gazpar2haws' defined in the above configuration file. It can be replaced by any other name.
 
+### Cost configuration
+
+Gazpar2HAWS is able to compute and publish cost history to Home Assistant.
+
+The cost computation is based in gas prices defined in the configuration files.
+
+The section 'Pricing' is broken into 5 sub-sections:
+- vat: Value added tax definition.
+- consumption_prices: All the gas price history in €/kWh.
+- subscription_prices: The subscription prices in €/month (or year).
+- transport_prices: The fixed prices in €/month (or year) to transport the gas.
+- energy_taxes: Various taxes on energy in €/kWh.
+
+Below, many examples illustrates how to use pricing configuration for use cases from the simplest to the most complex.
+
+
+Example 1: A fixed consumption price
+---
+
+The given price applies at the given date, after and before.
+
+The default unit is € per kWh.
+
+**Formula:**
+```math
+cost[€] = quantity[kWh] * price[€/kWh]
+```
+
+
+```yaml
+pricing:
+  consumption_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.07790 # Default unit is €/kWh.
+```
+
+Example 2: A fixed consumption price in another unit
+---
+
+*value_unit* is the price unit (default: €).
+*base_unit* is the denominator unit (default: kWh).
+
+**Formula:**
+```math
+cost[€] = \frac{quantity[kWh] * price[¢/MWh] * converter\_factor[¢->€]} {converter\_factor[MWh->kWh]}
+```
+
+
+```yaml
+pricing:
+  consumption_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 7790.0 # Unit is now ¢/MWh.
+      value_unit: "¢"
+      base_unit: "MWh"
+```
+
+Example 3: Multiple prices over time
+---
+
+```yaml
+pricing:
+  consumption_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.07790 # Default unit is €/kWh.
+    - start_date: "2024-01-01"
+      value: 0.06888 # Default unit is €/kWh.
+```
+
+Price is 0.07790 before 2024-01-01.
+
+Price is 0.06888 on 2024-01-01 and after.
+
+
+Example 4: Price is given excluding tax
+---
+
+The *normal* value added tax (*vat*) rate is 20%.
+
+```yaml
+pricing:
+  vat:
+    - id: normal
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.20 # It is the tax rate in [0, 1.0] <==> [0% - 100%].
+  consumption_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.07790 # Default unit is €/kWh.
+      vat_id: "normal" # Reference to the vat rate that is applied for this period.
+```
+
+**Formula:**
+```math
+cost[€] = quantity[kWh] * price[€/kWh] * (1 + vat[normal])
+```
+
+Example 5: Subscription price
+---
+
+A fixed montly subscription is due over consumption.
+
+Subscription *vat* tax may be different than the consumption *vat* tax.
+
+```yaml
+pricing:
+  vat:
+    - id: normal
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.20 # It is the tax rate in [0, 1.0] <==> [0% - 100%].
+    - id: reduced
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.0550
+  consumption_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.07790 # Default unit is €/kWh.
+      vat_id: "normal" # Reference to the vat rate that is applied for this period.
+  subscription_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 19.83
+      value_unit: "€"
+      base_unit: "month"
+      vat_id: "reduced"
+```
+
+**Formula:**
+```math
+cost[€] = quantity[kWh] * cons\_price[€/kWh] * (1 + vat[normal]) + sub\_price * (1 + vat[reduced])
+```
+
+
+Example 6: Transport price
+---
+
+A fixed yearly transport may be charged as well.
+
+```yaml
+pricing:
+  vat:
+    - id: normal
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.20 # It is the tax rate in [0, 1.0] <==> [0% - 100%].
+    - id: reduced
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.0550
+  consumption_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.07790 # Default unit is €/kWh.
+      vat_id: "normal" # Reference to the vat rate that is applied for this period.
+  transport_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 34.38
+      value_unit: "€"
+      base_unit: "year"
+      vat_id: reduced
+```
+**Formula:**
+```math
+cost[€] = quantity[kWh] * cons\_price[€/kWh] * (1 + vat[normal]) + trans\_price * (1 + vat[reduced])
+```
+
+Example 7: Energy taxes
+---
+
+Consumption may be taxed by additional taxes (known as energy taxes).
+
+```yaml
+pricing:
+  vat:
+    - id: normal
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.20 # It is the tax rate in [0, 1.0] <==> [0% - 100%].
+    - id: reduced
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.0550
+  consumption_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.07790 # Default unit is €/kWh.
+      vat_id: "normal" # Reference to the vat rate that is applied for this period.
+  energy_taxes:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.00837
+      value_unit: "€"
+      base_unit: "kWh"
+      vat_id: normal
+```
+**Formula:**
+```math
+cost[€] = quantity[kWh] * (cons\_price[€/kWh] + ener\_taxes[€/kWh])* (1 + vat[normal])
+```
+
+Example 8: All in one
+---
+
+In the price list, the first item properties are propagated to the next items in the list. If their values does not change, it is not required to repeat them.
+
+```yaml
+pricing:
+  vat:
+    - id: reduced
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.0550
+    - id: normal
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.20
+  consumption_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.07790
+      value_unit: "€"
+      base_unit: "kWh"
+      vat_id: normal
+    - start_date: "2023-07-01"
+      value: 0.05392
+    - start_date: "2023-08-01"
+      value: 0.05568
+    - start_date: "2023-09-01"
+      value: 0.05412
+    - start_date: "2023-10-01"
+      value: 0.06333
+    - start_date: "2023-11-01"
+      value: 0.06716
+    - start_date: "2023-12-01"
+      value: 0.07235
+    - start_date: "2024-01-01"
+      value: 0.06888
+    - start_date: "2024-02-01"
+      value: 0.05972
+    - start_date: "2024-03-01"
+      value: 0.05506
+    - start_date: "2024-04-01"
+      value: 0.04842
+    - start_date: "2025-01-01"
+      value: 0.07807
+  subscription_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 19.83
+      value_unit: "€"
+      base_unit: "month"
+      vat_id: reduced
+    - start_date: "2023-07-01"
+      value: 20.36
+  transport_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 34.38
+      value_unit: "€"
+      base_unit: "year"
+      vat_id: reduced
+  energy_taxes:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.00837
+      value_unit: "€"
+      base_unit: "kWh"
+      vat_id: normal
+    - start_date: "2024-01-01"
+      value: 0.01637
+```
+
 ### Environment variable for Docker
 
 In a Docker environment, the configurations files are instantiated by replacing the environment variables below in the template files:

{gazpar2haws-0.2.1 → gazpar2haws-0.3.0b16}/README.md

@@ -180,6 +180,262 @@ The history is uploaded on the entities with names:
 
 `${name}` is 'gazpar2haws' defined in the above configuration file. It can be replaced by any other name.
 
+### Cost configuration
+
+Gazpar2HAWS is able to compute and publish cost history to Home Assistant.
+
+The cost computation is based in gas prices defined in the configuration files.
+
+The section 'Pricing' is broken into 5 sub-sections:
+- vat: Value added tax definition.
+- consumption_prices: All the gas price history in €/kWh.
+- subscription_prices: The subscription prices in €/month (or year).
+- transport_prices: The fixed prices in €/month (or year) to transport the gas.
+- energy_taxes: Various taxes on energy in €/kWh.
+
+Below, many examples illustrates how to use pricing configuration for use cases from the simplest to the most complex.
+
+
+Example 1: A fixed consumption price
+---
+
+The given price applies at the given date, after and before.
+
+The default unit is € per kWh.
+
+**Formula:**
+```math
+cost[€] = quantity[kWh] * price[€/kWh]
+```
+
+
+```yaml
+pricing:
+  consumption_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.07790 # Default unit is €/kWh.
+```
+
+Example 2: A fixed consumption price in another unit
+---
+
+*value_unit* is the price unit (default: €).
+*base_unit* is the denominator unit (default: kWh).
+
+**Formula:**
+```math
+cost[€] = \frac{quantity[kWh] * price[¢/MWh] * converter\_factor[¢->€]} {converter\_factor[MWh->kWh]}
+```
+
+
+```yaml
+pricing:
+  consumption_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 7790.0 # Unit is now ¢/MWh.
+      value_unit: "¢"
+      base_unit: "MWh"
+```
+
+Example 3: Multiple prices over time
+---
+
+```yaml
+pricing:
+  consumption_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.07790 # Default unit is €/kWh.
+    - start_date: "2024-01-01"
+      value: 0.06888 # Default unit is €/kWh.
+```
+
+Price is 0.07790 before 2024-01-01.
+
+Price is 0.06888 on 2024-01-01 and after.
+
+
+Example 4: Price is given excluding tax
+---
+
+The *normal* value added tax (*vat*) rate is 20%.
+
+```yaml
+pricing:
+  vat:
+    - id: normal
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.20 # It is the tax rate in [0, 1.0] <==> [0% - 100%].
+  consumption_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.07790 # Default unit is €/kWh.
+      vat_id: "normal" # Reference to the vat rate that is applied for this period.
+```
+
+**Formula:**
+```math
+cost[€] = quantity[kWh] * price[€/kWh] * (1 + vat[normal])
+```
+
+Example 5: Subscription price
+---
+
+A fixed montly subscription is due over consumption.
+
+Subscription *vat* tax may be different than the consumption *vat* tax.
+
+```yaml
+pricing:
+  vat:
+    - id: normal
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.20 # It is the tax rate in [0, 1.0] <==> [0% - 100%].
+    - id: reduced
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.0550
+  consumption_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.07790 # Default unit is €/kWh.
+      vat_id: "normal" # Reference to the vat rate that is applied for this period.
+  subscription_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 19.83
+      value_unit: "€"
+      base_unit: "month"
+      vat_id: "reduced"
+```
+
+**Formula:**
+```math
+cost[€] = quantity[kWh] * cons\_price[€/kWh] * (1 + vat[normal]) + sub\_price * (1 + vat[reduced])
+```
+
+
+Example 6: Transport price
+---
+
+A fixed yearly transport may be charged as well.
+
+```yaml
+pricing:
+  vat:
+    - id: normal
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.20 # It is the tax rate in [0, 1.0] <==> [0% - 100%].
+    - id: reduced
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.0550
+  consumption_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.07790 # Default unit is €/kWh.
+      vat_id: "normal" # Reference to the vat rate that is applied for this period.
+  transport_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 34.38
+      value_unit: "€"
+      base_unit: "year"
+      vat_id: reduced
+```
+**Formula:**
+```math
+cost[€] = quantity[kWh] * cons\_price[€/kWh] * (1 + vat[normal]) + trans\_price * (1 + vat[reduced])
+```
+
+Example 7: Energy taxes
+---
+
+Consumption may be taxed by additional taxes (known as energy taxes).
+
+```yaml
+pricing:
+  vat:
+    - id: normal
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.20 # It is the tax rate in [0, 1.0] <==> [0% - 100%].
+    - id: reduced
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.0550
+  consumption_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.07790 # Default unit is €/kWh.
+      vat_id: "normal" # Reference to the vat rate that is applied for this period.
+  energy_taxes:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.00837
+      value_unit: "€"
+      base_unit: "kWh"
+      vat_id: normal
+```
+**Formula:**
+```math
+cost[€] = quantity[kWh] * (cons\_price[€/kWh] + ener\_taxes[€/kWh])* (1 + vat[normal])
+```
+
+Example 8: All in one
+---
+
+In the price list, the first item properties are propagated to the next items in the list. If their values does not change, it is not required to repeat them.
+
+```yaml
+pricing:
+  vat:
+    - id: reduced
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.0550
+    - id: normal
+      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.20
+  consumption_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.07790
+      value_unit: "€"
+      base_unit: "kWh"
+      vat_id: normal
+    - start_date: "2023-07-01"
+      value: 0.05392
+    - start_date: "2023-08-01"
+      value: 0.05568
+    - start_date: "2023-09-01"
+      value: 0.05412
+    - start_date: "2023-10-01"
+      value: 0.06333
+    - start_date: "2023-11-01"
+      value: 0.06716
+    - start_date: "2023-12-01"
+      value: 0.07235
+    - start_date: "2024-01-01"
+      value: 0.06888
+    - start_date: "2024-02-01"
+      value: 0.05972
+    - start_date: "2024-03-01"
+      value: 0.05506
+    - start_date: "2024-04-01"
+      value: 0.04842
+    - start_date: "2025-01-01"
+      value: 0.07807
+  subscription_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 19.83
+      value_unit: "€"
+      base_unit: "month"
+      vat_id: reduced
+    - start_date: "2023-07-01"
+      value: 20.36
+  transport_prices:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 34.38
+      value_unit: "€"
+      base_unit: "year"
+      vat_id: reduced
+  energy_taxes:
+    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
+      value: 0.00837
+      value_unit: "€"
+      base_unit: "kWh"
+      vat_id: normal
+    - start_date: "2024-01-01"
+      value: 0.01637
+```
+
 ### Environment variable for Docker
 
 In a Docker environment, the configurations files are instantiated by replacing the environment variables below in the template files:

{gazpar2haws-0.2.1 → gazpar2haws-0.3.0b16}/gazpar2haws/__main__.py

@@ -3,8 +3,9 @@ import asyncio
 import logging
 import traceback
 
-from gazpar2haws import __version__, config_utils
+from gazpar2haws import __version__
 from gazpar2haws.bridge import Bridge
+from gazpar2haws.configuration import Configuration
 
 Logger = logging.getLogger(__name__)
 
@@ -16,9 +17,7 @@ async def main():
         prog="gazpar2haws",
         description="Gateway that reads data history from the GrDF (French gas provider) meter and send it to Home Assistant using WebSocket interface.",
     )
-    parser.add_argument(
-        "-v", "--version", action="version", version="Gazpar2HAWS version"
-    )
+    parser.add_argument("-v", "--version", action="version", version="Gazpar2HAWS version")
     parser.add_argument(
         "-c",
         "--config",
@@ -38,17 +37,15 @@ async def main():
 
     try:
         # Load configuration files
-        config = config_utils.ConfigLoader(args.config, args.secrets)
-        config.load_secrets()
-        config.load_config()
+        config = Configuration.load(args.config, args.secrets)
 
         print(f"Gazpar2HAWS version: {__version__}")
 
         # Set up logging
-        logging_file = config.get("logging.file")
-        logging_console = bool(config.get("logging.console"))
-        logging_level = config.get("logging.level")
-        logging_format = config.get("logging.format")
+        logging_file = config.logging.file
+        logging_console = config.logging.console
+        logging_level = config.logging.level
+        logging_format = config.logging.format
 
         # Convert logging level to integer
         if logging_level.upper() == "DEBUG":
@@ -70,9 +67,7 @@ async def main():
             # Add a console handler manually
             console_handler = logging.StreamHandler()
             console_handler.setLevel(level)  # Set logging level for the console
-            console_handler.setFormatter(
-                logging.Formatter(logging_format)
-            )  # Customize console format
+            console_handler.setFormatter(logging.Formatter(logging_format))  # Customize console format
 
             # Get the root logger and add the console handler
             logging.getLogger().addHandler(console_handler)
@@ -91,12 +86,10 @@ async def main():
         return 0
 
     except Exception:  # pylint: disable=broad-except
-        errorMessage = (
-            f"An error occured while running Gazpar2HAWS: {traceback.format_exc()}"
-        )
+        errorMessage = f"An error occured while running Gazpar2HAWS: {traceback.format_exc()}"
         Logger.error(errorMessage)
         print(errorMessage)
-        return 1
+        raise
 
 
 # ----------------------------------