refact: improve structure, add docstrings

src/aura_engine/scheduling/domain.py

@@ -19,11 +19,17 @@
 
 """
 Domain models for scheduling.
+
+These domain models are defined:
+    - Timeslot: A timetable entry.
+    - Playlist: Definition of what should be broadcasted for one timeslot.
+    - PlaylistType: What kind of playlist it is. Either assigned to timeslot, schedule or show.
+    - PlaylistEntry: An element of the playlist, referencing media sources and metadata.
+
 """
 
 from __future__ import annotations
 
-import datetime
 import enum
 
 from aura_engine.core.channels import GenericChannel
@@ -34,44 +40,72 @@ from aura_engine.scheduling.utils import EntryQueueState
 class Timeslot:
     """
     A timeslot in the programme calendar.
+
+    Beside references to playlists, it holds show and episode metadata.
+    Note, some episodes values are inherited from the show,
+    some others are overridden by the episode.
+
+    Attributes:
+        id (int): Timeslot ID as used in Steering and Tank
+        repetition_of_id (int): In case of a re-broadcast it holds a reference
+            to another timeslot ID.
+        start: beginning of timeslot as UNIX epoch.
+        end: ending of timeslot as UNIX epoch.
+
+        paylist_timeslot (Playlist): Playlist assigned directly to the timeslot.
+        playlist_schedule (Playlist): Playlist assigned to the schedule.
+        paylist_show (Playlist): Playlist assigned to the show.
+
+        show_id (int): Show ID as used in Steering and Tank.
+        show_name (str): Name of the show.
+
+        episode_host (list[str]): List of hosts.
+        episode_type (list[str]): List of types.
+        episode_cat (list[str]): List of categories.
+        episode_funding_cat (list[str]): List of funding categories.
+        episode_language (list[str]): List of languages.
+        episode_topic (list[str]): List of topics.
+        episode_music_focus (list[str]): List of music genres.
+        episode_memo: Some notes for the (internal, non-public use only).
     """
 
     id: int
     repetition_of_id = int
-    start: datetime
-    end: datetime
-    memo: str
-    show: Show
+    start: int
+    end: int
+
     playlist_timeslot: Playlist
     playlist_schedule: Playlist
     playlist_show: Playlist
 
+    show_id: int
+    show_name: str
 
-class Show:
-    """
-    The show assigned to the timeslot.
-    """
-
-    id: int
-    name: str
-    hosts: list[str]
-    type: list[str]
-    category: list[str]
-    funding_category: list[str]
-    language: list[str]
-    topic: list[str]
-    musicfocus: list[str]
+    episode_host: list[str]
+    episode_type: list[str]
+    episode_cat: list[str]
+    episode_funding_cat: list[str]
+    episode_language: list[str]
+    episode_topic: list[str]
+    episode_music_focus: list[str]
+    episode_memo: str
 
 
 class Playlist:
     """
     The playlist assigned to a timeslot.
+
+    Attributes:
+        id (int): Playlist ID as used in Steering and Tank.
+        timeslot (Timeslot): Back reference to the timeslot.
+        type (PlaylistType): Indicating type of timeslot playlist.
+        count (int): Count of playlist entries.
+        entries (PlaylistEntry): List of entries.
     """
 
+    id: int
     timeslot: Timeslot
     type: PlaylistType
-
-    id: int
     count: int
     entries: PlaylistEntry
 
@@ -79,6 +113,11 @@ class Playlist:
 class PlaylistType(enum):
     """
     Playlist type defines where it is assigned to the timeslot.
+
+    Attributes:
+        TIMESLOT (str): (TIMESLOT) The playlist is assigned to the timeslot itself.
+        SCHEDULE (str): (SCHEDULE) The playlist is assigned to the schedule.
+        SHOW (str): (SHOW) The playlist is assigned to the show.
     """
 
     TIMESLOT = "playlist_timeslot"
@@ -89,27 +128,36 @@ class PlaylistType(enum):
 class PlaylistEntry:
     """
     The entries of a playlist.
+
+    Attributes:
+        playlist (str): Back reference to playlist.
+        index (int): The index in the playlist.
+        start (int): The start of the entry as UNIX epoch.
+        duration (int): Duration in milliseconds.
+        volume (int): Value from 0-100% indicating loudness.
+        source (str): URI referencing the audio source.
+
+        meta_artist (str): The artist.
+        meta_album (str): The album.
+        meta_title (str): The title.
+
+        play_channel (GenericChannel): Play-out channel, set when entry is starts playing.
+        play_queue_state (EntryQueueState): Progress on queuing, set when entry is queued.
+        play_status (Player.EntryPlayState): Play-out state, set when playing starts.
+
     """
 
     playlist: Playlist
     index: int
-    start: datetime
+    start: int
     duration: int
     volume: int
     source: str
 
-    channel: GenericChannel  # Assigned when entry is actually playing
-    queue_state: EntryQueueState  # Assigned when entry is about to be queued
-    status: Player.EntryPlayState  # Assigned when state changes
-
-    metadata: Metadata
-
-
-class Metadata:
-    """
-    The metadata of an playlist entry.
-    """
+    meta_artist: str
+    meta_album: str
+    meta_title: str
 
-    artist: str
-    title: str
-    album: str
+    play_channel: GenericChannel
+    play_queue_state: EntryQueueState
+    play_status: Player.EntryPlayState