officials

kloppy/domain/models/common.py

@@ -20,7 +20,7 @@
 
 from .position import PositionType
 
-from ...utils import deprecated
+from ...utils import deprecated, snake_case
 
 if sys.version_info >= (3, 8):
     from typing import Literal
@@ -120,14 +120,23 @@ def __str__(self):
 
 
 class OfficialType(Enum):
-    VideoAssistantReferee = "video_assistant_referee"
-    MainReferee = "main_referee"
-    AssistantReferee = "assistant_referee"
-    FourthOfficial = "fourth_official"
+    """Enumeration for types of officials (referees)."""
+
+    VideoAssistantReferee = "Video Assistant Referee"
+    MainReferee = "Main Referee"
+    AssistantReferee = "Assistant Referee"
+    FourthOfficial = "Fourth Official"
+
+    def __str__(self):
+        return self.value
 
 
 @dataclass(frozen=True)
 class Official:
+    """
+    Represents an official (referee) with optional names and roles.
+    """
+
     official_id: str
     name: Optional[str] = None
     first_name: Optional[str] = None
@@ -136,14 +145,17 @@ class Official:
 
     @property
     def full_name(self):
+        """
+        Returns the full name of the official, falling back to role-based or ID-based naming.
+        """
         if self.name:
             return self.name
         if self.first_name and self.last_name:
             return f"{self.first_name} {self.last_name}"
         if self.last_name:
             return self.last_name
         if self.role:
-            return f"{self.role}_{self.official_id}"
+            return f"{snake_case(str(self.role))}_{self.official_id}"
         return f"official_{self.official_id}"
 
 

kloppy/tests/test_sportec.py

@@ -16,6 +16,8 @@
     BallState,
     Point3D,
     PositionType,
+    OfficialType,
+    Official,
 )
 
 from kloppy import sportec
@@ -252,3 +254,43 @@ def test_referees(self, raw_data_referee: Path, meta_data: Path):
             only_alive=True,
         )
         assert len(dataset.metadata.officials) == 4
+
+        assert (
+            Official(
+                official_id="42",
+                name="Pierluigi Collina",
+                role=OfficialType.MainReferee,
+            ).role.value
+            == "Main Referee"
+        )
+
+        assert (
+            Official(
+                official_id="42",
+                name="Pierluigi Collina",
+                role=OfficialType.MainReferee,
+            ).full_name
+            == "Pierluigi Collina"
+        )
+        assert (
+            Official(
+                official_id="42",
+                first_name="Pierluigi",
+                last_name="Collina",
+                role=OfficialType.MainReferee,
+            ).full_name
+            == "Pierluigi Collina"
+        )
+        assert (
+            Official(
+                official_id="42",
+                last_name="Collina",
+                role=OfficialType.MainReferee,
+            ).full_name
+            == "Collina"
+        )
+        assert (
+            Official(official_id="42", role=OfficialType.MainReferee).full_name
+            == "main_referee_42"
+        )
+        assert Official(official_id="42").full_name == "official_42"

kloppy/utils.py

@@ -169,3 +169,8 @@ def __get__(self, instance, owner):
             stacklevel=2,
         )
         return self.value
+
+
+def snake_case(s: str) -> str:
+    """Convert a string to snake_case."""
+    return re.sub(r"[\s\-]+", "_", s.strip()).lower()