Skip to content

orchestrator

Main orchestrator module for Music Genre Updater.

This module handles the high-level coordination of all operations.

MusicAppNotRunningError 

MusicAppNotRunningError(command)

Bases: Exception

Music.app is closed, so a command that needs it cannot run.

This is a normal state for scheduled runs, not a failure: the caller should skip the run and try again later.

Source code in src/app/orchestrator.py 
32
33
34
def __init__(self, command: str) -> None:
    super().__init__(f"Music.app is not running - skipped '{command}' command")
    self.command = command

Orchestrator 

Orchestrator(deps)

Orchestrates the entire music update workflow.

Attributes:

Name Type Description
COMMANDS_BYPASSING_MUSIC_CHECK set[str]

Commands that skip the Music.app running check.

Parameters:

Name Type Description Default
deps DependencyContainer

Dependency container with all required services

 required
Source code in src/app/orchestrator.py 
50
51
52
53
54
55
def __init__(self, deps: DependencyContainer) -> None:
    self.deps = deps
    self.music_updater = MusicUpdater(deps)
    self.config = deps.app_config
    self.console_logger = deps.console_logger
    self.error_logger = deps.error_logger

run_command async 

run_command(args)

Execute the appropriate command based on arguments.

Parameters:

Name Type Description Default
args Namespace

Parsed command-line arguments from argparse.

 required

Raises:

Type Description
MusicAppNotRunningError

The command needs Music.app and it is not running.
Source code in src/app/orchestrator.py 
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
async def run_command(self, args: argparse.Namespace) -> None:
    """Execute the appropriate command based on arguments.

    Args:
        args: Parsed command-line arguments from argparse.

    Raises:
        MusicAppNotRunningError: The command needs Music.app and it is not running.

    """
    # Reset per-run state
    reset_cleaning_exceptions_log()

    # Handle --fresh flag: clear all caches and snapshots
    if getattr(args, "fresh", False):
        self.console_logger.info("--fresh flag set: clearing all caches and snapshots...")
        await self.deps.cache_service.clear()
        self.deps.library_snapshot_service.clear_snapshot()
        self.console_logger.info("All caches cleared. Will fetch fresh data from Music.app.")

    command = getattr(args, "command", None)

    # Check if Music app is running for commands that depend on it
    if self._requires_music_app(command) and not is_music_app_running(self.error_logger):
        raise MusicAppNotRunningError(command or "default")

    # Set dry-run context if needed
    if args.dry_run or getattr(args, "test_mode", False):
        test_artists = set(self.config.development.test_artists)
        mode = "test" if getattr(args, "test_mode", False) else "dry_run"
        self.music_updater.set_dry_run_context(mode, test_artists)

    # ALWAYS apply test_artists from config if configured (even in --force mode)
    elif test_artists_config := set(self.config.development.test_artists):
        self.console_logger.info("Using test_artists from config in normal mode: %s", sorted(test_artists_config))
        self.music_updater.set_dry_run_context("normal", test_artists_config)

    # Route to an appropriate command
    match args.command:
        case "clean_artist" | "clean":
            await self._run_clean_artist(args)
        case "update_years" | "years":
            await self._run_update_years(args)
        case "update_genres" | "genres":
            await self._run_update_genres(args)
        case "revert_years" | "revert":
            await self._run_revert_years(args)
        case "restore_release_years" | "restore":
            await self._run_restore_release_years(args)
        case "verify_database" | "verify-db":
            await self._run_verify_database(args)
        case "verify_pending" | "pending":
            await self._run_verify_pending(args)
        case "batch":
            await self._run_batch(args)
        case "rotate_keys" | "rotate-keys":
            self._run_rotate_encryption_keys(args)
        case _:
            await self._run_main_workflow(args)