Merge branch 'main' into main

XaMa928 · web-flow · commit a44f68347822 · 2025-12-02T13:01:15.000+01:00
diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
@@ -39,7 +39,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
@@ -9,7 +9,7 @@ jobs:
         python-version: ["3.12"]
         os: [ubuntu-latest]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Set up Python ${{ matrix.python-version }}
diff --git a/.github/workflows/docs_latest.yml b/.github/workflows/docs_latest.yml
@@ -33,7 +33,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0 # otherwise, you will fail to push refs to dest repo
       - name: Install dependencies
diff --git a/.github/workflows/formatting.yml b/.github/workflows/formatting.yml
@@ -5,6 +5,6 @@ jobs:
   formatting:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: actions/setup-python@v6
       - uses: pre-commit/action@v3.0.1
diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml
@@ -10,7 +10,7 @@ jobs:
         os: [ubuntu-latest, windows-latest]
         linter-env: ["linting", "type_check", "dev"]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v6
         with:
diff --git a/.github/workflows/packaging_test.yml b/.github/workflows/packaging_test.yml
@@ -9,7 +9,7 @@ jobs:
         python-version: ["3.10", "3.11", "3.12"]
         os: [ubuntu-latest]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v6
         with:
diff --git a/.github/workflows/python-publish-scheduled.yml b/.github/workflows/python-publish-scheduled.yml
@@ -16,7 +16,7 @@ jobs:
         python-version: ["3.10", "3.11", "3.12"]
         os: [ubuntu-latest]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v6
         with:
@@ -32,7 +32,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
       - name: Calculate Tag Name
         id: calc_tag
         run: |
@@ -52,7 +52,7 @@ jobs:
     needs: tests
     steps:
       - name: Check out Git repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v6
         with:
@@ -98,7 +98,7 @@ jobs:
       id-token: write
     needs: [tests, generate]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml
@@ -16,7 +16,7 @@ jobs:
         python-version: ["3.12"]
         os: [ubuntu-latest]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v6
         with:
@@ -33,7 +33,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out Git repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Set up Python ${{ matrix.python-version }}
@@ -63,7 +63,7 @@ jobs:
     concurrency: build-n-publish-json-schemas
     steps:
       - name: Check out Git repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v6
         with:
@@ -113,7 +113,7 @@ jobs:
     needs: [tests, check_version_tag]
     concurrency: build-n-publish-docs
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0  # otherwise, you will fail to push refs to dest repo
       - name: Set up Python
@@ -183,7 +183,7 @@ jobs:
     needs: [tests, json_schemas, docs]
     concurrency: build-n-publish-distributions
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
diff --git a/.github/workflows/test_docs.yml b/.github/workflows/test_docs.yml
@@ -9,7 +9,7 @@ jobs:
         python-version: ["3.12"]
         os: [ubuntu-latest]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Set up Python ${{ matrix.python-version }}
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -9,7 +9,7 @@ jobs:
         python-version: ["3.10", "3.11", "3.12"]
         os: [ubuntu-latest]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Set up Python ${{ matrix.python-version }}
diff --git a/docs/index.rst b/docs/index.rst
@@ -31,14 +31,15 @@ Contents
    :maxdepth: 2
 
    Fundamentals <fundamentals>
+   Technical restrictions <restrictions>
    Data Model Overview <api/modules>
    BusinessObjects <api/bo4e.bo>
    Components <api/bo4e.com>
    Enumerations <api/bo4e.enum>
    Versioning <versioning>
    Release Workflow <release_workflow>
-   Contributing <contributing_guide>
    Changelog <changelog>
+   Contributing <contributing_guide>
    Authors <authors>
    License <license>
 
diff --git a/docs/release_workflow.rst b/docs/release_workflow.rst
@@ -10,24 +10,24 @@ Step-by-Step Guide
 
 1. Python Package Implementation
 --------------------------------
-   * **Starting Point:** The journey begins with the implementation of the `BO4E data model as a Python package <https://github.com/bo4e/BO4E-python/>`_.
+   * **Starting Point:** The journey begins with the implementation of the `BO4E data model as a Python package <https://github.com/bo4e/BO4E-python/>`__.
 
 2. Release and Schema Generation
 --------------------------------
    * **Automatic Generation:** Upon releasing a new version of this Python package, a GitHub action automatically triggers.
    * **JSON Schemas Creation:** This action generates JSON schemas, which are essential blueprints of the data model.
-   * **Storage:** These schemas are then stored in a dedicated repository, known as the `BO4E-Schemas Repository <https://github.com/bo4e/BO4E-Schemas>`_.
+   * **Storage:** These schemas are then stored in a dedicated repository, known as the `BO4E-Schemas Repository <https://github.com/bo4e/BO4E-Schemas>`__.
 
-3. Optional Customization (BO4E-Schema-Tool)
+3. Optional Customization (BO4E-CLI)
 --------------------------------------------
    * **Flexibility in Data Fields:** Initially, the JSON schemas contain only optional fields.
-   * **Setting Required Fields:** If you need to designate certain fields as mandatory, you can use the `BO4E-Schema-Tool Repository <https://github.com/bo4e/BO4E-Schema-Tool>`_.
-   * **Tool Functionality:** This repository houses a command-line interface (CLI) tool that assists in updating the JSON schema files to define required fields.
+   * **Setting Required Fields:** If you need to designate certain fields as mandatory, you can use the `BO4E-CLI <https://github.com/bo4e/BO4E-CLI?tab=readme-ov-file#bo4e-edit>`__.
+   * **More flexibility for your use-case:** Besides the required fields, the BO4E-CLI can do a lot more non-critical customization. I.e. the edits are only additive.
 
-4. Code Generation (BO4E-Python-Generator)
+4. Code Generation (BO4E-CLI)
 ------------------------------------------
    * **Finalizing JSON Schemas:** Once you have the final version of the JSON schema files, it's time to generate code.
-   * **Pydantic Classes Creation:** Utilize tools like the `BO4E-Python-Generator <https://github.com/bo4e/BO4E-Python-Generator>`_, another CLI tool, to create Pydantic classes from the JSON schemas.
+   * **Pydantic Classes Creation:** Use the same `BO4E-CLI <https://github.com/bo4e/BO4E-CLI?tab=readme-ov-file#bo4e-generate>`__ to create Pydantic classes from the JSON schemas.
 
 5. Ready to Use
 ---------------
diff --git a/docs/restrictions.rst b/docs/restrictions.rst
@@ -0,0 +1,26 @@
+======================
+Technical restrictions
+======================
+
+There are some technical restrictions throughout the BO4E data models which are important if you want to use it.
+There are several reasons for these but mostly due to compatibility reasons as we want to design the data model
+such that it can be implemented in most programming languages.
+
+* The data model is generally not object oriented. The reference implementation (BO4E-Python) uses inheritance
+  to save some code but the generated JSON schemas do not contain any information about inheritance as it is not
+  supported by the official JSON schema structure. As a result, the following constraints apply:
+
+  * You can only differentiate BOs and COMs by using the enums `BoTyp` and `ComTyp`. They are not directly
+    referenced from the data model but are rolled out to support developers if they need to differentiate the
+    types.
+  * There will be some redundancy in terms of field definitions.
+
+* In general, BOs won't be referenced by COMs but it's not prohibited. In fact, there are some cases in which a COM
+  references a BO. Keep that in mind when designing a package structure e.g. to prevent circular import errors.
+* There are no circular references. This means, when drawing a reference graph of BO4E there will be no loops.
+
+  * As a result, we cannot directly support `n x m`-relationships as they would require a back-reference.
+    If you're designing a database structure you have to manually add these relationship tables where needed.
+
+* We won't use a `Union`-type which is represented in JSON schemas as `anyOf` except for a nullable type. I.e.
+  the type can never be a union of two or more types which are not `null`.
diff --git a/src/bo4e/__init__.py b/src/bo4e/__init__.py
@@ -101,7 +101,6 @@
     "TarifzeitenZeitscheibe",
     "Tarifzeitstufe",
     "Unterschrift",
-    "Verbrauch",
     "Vertragskonditionen",
     "Vertragsteil",
     "VerwendungszweckProMarktrolle",
@@ -307,7 +306,6 @@
 from .com.tarifzeitenzeitscheibe import TarifzeitenZeitscheibe
 from .com.tarifzeitstufe import Tarifzeitstufe
 from .com.unterschrift import Unterschrift
-from .com.verbrauch import Verbrauch
 from .com.vertragskonditionen import Vertragskonditionen
 from .com.vertragsteil import Vertragsteil
 from .com.verwendungszweckpromarktrolle import VerwendungszweckProMarktrolle
diff --git a/src/bo4e/bo/energiemenge.py b/src/bo4e/bo/energiemenge.py
@@ -11,8 +11,8 @@
 from .geschaeftsobjekt import Geschaeftsobjekt
 
 if TYPE_CHECKING:
-    from ..com.verbrauch import Verbrauch
-    from ..enum.lokationstyp import Lokationstyp
+    from ..com.menge import Menge
+    from ..com.zeitraum import Zeitraum
 
 
 # pylint: disable=too-few-public-methods
@@ -34,11 +34,11 @@ class Energiemenge(Geschaeftsobjekt):
     """
 
     typ: Annotated[Literal[BoTyp.ENERGIEMENGE], Field(alias="_typ")] = BoTyp.ENERGIEMENGE
-    lokations_id: Optional[str] = None
-    """Eindeutige Nummer der Marktlokation bzw. der Messlokation, zu der die Energiemenge gehört"""
-    lokationstyp: Optional["Lokationstyp"] = None
-    """Gibt an, ob es sich um eine Markt- oder Messlokation handelt"""
-
-    energieverbrauch: Optional[list["Verbrauch"]] = None
-    """Gibt den Verbrauch in einer Zeiteinheit an"""
-    # there are no optional attributes
+    obis_kennzahl: Optional[str] = None
+    """Die OBIS-Kennzahl der Energiemenge"""
+    beschreibung: Optional[str] = None
+    """Ergänzende Beschreibung zur Energiemenge"""
+    zeitraum: Optional["Zeitraum"] = None
+    """Zeitraum, in dem die Energiemenge angefallen ist/gemessen wurde"""
+    menge: Optional["Menge"] = None
+    """Die angefallene/gemessene Menge"""
diff --git a/src/bo4e/bo/marktlokation.py b/src/bo4e/bo/marktlokation.py
@@ -12,10 +12,10 @@
 from .geschaeftsobjekt import Geschaeftsobjekt
 
 if TYPE_CHECKING:
+    from ..bo.energiemenge import Energiemenge
     from ..com.adresse import Adresse
     from ..com.geokoordinaten import Geokoordinaten
     from ..com.katasteradresse import Katasteradresse
-    from ..com.verbrauch import Verbrauch
     from ..com.zaehlwerk import Zaehlwerk
     from ..enum.bilanzierungsmethode import Bilanzierungsmethode
     from ..enum.energierichtung import Energierichtung
@@ -103,7 +103,7 @@ class Marktlokation(Geschaeftsobjekt):
     marktgebiet: Optional[str] = None
     """für Gas. Code vom EIC, https://www.entsog.eu/data/data-portal/codes-list"""
     zaehlwerke: Optional[list["Zaehlwerk"]] = None
-    verbrauchsmengen: Optional[list["Verbrauch"]] = None
+    verbrauchsmengen: Optional[list["Energiemenge"]] = None
     zaehlwerke_der_beteiligten_marktrolle: Optional[list["Zaehlwerk"]] = None
 
     lokationszuordnungen: Optional[list["Lokationszuordnung"]] = None
diff --git a/src/bo4e/com/verbrauch.py b/src/bo4e/com/verbrauch.py
diff --git a/src/bo4e/enum/comtyp.py b/src/bo4e/enum/comtyp.py
@@ -65,7 +65,6 @@ class ComTyp(StrEnum):
     TARIFZEITENZEITSCHEIBE = "TARIFZEITENZEITSCHEIBE"
     TARIFZEITSTUFE = "TARIFZEITSTUFE"
     UNTERSCHRIFT = "UNTERSCHRIFT"
-    VERBRAUCH = "VERBRAUCH"
     VERTRAGSKONDITIONEN = "VERTRAGSKONDITIONEN"
     VERTRAGSTEIL = "VERTRAGSTEIL"
     VERWENDUNGSZWECKPROMARKTROLLE = "VERWENDUNGSZWECKPROMARKTROLLE"
diff --git a/tests/test_energiemenge.py b/tests/test_energiemenge.py
@@ -1,6 +1,6 @@
 import pytest
 
-from bo4e import Energiemenge, Lokationstyp, Verbrauch
+from bo4e import Energiemenge, Menge, Zeitraum
 from tests.serialization_helper import assert_serialization_roundtrip
 
 
@@ -10,9 +10,10 @@ class TestEnergiemenge:
         [
             pytest.param(
                 Energiemenge(
-                    lokations_id="DE0123456789012345678901234567890",
-                    lokationstyp=Lokationstyp.MELO,
-                    energieverbrauch=[Verbrauch()],
+                    obis_kennzahl="1-0:1.8.1",
+                    beschreibung="Eine Beschreibung",
+                    zeitraum=Zeitraum(),
+                    menge=Menge(),
                 ),
                 id="all attributes at first level",
             ),
diff --git a/tests/test_marktlokation.py b/tests/test_marktlokation.py
@@ -3,6 +3,7 @@
 from bo4e import (
     Adresse,
     Bilanzierungsmethode,
+    Energiemenge,
     Energierichtung,
     Geschaeftspartner,
     Kundentyp,
@@ -29,6 +30,7 @@ class TestMaLo:
                     netzebene=Netzebene.NSP,
                     endkunde=Geschaeftspartner(),
                     kundengruppen=[Kundentyp.GEWERBE, Kundentyp.PRIVAT],
+                    verbrauchsmengen=[Energiemenge()],
                     lokationsbuendel_objektcode="9992 00000 125 6",
                     lokationszuordnungen=[Lokationszuordnung()],
                 )
diff --git a/tests/test_verbrauch.py b/tests/test_verbrauch.py
