"""
Contratos para provedores de análise musical.

O contrato permite que a aplicação use Essentia, um dublê de teste ou outro
provedor no futuro sem conhecer detalhes de carregamento e classificação.
"""

from pathlib import Path
from typing import Protocol

from .modelos_de_analise_musical import ResultadoDaAnaliseMusical


class AnalisadorDeMusica(Protocol):
    """Define a operação necessária para analisar um arquivo musical."""

    def analisar(self, arquivo: str | Path) -> ResultadoDaAnaliseMusical:
        """
        Analisa um arquivo de música e devolve seus descritores internos.

        Parâmetros:
            arquivo: Caminho de um arquivo de áudio existente.

        Retorna:
            Resultado estruturado da análise musical.

        Pode gerar:
            FileNotFoundError: quando o arquivo não existir.
            RuntimeError: quando Essentia não estiver instalado.
        """

        ...