Allow for decimal parsing in pydantic model

docs/examples.md

@@ -24,11 +24,14 @@ result = EnergyPrices(
 ).query_api()
 
 # Convert to DataFrame-ready records
-records = extract_records(result)
+records = extract_records(result, decimal_to_float=True)
 records = add_timestamps(records)
 df = DataFrame(records)
 ```
 
+!!! note
+    The [`extract_records`](utilities.md#entsoe.utils.extract_records) function can automatically parse pydantic `Decimal` data types to `float` values. Be aware that converting `Decimal` to `float` may introduce precision loss, especially for high-precision quantities. Use `decimal_to_float=False` when exact decimal precision must be preserved; this will not parse these types and will give you raw `pydantic.BaseModel.model_dump(mode="json")` output.
+
 !!! note
     The [`extract_records`](utilities.md#entsoe.utils.extract_records) function automatically removes `m_rid` and `time_series.m_rid` metadata fields. This mitigates duplicates due to internal splitting of queries, see [#68](https://github.com/BerriJ/entsoe-apy/issues/68). You may extend the `ignore_fields` parameter as needed (for exampe with `"created_date_time", "time_period_time_interval.start","time_period_time_interval.end"`).
      See [`extract_records`](utilities.md#entsoe.utils.extract_records) for more details.
@@ -59,7 +62,7 @@ result = EnergyPrices(
     period_end=format_entsoe_datetime(period_end),
 ).query_api()
 
-records = extract_records(result)
+records = extract_records(result, decimal_to_float=True)
 records = add_timestamps(records)
 df = pd.DataFrame(records)
 df = df.convert_dtypes()

pyproject.toml

@@ -26,6 +26,7 @@ dependencies = [
   "httpx~=0.28.1",
   "loguru~=0.7.2",
   "xsdata-pydantic>=24.5",
+  "pydantic>=2.0.0",
   "isodate>=0.7.2",
 ]
 

requirements.txt

@@ -1,4 +1,5 @@
 xsdata-pydantic>=24.5
+pydantic>=2.0.0
 httpx==0.28.1
 loguru>=0.7.3
 isodate>=0.7.2

src/entsoe/utils/records.py

@@ -1,10 +1,14 @@
+from decimal import Decimal
 from typing import Any, Dict, List, Optional
 
-from pydantic import BaseModel
+from pydantic import BaseModel, TypeAdapter
 
 from ..config.config import logger
 
 
+_ANY_ADAPTER = TypeAdapter(Any)
+
+
 def _deduplicate_records(records: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
     """Remove duplicate records while preserving order."""
     seen = set()
@@ -17,6 +21,17 @@
     return unique_records
 
 
+def _coerce_decimals_to_float(value: Any) -> Any:
+    """Recursively convert Decimal values to float for downstream processing."""
+    if isinstance(value, Decimal):
+        return float(value)
+    if isinstance(value, dict):
+        return {k: _coerce_decimals_to_float(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_coerce_decimals_to_float(item) for item in value]
+    return value
+
+
 def normalize_to_records(
     data: Dict[str, Any] | List[Any] | Any,
     parent_key: str = "",
@@ -117,6 +132,7 @@
         "time_series.m_rid",
     ],
     deduplicate: bool = True,
+    decimal_to_float: bool = False,
 ) -> List[Dict[str, int | float | str | None]]:
     """
     Convert a Pydantic model or list of Pydantic models to a list of flattened records suitable for pandas DataFrame.
@@ -138,6 +154,9 @@
                       Defaults to ["m_rid", "time_series.m_rid"].
                       Pass None to disable field filtering.
         deduplicate: Whether to remove duplicate records while preserving order. Defaults to True.
+        decimal_to_float: Whether to convert Decimal values to float in the returned
+                 records. If False, uses JSON serialization semantics where
+                 Decimal values are represented as strings. Defaults to False.
 
     Returns:
         List of flattened dictionaries (records) from all BaseModel instances.
@@ -179,7 +198,16 @@
             f"Expected data to be a BaseModel or list of BaseModel instances, got {type(data)}"
         )
 
-    data_dict = [item.model_dump(mode="json") for item in data_list]
+    if decimal_to_float:
+        # Keep Decimal values typed, coerce them, then normalize to JSON-compatible
+        # values so the output structure stays aligned with mode="json".
+        data_dict = [item.model_dump(mode="python") for item in data_list]
+        data_dict = [_coerce_decimals_to_float(item_dict) for item_dict in data_dict]
+        data_dict = [
+            _ANY_ADAPTER.dump_python(item_dict, mode="json") for item_dict in data_dict
+        ]
+    else:
+        data_dict = [item.model_dump(mode="json") for item in data_list]
     all_records = []
 
     if domain:

src/entsoe/utils/utils.py

@@ -31,10 +31,10 @@ def format_entsoe_datetime(dt: datetime) -> int:
     """
     Format datetime object to ENTSOE datetime format (YYYYMMDDHHMM).
 
-    Convert a (tz-aware) datetime to UTC and format it as an integer in the 
-    ENTSOE format. If the datetime is naive, it is assumed to be in UTC.This 
-    function can be used to convert pd.Timestamp and pl.Datetime objects to the 
-    required format for ENTSOE API calls. Please have a look at the 
+    Convert a (tz-aware) datetime to UTC and format it as an integer in the
+    ENTSOE format. If the datetime is naive, it is assumed to be in UTC.This
+    function can be used to convert pd.Timestamp and pl.Datetime objects to the
+    required format for ENTSOE API calls. Please have a look at the
     documentation for more details and examples.
 
     Args:

tests/test_extract_records.py

@@ -1,12 +1,97 @@
 # %%
 
+from decimal import Decimal
+from datetime import datetime, timezone
+
 import pytest
+from pydantic import BaseModel
 
 from entsoe.config import get_config
 from entsoe.Market import EnergyPrices
 from entsoe.utils import extract_records
 
 
+def test_extract_records_converts_decimal_to_float():
+    class Point(BaseModel):
+        quantity: Decimal
+
+    class Document(BaseModel):
+        m_rid: str
+        point: list[Point]
+
+    data = Document(
+        m_rid="doc-1",
+        point=[Point(quantity=Decimal("10.25")), Point(quantity=Decimal("2.5"))],
+    )
+
+    records = extract_records(data, decimal_to_float=True)
+
+    assert len(records) == 2
+    assert all(isinstance(record["point.quantity"], float) for record in records)
+    assert records[0]["point.quantity"] == 10.25
+    assert records[1]["point.quantity"] == 2.5
+
+
+def test_extract_records_domain_converts_decimal_to_float():
+    class TimeSeries(BaseModel):
+        quantity: Decimal
+
+    class Document(BaseModel):
+        time_series: list[TimeSeries]
+
+    data = Document(
+        time_series=[
+            TimeSeries(quantity=Decimal("3.14")),
+            TimeSeries(quantity=Decimal("6.28")),
+        ]
+    )
+
+    records = extract_records(data, domain="time_series", decimal_to_float=True)
+
+    assert len(records) == 2
+    assert all(isinstance(record["quantity"], float) for record in records)
+    assert records[0]["quantity"] == 3.14
+    assert records[1]["quantity"] == 6.28
+
+
+def test_extract_records_decimal_to_float_keeps_json_like_structure():
+    class Document(BaseModel):
+        timestamp: datetime
+        quantity: Decimal
+
+    data = Document(
+        timestamp=datetime(2026, 1, 1, 0, 0, tzinfo=timezone.utc),
+        quantity=Decimal("9.5"),
+    )
+
+    records = extract_records(data, decimal_to_float=True)
+
+    assert len(records) == 1
+    assert isinstance(records[0]["timestamp"], str)
+    assert records[0]["timestamp"].startswith("2026-01-01T00:00:00")
+    assert isinstance(records[0]["quantity"], float)
+    assert records[0]["quantity"] == 9.5
+
+
+def test_extract_records_serializes_decimal_as_string_when_disabled():
+    class Point(BaseModel):
+        quantity: Decimal
+
+    class Document(BaseModel):
+        point: list[Point]
+
+    data = Document(
+        point=[Point(quantity=Decimal("1.1")), Point(quantity=Decimal("2.2"))]
+    )
+
+    records = extract_records(data, decimal_to_float=False)
+
+    assert len(records) == 2
+    assert all(isinstance(record["point.quantity"], str) for record in records)
+    assert records[0]["point.quantity"] == "1.1"
+    assert records[1]["point.quantity"] == "2.2"
+
+
 @pytest.mark.skipif(
     get_config().security_token is None,
     reason="ENTSOE_API environment variable not set",