merge main into feature branch

Konstantin · Konstantin · commit e79bf3359d3d · 2025-10-15T10:41:32.000+02:00
diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
@@ -6,11 +6,7 @@ on:
   pull_request: {}
 jobs:
   coverage:
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        python-version: ["3.13"]
-        os: [ubuntu-latest]
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
         with:
@@ -21,10 +17,10 @@ jobs:
           # REPO_AND_READ_PACKAGES_PAT is a secret token on organization level
           # https://github.com/organizations/Hochfrequenz/settings/secrets/dependabot/REPO_AND_READ_PACKAGES_PAT
           submodules: "recursive"
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.14"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
diff --git a/.github/workflows/dev_test.yml b/.github/workflows/dev_test.yml
@@ -8,11 +8,10 @@ on:
   pull_request: {}
 jobs:
   check:
-    runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
-        os: [ubuntu-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
     steps:
       - uses: actions/checkout@v5
       - name: Set up Python ${{ matrix.python-version }}
diff --git a/.github/workflows/formatting.yml b/.github/workflows/formatting.yml
@@ -6,18 +6,16 @@ on:
   pull_request: {}
 jobs:
   black:
-    runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.13"]
-        os: [ubuntu-latest]
         tool: ["black", "isort"]
     steps:
       - uses: actions/checkout@v5
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.14"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
diff --git a/.github/workflows/packaging_test.yml b/.github/workflows/packaging_test.yml
@@ -6,17 +6,13 @@ on:
   pull_request: {}
 jobs:
   check_packaging:
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        python-version: ["3.13"]
-        os: [ubuntu-latest]
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: 3.14
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml
@@ -14,22 +14,18 @@ on:
 jobs:
   tests:
     if: startsWith(github.ref, 'refs/tags/v')
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        python-version: [ "3.13" ]
-        os: [ ubuntu-latest ]
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
         with:
           ref: ${{ github.event.workflow_run.head_branch }}
           token: ${{ secrets.XML_SUBMODULE_PAT }} # token with repo scope; expires never
           # https://github.com/Hochfrequenz/xml-fundamend-python/settings/secrets/actions/XML_AHB_MIG_Token
           submodules: "recursive"
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.14"
       - name: Install tox
         run: |
           python -m pip install --upgrade pip
@@ -40,24 +36,20 @@ jobs:
 
   build-n-publish:
     name: Build and publish Python 🐍 distributions 📦 to PyPI and TestPyPI
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        python-version: [ "3.13" ]
-        os: [ ubuntu-latest ]
-        # Specifying a GitHub environment, # Specifying a GitHub environment, which is strongly recommended by
-        #PyPI: https://docs.pypi.org/trusted-publishers/adding-a-publisher/
-        # you have to create an environment in your repository settings and add the environment name here
+    runs-on: ubuntu-latest
+    # Specifying a GitHub environment, # Specifying a GitHub environment, which is strongly recommended by
+    #PyPI: https://docs.pypi.org/trusted-publishers/adding-a-publisher/
+    # you have to create an environment in your repository settings and add the environment name here
     environment: release
     permissions:
       id-token: write
     needs: tests
     steps:
       - uses: actions/checkout@v5
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.14"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
diff --git a/.github/workflows/pythonlint.yml b/.github/workflows/pythonlint.yml
@@ -7,18 +7,16 @@ on:
 jobs:
   pylint:
     name: Python Code Quality and Lint
-    runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.13"]
-        os: [ubuntu-latest]
         linter-env: ["linting", "type_check", "spell_check"]
     steps:
       - uses: actions/checkout@v5
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.14"
       - name: Install Dependencies
         run: |
           python -m pip install --upgrade pip
diff --git a/.github/workflows/unittests.yml b/.github/workflows/unittests.yml
@@ -9,7 +9,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
         cli: [install_typer, skip_typer]
         os: [ubuntu-latest]
     steps:
diff --git a/pyproject.toml b/pyproject.toml
@@ -16,10 +16,11 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
     "pydantic>=2",
-    "efoli>=2.0.0"
+    "efoli>=2.1.0"
 ]
 dynamic = ["readme", "version"]
 
@@ -36,10 +37,10 @@ coverage = [
 ]
 formatting = [
     "black==25.9.0",
-    "isort==6.0.1"
+    "isort==7.0.0"
 ]
 linting = [
-    "pylint==3.3.8"
+    "pylint==4.0.0"
 ]
 cli = [
     "typer" # if you install fundamend[cli], the cli commands are available via typer
@@ -66,7 +67,7 @@ Homepage = "https://github.com/Hochfrequenz/xml-fundamend-python"
 
 [tool.black]
 line-length = 120
-target_version = ["py311", "py312", "py313"]
+target_version = ["py311", "py312", "py313", "py314"]
 
 [tool.isort]
 line_length = 120
diff --git a/requirements.txt b/requirements.txt
@@ -6,11 +6,11 @@
 #
 annotated-types==0.7.0
     # via pydantic
-efoli==2.0.0
+efoli==2.1.1
     # via fundamend (pyproject.toml)
-pydantic==2.11.3
+pydantic==2.12.0
     # via fundamend (pyproject.toml)
-pydantic-core==2.33.1
+pydantic-core==2.41.1
     # via pydantic
 pytz==2025.2
     # via efoli
@@ -19,5 +19,5 @@ typing-extensions==4.15.0
     #   pydantic
     #   pydantic-core
     #   typing-inspection
-typing-inspection==0.4.1
+typing-inspection==0.4.2
     # via pydantic
diff --git a/src/fundamend/models/anwendungshandbuch.py b/src/fundamend/models/anwendungshandbuch.py
@@ -8,6 +8,8 @@
 from efoli import EdifactFormat
 
 from fundamend.models.base import FundamendBaseModel
+from fundamend.models.kommunikationsrichtung import Kommunikationsrichtung
+from fundamend.utils import parse_kommunikation_von
 
 
 class Code(FundamendBaseModel):
@@ -149,6 +151,15 @@ def is_outdated(self) -> bool:
         """
         return "##alt##" in self.pruefidentifikator.lower()  # table flip moment
 
+    @property
+    def kommunikationsrichtungen(self) -> list[Kommunikationsrichtung] | None:
+        """
+        the parsed 'kommunikation_von' attribute or None if it's unparsable (l)or outdated
+        """
+        if self.is_outdated:
+            return None
+        return parse_kommunikation_von(self.kommunikation_von)
+
 
 class Bedingung(FundamendBaseModel):
     """Ein ConditionKeyConditionText Mapping"""
diff --git a/src/fundamend/models/kommunikationsrichtung.py b/src/fundamend/models/kommunikationsrichtung.py
@@ -0,0 +1,16 @@
+"""contains the Kommunikationsrichtung model"""
+
+from fundamend.models.base import FundamendBaseModel
+
+
+# needs to be separate file/module to avoid circular imports
+class Kommunikationsrichtung(FundamendBaseModel):
+    """
+    a strongly typed representation of the 'Kommunikation_von' attribute of anwendungsfall
+    """
+
+    sender: str  #: e.g. "NB"
+    empfaenger: str  #: e.g. "MSB"
+
+
+__all__ = ["Kommunikationsrichtung"]
diff --git a/src/fundamend/sqlmodels/anwendungshandbuch.py b/src/fundamend/sqlmodels/anwendungshandbuch.py
@@ -13,7 +13,7 @@
 
 
 try:
-    from sqlalchemy import CheckConstraint, UniqueConstraint
+    from sqlalchemy import JSON, CheckConstraint, Column, UniqueConstraint
     from sqlmodel import Field, Relationship, SQLModel
 except ImportError as import_error:
     import_error.msg += "; Did you install fundamend[sqlmodels] or did you try to import from fundamend.models instead?"
@@ -341,6 +341,15 @@ class Anwendungsfall(SQLModel, table=True):
     pruefidentifikator: str = Field(index=True)  #: e.g. '25001'
     beschreibung: str = Field(index=True)  #: e.g. 'Berechnungsformel'
     kommunikation_von: str  #: e.g. 'NB an MSB / LF'
+    kommunikationsrichtungen: list[dict[str, str]] | None = Field(default=None, sa_column=Column(JSON))
+    """
+    JSON column containing a list of dicts with keys 'sender' and 'empfaenger'.
+    The columns value can be deserialized as list[Kommunikationsrichtung].
+    The column contains no more information than the stringly typed 'kommunikation_von' column alone,
+    but it's parsed already and hence easier to use and query.
+    """
+    # we use a json column because setting up a separate table and FK relationships for this seems overkill
+    # https://stackoverflow.com/a/70659555/10009545
     format: EdifactFormat = Field(index=True)  #: e.g. 'UTILTS'
     segments: list[Segment] = Relationship(back_populates="anwendungsfall")
     segment_groups: list[SegmentGroup] = Relationship(back_populates="anwendungsfall")
@@ -356,6 +365,11 @@ def from_model(cls, model: PydanticAnwendungsfall, position: Optional[int] = Non
             pruefidentifikator=model.pruefidentifikator,
             beschreibung=model.beschreibung,
             kommunikation_von=model.kommunikation_von,
+            kommunikationsrichtungen=(
+                [kr.model_dump(mode="json") for kr in model.kommunikationsrichtungen]
+                if model.kommunikationsrichtungen is not None
+                else None
+            ),
             format=model.format,
             position=position,
         )
@@ -373,6 +387,7 @@ def to_model(self) -> PydanticAnwendungsfall:
             pruefidentifikator=self.pruefidentifikator,
             beschreibung=self.beschreibung,
             kommunikation_von=self.kommunikation_von,
+            # the kommunikationsrichtungen are a computed property, so we reconstruct it from the kommunikation_von str
             format=self.format,
             elements=tuple(
                 x.to_model()
diff --git a/src/fundamend/utils.py b/src/fundamend/utils.py
@@ -2,6 +2,11 @@
 Contains some utility functions that are used in the project.
 """
 
+import re
+from typing import Optional
+
+from fundamend.models.kommunikationsrichtung import Kommunikationsrichtung
+
 
 def lstrip(prefix: str, text: str) -> str:
     """Strip the given prefix from the given text. If the text does not start with the prefix, return the text as is.
@@ -73,4 +78,69 @@ def remove_linebreaks_and_hyphens(original: str) -> str:
     return " ".join(result.strip().split())
 
 
-__all__ = ["lstrip", "rstrip", "strip", "remove_linebreaks_and_hyphens"]
+_UNIFIED_SEPARATOR = "/"  # how multiple Marktrollen shall be split in the kommunikation_von attribute
+_ALTERNATIVE_SEPARATORS = [","]  # other separators that are used in the wild
+
+_an_at_word_boundary = re.compile(r"\ban\b")
+
+
+def _add_whitespace_before_an(original: str) -> str:
+    """adds whitespace before 'an' if it is not already there"""
+    return _an_at_word_boundary.sub(" an", original)
+
+
+def _parse_kommunikation_von_line(kommunikation_von_line: str) -> list[Kommunikationsrichtung]:
+    """
+    parses a single line of kommunikation_von into a list of Kommunikationsrichtung objects
+    this is necessary because some AHBs have multiple lines in the kommunikation_von attribute which must not be mixed
+    """
+    if not kommunikation_von_line or not kommunikation_von_line.strip():
+        return []
+    result: list[Kommunikationsrichtung] = []
+    parts = _add_whitespace_before_an(kommunikation_von_line).split(" an ")
+    if len(parts) != 2:
+        # maybe this line looks different, more like 'NB an LF, MSB an NB (Gas)'
+        # then we have to split at the comma first and treat each part like it was a single line. wtf
+        if "," in kommunikation_von_line:
+            for subpart in kommunikation_von_line.split(","):
+                result += _parse_kommunikation_von_line(subpart.strip())
+            return result
+        raise ValueError(f"Invalid kommunikation_von string: '{kommunikation_von_line}'. Expected format: 'X an Y[/Z]'")
+    sender_str = parts[0]
+    receiver_str = parts[1]
+    for alternative_separator in _ALTERNATIVE_SEPARATORS:
+        if alternative_separator in receiver_str:
+            receiver_str = receiver_str.replace(alternative_separator, _UNIFIED_SEPARATOR)
+        if alternative_separator in sender_str:
+            sender_str = sender_str.replace(alternative_separator, _UNIFIED_SEPARATOR)
+    senders = [x.strip() for x in sender_str.split(_UNIFIED_SEPARATOR)]
+    receivers = [x.strip() for x in receiver_str.split(_UNIFIED_SEPARATOR)]
+    for sender in senders:
+        for receiver in receivers:
+            result.append(Kommunikationsrichtung(sender=sender, empfaenger=receiver))
+    return result
+
+
+def parse_kommunikation_von(kommunikation_von: Optional[str]) -> list[Kommunikationsrichtung] | None:
+    """Splits the kommunikation_von string into something strongly typed
+
+    Args:
+        kommunikation_von: The kommunikation_von string to split, e.g. 'NB an LF/MSB'.
+
+    Returns:
+        Properly typed list of Kommunikationsrichtung objects:
+        [Kommunikationsrichtung(sender='NB', empfaenger='LF'),
+        Kommunikationsrichtung(sender='NB', empfaenger='MSB')]
+        or none in case there are no information given (directly).
+    """
+    if kommunikation_von == "Beteiligte aus Ursprungs-nachricht":
+        return None
+    result: list[Kommunikationsrichtung] = []
+    for line in (kommunikation_von or "").splitlines():
+        line = line.strip()
+        if line:
+            result += _parse_kommunikation_von_line(line)
+    return result
+
+
+__all__ = ["lstrip", "rstrip", "strip", "parse_kommunikation_von", "remove_linebreaks_and_hyphens"]
diff --git a/tox.ini b/tox.ini
diff --git a/unittests/test_cli.py b/unittests/test_cli.py
diff --git a/unittests/test_sqlmodels_anwendungshandbuch.py b/unittests/test_sqlmodels_anwendungshandbuch.py
diff --git a/unittests/test_utils.py b/unittests/test_utils.py
