From 708b8646dd2d9296272cec062d4f60e67ed4a791 Mon Sep 17 00:00:00 2001
From: David Trattnig <david@subsquare.at>
Date: Mon, 24 Jul 2023 15:52:01 +0200
Subject: [PATCH] refact: improve structure, add docstrings
---
src/aura_engine/scheduling/domain.py | 120 +++++++++++++++++++--------
1 file changed, 84 insertions(+), 36 deletions(-)
diff --git a/src/aura_engine/scheduling/domain.py b/src/aura_engine/scheduling/domain.py
index cc5f3ea0..91a092ac 100644
--- a/src/aura_engine/scheduling/domain.py
+++ b/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
--
GitLab