Rework Geschaeftspartner, Marktteilnehmer and Ansprechpartner (=> Person) (#680)

Co-authored-by: kevin <68426071+hf-krechan@users.noreply.github.com>

Author: hf-fvesely

src/bo4e/__init__.py

@@ -9,7 +9,6 @@
 """
 __all__ = [
     "Angebot",
-    "Ansprechpartner",
     "Ausschreibung",
     "Buendelvertrag",
     "Energiemenge",
@@ -22,6 +21,7 @@
     "Marktlokation",
     "Marktteilnehmer",
     "Messlokation",
+    "Person",
     "Preisblatt",
     "PreisblattDienstleistung",
     "PreisblattHardware",
@@ -58,6 +58,7 @@
     "Fremdkostenposition",
     "Geokoordinaten",
     "Katasteradresse",
+    "Kontaktweg",
     "Konzessionsabgabe",
     "Kostenblock",
     "Kostenposition",
@@ -77,7 +78,6 @@
     "RegionalerAufAbschlag",
     "RegionaleTarifpreisposition",
     "Regionskriterium",
-    "Rufnummer",
     "Sigmoidparameter",
     "StandorteigenschaftenGas",
     "StandorteigenschaftenStrom",
@@ -145,6 +145,7 @@
     "NetznutzungRechnungstyp",
     "Oekolabel",
     "Oekozertifikat",
+    "Organisationstyp",
     "Preisgarantietyp",
     "Preismodell",
     "Preisstatus",
@@ -155,7 +156,6 @@
     "Regionskriteriumtyp",
     "Registeranzahl",
     "Rollencodetyp",
-    "Rufnummernart",
     "Sparte",
     "Steuerkennzeichen",
     "StrEnum",
@@ -188,7 +188,6 @@
 
 # Import BOs
 from .bo.angebot import Angebot
-from .bo.ansprechpartner import Ansprechpartner
 from .bo.ausschreibung import Ausschreibung
 from .bo.buendelvertrag import Buendelvertrag
 from .bo.energiemenge import Energiemenge
@@ -201,6 +200,7 @@
 from .bo.marktlokation import Marktlokation
 from .bo.marktteilnehmer import Marktteilnehmer
 from .bo.messlokation import Messlokation
+from .bo.person import Person
 from .bo.preisblatt import Preisblatt
 from .bo.preisblattdienstleistung import PreisblattDienstleistung
 from .bo.preisblatthardware import PreisblattHardware
@@ -239,6 +239,7 @@
 from .com.fremdkostenposition import Fremdkostenposition
 from .com.geokoordinaten import Geokoordinaten
 from .com.katasteradresse import Katasteradresse
+from .com.kontaktweg import Kontaktweg
 from .com.konzessionsabgabe import Konzessionsabgabe
 from .com.kostenblock import Kostenblock
 from .com.kostenposition import Kostenposition
@@ -258,7 +259,6 @@
 from .com.regionaleraufabschlag import RegionalerAufAbschlag
 from .com.regionaletarifpreisposition import RegionaleTarifpreisposition
 from .com.regionskriterium import Regionskriterium
-from .com.rufnummer import Rufnummer
 from .com.sigmoidparameter import Sigmoidparameter
 from .com.standorteigenschaftengas import StandorteigenschaftenGas
 from .com.standorteigenschaftenstrom import StandorteigenschaftenStrom
@@ -328,6 +328,7 @@
 from .enum.netznutzungrechnungstyp import NetznutzungRechnungstyp
 from .enum.oekolabel import Oekolabel
 from .enum.oekozertifikat import Oekozertifikat
+from .enum.organisationstyp import Organisationstyp
 from .enum.preisgarantietyp import Preisgarantietyp
 from .enum.preismodell import Preismodell
 from .enum.preisstatus import Preisstatus
@@ -338,7 +339,6 @@
 from .enum.regionskriteriumtyp import Regionskriteriumtyp
 from .enum.registeranzahl import Registeranzahl
 from .enum.rollencodetyp import Rollencodetyp
-from .enum.rufnummernart import Rufnummernart
 from .enum.sparte import Sparte
 from .enum.steuerkennzeichen import Steuerkennzeichen
 from .enum.strenum import StrEnum

src/bo4e/bo/angebot.py

@@ -14,9 +14,9 @@
 from ..enum.sparte import Sparte
 from ..enum.typ import Typ
 from ..utils import postprocess_docstring
-from .ansprechpartner import Ansprechpartner
 from .geschaeftsobjekt import Geschaeftsobjekt
 from .geschaeftspartner import Geschaeftspartner
+from .person import Person
 
 
 @postprocess_docstring
@@ -59,6 +59,6 @@ class Angebot(Geschaeftsobjekt):
     #: Bis zu diesem Zeitpunkt (Tag/Uhrzeit) inklusive gilt das Angebot
     bindefrist: Optional[datetime] = None
     #: Person, die als Angebotsnehmer das Angebot angenommen hat
-    unterzeichner_angebotsnehmer: Optional[Ansprechpartner] = None
+    unterzeichner_angebotsnehmer: Optional[Person] = None
     #: Person, die als Angebotsgeber das Angebots ausgestellt hat
-    unterzeichner_angebotsgeber: Optional[Ansprechpartner] = None
+    unterzeichner_angebotsgeber: Optional[Person] = None

src/bo4e/bo/ansprechpartner.py

@@ -2,18 +2,22 @@
 Contains Geschaeftspartner class
 and corresponding marshmallow schema for de-/serialization
 """
-# pylint: disable=too-many-instance-attributes, too-few-public-methods
+
+# pylint: disable=too-many-instance-attributes, too-few-public-methods, disable=duplicate-code
 from typing import Annotated, Optional
 
 from pydantic import Field
 
 from ..com.adresse import Adresse
+from ..com.kontaktweg import Kontaktweg
 from ..enum.anrede import Anrede
 from ..enum.geschaeftspartnerrolle import Geschaeftspartnerrolle
-from ..enum.kontaktart import Kontaktart
+from ..enum.organisationstyp import Organisationstyp
+from ..enum.titel import Titel
 from ..enum.typ import Typ
 from ..utils import postprocess_docstring
 from .geschaeftsobjekt import Geschaeftsobjekt
+from .person import Person
 
 
 @postprocess_docstring
@@ -34,53 +38,45 @@ class Geschaeftspartner(Geschaeftsobjekt):
     """
 
     typ: Annotated[Optional[Typ], Field(alias="_typ")] = Typ.GESCHAEFTSPARTNER
-    name1: Optional[str] = None
+    #: Mögliche Anrede der Person
+    anrede: Optional[Anrede] = None
+    individuelle_anrede: Optional[str] = None
     """
-    Erster Teil des Namens.
-    Hier kann der Firmenname oder bei Privatpersonen beispielsweise der Nachname dagestellt werden.
-    Beispiele: Yellow Strom GmbH oder Hagen
+    Im Falle einer nicht standardisierten Anrede kann hier eine frei definierbare Anrede vorgegeben werden.
+    Beispiel: "Vereinsgemeinschaft", "Pfarrer", "Hochwürdigster Herr Abt".
     """
-    # todo: replace name1/2/3 with something more readable. no one wants to deal with that. maybe serialize as name1/2/3
-    # but resolve to readable python fields under the hood
+    #: Möglicher Titel der Person
+    titel: Optional[Titel] = None
+    #: Vorname der Person
+    vorname: Optional[str] = None
+    #: Nachname (Familienname) der Person
+    nachname: Optional[str] = None
 
-    ist_gewerbe: Optional[bool] = None
+    ansprechpartner: Optional[list[Person]] = None
+    organisationstyp: Optional[Organisationstyp] = None
     """
-    Kennzeichnung ob es sich um einen Gewerbe/Unternehmen (istGewerbe = true)
-    oder eine Privatperson handelt. (istGewerbe = false)
+    Kennzeichnung ob es sich um ein Gewerbe/Unternehmen, eine Privatperson oder eine andere Art von Organisation handelt.
     """
-    #: Rollen, die die Geschäftspartner inne haben (z.B. Interessent, Kunde)
-    geschaeftspartnerrolle: Optional[list[Geschaeftspartnerrolle]] = None
-    # todo: rename to plural
-
-    #: Die Anrede für den GePa, Z.B. "Herr"
-    anrede: Optional[Anrede] = None
-    name2: Optional[str] = None
+    organisationsname: Optional[str] = None
     """
-    Zweiter Teil des Namens.
-    Hier kann der eine Erweiterung zum Firmennamen oder bei Privatpersonen beispielsweise der Vorname dagestellt werden.
-    Beispiele: Bereich Süd oder Nina
-    """
-
-    name3: Optional[str] = None
-    """
-    Dritter Teil des Namens.
-    Hier können weitere Ergänzungen zum Firmennamen oder bei Privatpersonen Zusätze zum Namen dagestellt werden.
-    Beispiele: und Afrika oder Sängerin
+    Name der Firma, wenn Gewerbe oder andere Organisation.
     """
+    #: Kontaktwege des Geschäftspartners
+    kontaktwege: Optional[list[Kontaktweg]] = None
+    #: Rollen, die die Geschäftspartner inne haben (z.B. Interessent, Kunde)
+    geschaeftspartnerrollen: Optional[list[Geschaeftspartnerrolle]] = None
     #: Handelsregisternummer des Geschäftspartners
-    hrnummer: Optional[str] = None
+    handelsregisternummer: Optional[str] = None
     #: Amtsgericht bzw Handelsregistergericht, das die Handelsregisternummer herausgegeben hat
     amtsgericht: Optional[str] = None
-    #: Bevorzugte Kontaktwege des Geschäftspartners
-    kontaktweg: Optional[list[Kontaktart]] = None
     #: Die Steuer-ID des Geschäftspartners; Beispiel: "DE 813281825"
     umsatzsteuer_id: Optional[str] = None
     #: Die Gläubiger-ID welche im Zahlungsverkehr verwendet wird; Z.B. "DE 47116789"
     glaeubiger_id: Optional[str] = None
-    #: E-Mail-Adresse des Ansprechpartners. Z.B. "info@hochfrequenz.de"
-    e_mail_adresse: Optional[str] = None
     #: Internetseite des Marktpartners
     website: Optional[str] = None
-    #: Adressen der Geschäftspartner, an denen sich der Hauptsitz befindet
-    partneradresse: Optional[Adresse] = None  # todo: is it plural or not? the docs are bad
+    #: Adresse des Geschäftspartners
+    adresse: Optional[Adresse] = None
     #: Todo: Add optional connection to marktteilnehmer as discussed in workshop
+    #: not clear what is the best solution here - circular import marktteilnehmer?
+    #: discussed in workshop on Feb 6 2024: yes we need the bidirectional option, let's figure out a solution somehow.

src/bo4e/bo/geschaeftspartner.py

@@ -15,11 +15,12 @@
 from ..enum.sparte import Sparte
 from ..enum.typ import Typ
 from ..utils import postprocess_docstring
+from .geschaeftsobjekt import Geschaeftsobjekt
 from .geschaeftspartner import Geschaeftspartner
 
 
 @postprocess_docstring
-class Marktteilnehmer(Geschaeftspartner):
+class Marktteilnehmer(Geschaeftsobjekt):
     """
     Objekt zur Aufnahme der Information zu einem Marktteilnehmer
 
@@ -41,6 +42,7 @@ class Marktteilnehmer(Geschaeftspartner):
     rollencodetyp: Optional[Rollencodetyp] = None
     #: Sparte des Marktteilnehmers, z.B. Gas oder Strom
     sparte: Optional[Sparte] = None
-
-    #: Die 1:1-Kommunikationsadresse des Marktteilnehmers; Diese wird in der Marktkommunikation verwendet.
-    makoadresse: Optional[str] = None
+    #: Die 1:1-Kommunikationsadresse des Marktteilnehmers. Diese wird in der Marktkommunikation verwendet. Konkret kann dies eine eMail-Adresse oder ein AS4-Endpunkt sein.
+    makoadresse: Optional[list[str]] = None
+    #: Der zu diesem Marktteilnehmer gehörende Geschäftspartner
+    geschaeftspartner: Optional[Geschaeftspartner] = None

src/bo4e/bo/marktteilnehmer.py

@@ -0,0 +1,60 @@
+"""
+Contains Person class
+and corresponding marshmallow schema for de-/serialization
+"""
+
+from datetime import datetime
+from typing import Annotated, Optional
+
+from pydantic import Field
+
+from ..com.adresse import Adresse
+from ..com.kontaktweg import Kontaktweg
+from ..com.zustaendigkeit import Zustaendigkeit
+from ..enum.anrede import Anrede
+from ..enum.titel import Titel
+from ..enum.typ import Typ
+from ..utils import postprocess_docstring
+from .geschaeftsobjekt import Geschaeftsobjekt
+
+# pylint: disable=too-many-instance-attributes, too-few-public-methods, disable=duplicate-code
+
+
+@postprocess_docstring
+class Person(Geschaeftsobjekt):
+    """
+    Object containing information about a Person
+
+    .. raw:: html
+
+        <object data="../_static/images/bo4e/bo/Person.svg" type="image/svg+xml"></object>
+
+    .. HINT::
+        `Person JSON Schema <https://json-schema.app/view/%23?url=https://raw.githubusercontent.com/Hochfrequenz/BO4E-Schemas/{__gh_version__}/src/bo4e_schemas/bo/Person.json>`_
+
+    """
+
+    typ: Annotated[Optional[Typ], Field(alias="_typ")] = Typ.PERSON
+    #: Mögliche Anrede der Person
+    anrede: Optional[Anrede] = None
+    individuelle_anrede: Optional[str] = None
+    """
+    Im Falle einer nicht standardisierten Anrede kann hier eine frei definierbare Anrede vorgegeben werden.
+    Beispiel: "Vereinsgemeinschaft", "Pfarrer", "Hochwürdigster Herr Abt".
+    """
+    #: Möglicher Titel der Person
+    titel: Optional[Titel] = None
+    #: Vorname der Person
+    vorname: Optional[str] = None
+    #: Nachname (Familienname) der Person
+    nachname: Optional[str] = None
+    #: Kontaktwege der Person
+    kontaktwege: Optional[list[Kontaktweg]] = None
+    #: Geburtsdatum der Person
+    geburtsdatum: Optional[datetime] = None
+    #: Weitere Informationen zur Person
+    kommentar: Optional[str] = None
+    #: Liste der Abteilungen und Zuständigkeiten der Person
+    zustaendigkeiten: Optional[list[Zustaendigkeit]] = None
+    #: Adresse der Person, falls diese von der Adresse des Geschäftspartners abweicht
+    adresse: Optional[Adresse] = None