audiometa-python 0.6.0__py3-none-any.whl

audiometa/test/tests/unit/metadata_managers/metadata_field/test_validation.py

@@ -0,0 +1,83 @@
+import pytest
+
+from audiometa import validate_metadata_for_update
+from audiometa.utils.unified_metadata_key import UnifiedMetadataKey
+
+
+@pytest.mark.unit
+class TestValidateMetadata:
+    """Test the integrate validate_metadata_for_update function.
+
+    This class tests the high-level validation function that integrates multiple validation layers. Specific field
+    validation (type, format) is tested separately in metadata_field/ test files.
+    """
+
+    def test_empty_dict_raises_error(self):
+        with pytest.raises(ValueError, match="no metadata fields specified"):
+            validate_metadata_for_update({})
+
+    def test_none_values_allowed(self):
+        validate_metadata_for_update({UnifiedMetadataKey.TITLE: None})
+
+        validate_metadata_for_update(
+            {
+                UnifiedMetadataKey.TITLE: None,
+                UnifiedMetadataKey.ARTISTS: None,
+                UnifiedMetadataKey.ALBUM: None,
+            }
+        )
+
+    def test_empty_string_allowed(self):
+        validate_metadata_for_update({UnifiedMetadataKey.TITLE: ""})
+
+    def test_empty_list_allowed(self):
+        validate_metadata_for_update({UnifiedMetadataKey.ARTISTS: []})
+
+    def test_list_with_none_values_allowed(self):
+        validate_metadata_for_update({UnifiedMetadataKey.ARTISTS: [None, None]})
+        validate_metadata_for_update({UnifiedMetadataKey.ARTISTS: [None]})
+        validate_metadata_for_update({UnifiedMetadataKey.GENRES_NAMES: [None, None, None]})
+
+    def test_empty_string_and_empty_list_allowed(self):
+        validate_metadata_for_update({UnifiedMetadataKey.TITLE: "", UnifiedMetadataKey.ARTISTS: []})
+
+    def test_valid_metadata_passes(self):
+        validate_metadata_for_update({UnifiedMetadataKey.TITLE: "Song Title"})
+        validate_metadata_for_update({UnifiedMetadataKey.ARTISTS: ["Artist 1", "Artist 2"]})
+        validate_metadata_for_update({UnifiedMetadataKey.ALBUM: "Album Name"})
+
+    def test_multiple_valid_fields_passes(self):
+        validate_metadata_for_update(
+            {
+                UnifiedMetadataKey.TITLE: "Song Title",
+                UnifiedMetadataKey.ARTISTS: ["Artist"],
+                UnifiedMetadataKey.ALBUM: "Album",
+            }
+        )
+
+    def test_mixed_none_and_valid_fields_passes(self):
+        validate_metadata_for_update(
+            {
+                UnifiedMetadataKey.TITLE: None,
+                UnifiedMetadataKey.ARTISTS: ["Artist"],
+            }
+        )
+
+    def test_combined_validation_rating_and_release_date(self):
+        validate_metadata_for_update(
+            {
+                UnifiedMetadataKey.RATING: 50,
+                UnifiedMetadataKey.RELEASE_DATE: "2024-01-01",
+            },
+            normalized_rating_max_value=100,
+        )
+
+    def test_combined_validation_with_empty_fields(self):
+        validate_metadata_for_update(
+            {
+                UnifiedMetadataKey.TITLE: "",
+                UnifiedMetadataKey.ARTISTS: [],
+                UnifiedMetadataKey.RATING: 50,
+            },
+            normalized_rating_max_value=100,
+        )

audiometa/test/tests/unit/metadata_managers/test_metadata_format_managers_write_and_read.py

@@ -0,0 +1,74 @@
+import pytest
+
+from audiometa._audio_file import _AudioFile
+from audiometa.manager._rating_supporting.id3v2._Id3v2Manager import _Id3v2Manager as Id3v2Manager
+from audiometa.manager._rating_supporting.riff._RiffManager import _RiffManager as RiffManager
+from audiometa.manager._rating_supporting.vorbis._VorbisManager import _VorbisManager as VorbisManager
+from audiometa.manager.id3v1._Id3v1Manager import _Id3v1Manager as Id3v1Manager
+from audiometa.manager.id3v1.id3v1_raw_metadata_key import Id3v1RawMetadataKey
+from audiometa.test.helpers.temp_file_with_metadata import temp_file_with_metadata
+from audiometa.utils.unified_metadata_key import UnifiedMetadataKey
+
+
+@pytest.mark.unit
+class TestMetadataFormatManagersWriteAndRead:
+    def test_id3v1_manager_write_and_read(self):
+        with temp_file_with_metadata({}, "mp3") as test_file:
+            audio_file = _AudioFile(test_file)
+            manager = Id3v1Manager(audio_file)
+
+            manager.update_metadata(
+                {UnifiedMetadataKey.TITLE: "Test Title", UnifiedMetadataKey.ARTISTS: ["Test Artist"]}
+            )
+
+            raw_metadata = manager._extract_mutagen_metadata()
+
+            assert raw_metadata.tags.get(Id3v1RawMetadataKey.TITLE) == ["Test Title"]
+            assert raw_metadata.tags.get(Id3v1RawMetadataKey.ARTISTS_NAMES_STR) == ["Test Artist"]
+
+    def test_id3v2_manager_write_and_read(self):
+        with temp_file_with_metadata({}, "mp3") as test_file:
+            audio_file = _AudioFile(test_file)
+            manager = Id3v2Manager(audio_file)
+
+            manager.update_metadata(
+                {UnifiedMetadataKey.TITLE: "Test Title", UnifiedMetadataKey.ARTISTS: ["Test Artist"]}
+            )
+
+            raw_metadata = manager._extract_mutagen_metadata()
+
+            assert Id3v2Manager.Id3TextFrame.TITLE in raw_metadata
+            assert str(raw_metadata[Id3v2Manager.Id3TextFrame.TITLE][0]) == "Test Title"
+            assert Id3v2Manager.Id3TextFrame.ARTISTS in raw_metadata
+            artists_text = str(raw_metadata[Id3v2Manager.Id3TextFrame.ARTISTS][0])
+            assert "Test Artist" in artists_text
+
+    def test_riff_manager_write_and_read(self):
+        with temp_file_with_metadata({}, "wav") as test_file:
+            audio_file = _AudioFile(test_file)
+            manager = RiffManager(audio_file)
+
+            manager.update_metadata(
+                {UnifiedMetadataKey.TITLE: "Test Title", UnifiedMetadataKey.ARTISTS: ["Test Artist"]}
+            )
+
+            raw_metadata = manager._extract_mutagen_metadata()
+
+            assert hasattr(raw_metadata, "info")
+            info_tags = getattr(raw_metadata, "info", {})
+            assert info_tags.get(RiffManager.RiffTagKey.TITLE) == ["Test Title"]
+            assert info_tags.get(RiffManager.RiffTagKey.ARTIST) == ["Test Artist"]
+
+    def test_vorbis_manager_write_and_read(self):
+        with temp_file_with_metadata({}, "flac") as test_file:
+            audio_file = _AudioFile(test_file)
+            manager = VorbisManager(audio_file)
+
+            manager.update_metadata(
+                {UnifiedMetadataKey.TITLE: "Test Title", UnifiedMetadataKey.ARTISTS: ["Test Artist"]}
+            )
+
+            raw_metadata = manager._extract_mutagen_metadata()
+
+            assert raw_metadata.get(VorbisManager.VorbisKey.TITLE) == ["Test Title"]
+            assert raw_metadata.get(VorbisManager.VorbisKey.ARTIST) == ["Test Artist"]

audiometa/test/tests/unit/metadata_managers/test_riff_configuration_error.py

@@ -0,0 +1,26 @@
+from unittest.mock import MagicMock
+
+import pytest
+
+from audiometa.exceptions import ConfigurationError
+from audiometa.manager._rating_supporting.riff._RiffManager import _RiffManager as RiffManager
+from audiometa.utils.unified_metadata_key import UnifiedMetadataKey
+
+
+@pytest.mark.unit
+class TestRiffManagerConfigurationError:
+    def test_update_not_using_mutagen_metadata_raises_configuration_error_when_metadata_keys_direct_map_write_is_none(
+        self,
+    ):
+        wave_audio_file = MagicMock()
+        wave_audio_file.file_extension = ".wav"
+        riff_manager = RiffManager(audio_file=wave_audio_file, normalized_rating_max_value=10)
+
+        # Manually set metadata_keys_direct_map_write to None to test the error condition
+        riff_manager.metadata_keys_direct_map_write = None
+
+        unified_metadata = {UnifiedMetadataKey.TITLE: "Test Title"}
+
+        with pytest.raises(ConfigurationError) as exc_info:
+            riff_manager._update_not_using_mutagen_metadata(unified_metadata)
+        assert "metadata_keys_direct_map_write must be set" in str(exc_info.value)

audiometa/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility classes and functions for audio metadata processing."""

audiometa/utils/id3v1_genre_code_map.py

@@ -0,0 +1,205 @@
+"""Standard ID3v1 genre codes mapping.
+
+This is the complete standard genre map used by both ID3v1 and RIFF formats. Genres 0-79 are from the original ID3v1
+spec. Genres 80-125 were added by Winamp. Genres 126-147 were added by other players. Genres 148-191 were added in
+Winamp 5.6 (November 2010).
+"""
+
+ID3V1_GENRE_CODE_MAP = {
+    0: "Blues",
+    1: "Classic Rock",
+    2: "Country",
+    3: "Dance",
+    4: "Disco",
+    5: "Funk",
+    6: "Grunge",
+    7: "Hip-Hop",
+    8: "Jazz",
+    9: "Metal",
+    10: "New Age",
+    11: "Oldies",
+    12: "Other",
+    13: "Pop",
+    14: "R&B",
+    15: "Rap",
+    16: "Reggae",
+    17: "Rock",
+    18: "Techno",
+    19: "Industrial",
+    20: "Alternative",
+    21: "Ska",
+    22: "Death Metal",
+    23: "Pranks",
+    24: "Soundtrack",
+    25: "Euro-Techno",
+    26: "Ambient",
+    27: "Trip-Hop",
+    28: "Vocal",
+    29: "Jazz+Funk",
+    30: "Fusion",
+    31: "Trance",
+    32: "Classical",
+    33: "Instrumental",
+    34: "Acid",
+    35: "House",
+    36: "Game",
+    37: "Sound Clip",
+    38: "Gospel",
+    39: "Noise",
+    40: "Alternative Rock",
+    41: "Bass",
+    42: "Soul",
+    43: "Punk",
+    44: "Space",
+    45: "Meditative",
+    46: "Instrumental Pop",
+    47: "Instrumental Rock",
+    48: "Ethnic",
+    49: "Gothic",
+    50: "Darkwave",
+    51: "Techno-Industrial",
+    52: "Electronic",
+    53: "Pop-Folk",
+    54: "Eurodance",
+    55: "Dream",
+    56: "Southern Rock",
+    57: "Comedy",
+    58: "Cult",
+    59: "Gangsta",
+    60: "Top 40",
+    61: "Christian Rap",
+    62: "Pop/Funk",
+    63: "Jungle",
+    64: "Native US",
+    65: "Cabaret",
+    66: "New Wave",
+    67: "Psychedelic",
+    68: "Rave",
+    69: "Showtunes",
+    70: "Trailer",
+    71: "Lo-Fi",
+    72: "Tribal",
+    73: "Acid Punk",
+    74: "Acid Jazz",
+    75: "Polka",
+    76: "Retro",
+    77: "Musical",
+    78: "Rock & Roll",
+    79: "Hard Rock",
+    # Winamp extensions
+    80: "Folk",
+    81: "Folk-Rock",
+    82: "National Folk",
+    83: "Swing",
+    84: "Fast Fusion",
+    85: "Bebop",
+    86: "Latin",
+    87: "Revival",
+    88: "Celtic",
+    89: "Bluegrass",
+    90: "Avantgarde",
+    91: "Gothic Rock",
+    92: "Progressive Rock",
+    93: "Psychedelic Rock",
+    94: "Symphonic Rock",
+    95: "Slow Rock",
+    96: "Big Band",
+    97: "Chorus",
+    98: "Easy Listening",
+    99: "Acoustic",
+    100: "Humour",
+    101: "Speech",
+    102: "Chanson",
+    103: "Opera",
+    104: "Chamber Music",
+    105: "Sonata",
+    106: "Symphony",
+    107: "Booty Bass",
+    108: "Primus",
+    109: "Porn Groove",
+    110: "Satire",
+    111: "Slow Jam",
+    112: "Club",
+    113: "Tango",
+    114: "Samba",
+    115: "Folklore",
+    116: "Ballad",
+    117: "Power Ballad",
+    118: "Rhythmic Soul",
+    119: "Freestyle",
+    120: "Duet",
+    121: "Punk Rock",
+    122: "Drum Solo",
+    123: "A Cappella",
+    124: "Euro-House",
+    125: "Dance Hall",
+    # Other extensions
+    126: "Goa",
+    127: "Drum & Bass",
+    128: "Club-House",
+    129: "Hardcore",
+    130: "Terror",
+    131: "Indie",
+    132: "BritPop",
+    133: "Negerpunk",
+    134: "Polsk Punk",
+    135: "Beat",
+    136: "Christian Gangsta Rap",
+    137: "Heavy Metal",
+    138: "Black Metal",
+    139: "Crossover",
+    140: "Contemporary Christian",
+    141: "Christian Rock",
+    142: "Merengue",
+    143: "Salsa",
+    144: "Thrash Metal",
+    145: "Anime",
+    146: "JPop",
+    147: "Synthpop",
+    # Winamp 5.6 extensions (November 2010)
+    148: "Christmas",
+    149: "Art Rock",
+    150: "Baroque",
+    151: "Bhangra",
+    152: "Big Beat",
+    153: "Breakbeat",
+    154: "Chillout",
+    155: "Downtempo",
+    156: "Dub",
+    157: "EBM",
+    158: "Eclectic",
+    159: "Electro",
+    160: "Electroclash",
+    161: "Emo",
+    162: "Experimental",
+    163: "Garage",
+    164: "Global",
+    165: "IDM",
+    166: "Illbient",
+    167: "Industro-Goth",
+    168: "Jam Band",
+    169: "Krautrock",
+    170: "Leftfield",
+    171: "Lounge",
+    172: "Math Rock",
+    173: "New Romantic",
+    174: "Nu-Breakz",
+    175: "Post-Punk",
+    176: "Post-Rock",
+    177: "Psytrance",
+    178: "Shoegaze",
+    179: "Space Rock",
+    180: "Trop Rock",
+    181: "World Music",
+    182: "Neoclassical",
+    183: "Audiobook",
+    184: "Audio Theatre",
+    185: "Neue Deutsche Welle",
+    186: "Podcast",
+    187: "Indie Rock",
+    188: "G-Funk",
+    189: "Dubstep",
+    190: "Garage Rock",
+    191: "Psybient",
+    255: None,
+}

audiometa/utils/metadata_format.py

@@ -0,0 +1,31 @@
+"""Tag type constants for audio metadata handling.
+
+This module defines the supported metadata formats and their file extension priorities for reading and writing audio
+metadata across different file types.
+"""
+
+from enum import Enum
+
+
+class MetadataFormat(str, Enum):
+    """Enumeration of supported audio metadata formats."""
+
+    ID3V2 = "id3v2"
+    ID3V1 = "id3v1"
+    VORBIS = "vorbis"
+    RIFF = "riff"
+
+    @classmethod
+    def get_priorities(cls) -> dict[str, list["MetadataFormat"]]:
+        """Get tag format priorities for different file formats.
+
+        First tag format in each list has highest priority.
+
+        Returns:
+            dictionary mapping file extensions to ordered list of tag types
+        """
+        return {
+            ".flac": [cls.VORBIS, cls.ID3V2, cls.ID3V1],
+            ".mp3": [cls.ID3V2, cls.ID3V1],
+            ".wav": [cls.RIFF, cls.ID3V2, cls.ID3V1],
+        }

audiometa/utils/metadata_writing_strategy.py

@@ -0,0 +1,16 @@
+"""Metadata writing strategy constants for audio metadata handling."""
+
+from enum import Enum
+
+
+class MetadataWritingStrategy(str, Enum):
+    """Strategy for handling metadata when writing to files with existing metadata in other formats."""
+
+    SYNC = "sync"
+    """Write to native format and synchronize other metadata formats that are already present (default)."""
+
+    PRESERVE = "preserve"
+    """Write to native format only, preserve existing metadata in other formats."""
+
+    CLEANUP = "cleanup"
+    """Write to native format and remove all non-native metadata formats."""

audiometa/utils/mutagen_exception_handler.py

@@ -0,0 +1,24 @@
+"""Utility functions for handling mutagen exceptions."""
+
+from audiometa.exceptions import FileCorruptedError
+
+
+def handle_mutagen_exception(operation: str, file_path: str, exception: Exception) -> None:
+    """Handle exceptions from mutagen operations.
+
+    Re-raises standard I/O exceptions as-is and converts other exceptions
+    (including mutagen-specific ones) to FileCorruptedError.
+
+    Args:
+        operation: Description of the operation being performed (e.g., "save metadata", "extract RIFF metadata from")
+        file_path: Path to the file being operated on
+        exception: The exception that was raised
+
+    Raises:
+        IOError, OSError, PermissionError: Re-raised as-is for standard I/O errors
+        FileCorruptedError: Raised for mutagen-specific or other unexpected exceptions
+    """
+    if isinstance(exception, IOError | OSError | PermissionError):
+        raise exception
+    msg = f"Failed to {operation} {file_path}: {exception!s}"
+    raise FileCorruptedError(msg) from exception

audiometa/utils/os_dependencies_checker/__init__.py

@@ -0,0 +1,24 @@
+"""OS-specific dependency checkers for verifying system dependencies."""
+
+import platform
+
+from audiometa.utils.os_dependencies_checker.base import OsDependenciesChecker
+from audiometa.utils.os_dependencies_checker.macos import MacOSDependenciesChecker
+from audiometa.utils.os_dependencies_checker.ubuntu import UbuntuDependenciesChecker
+from audiometa.utils.os_dependencies_checker.windows import WindowsDependenciesChecker
+
+
+def get_dependencies_checker() -> OsDependenciesChecker | None:
+    """Get the appropriate OS-specific dependencies checker.
+
+    Returns:
+        OS-specific checker instance, or None if OS not supported
+    """
+    system = platform.system().lower()
+    if system == "darwin":
+        return MacOSDependenciesChecker()
+    if system == "linux":
+        return UbuntuDependenciesChecker()
+    if system == "windows":
+        return WindowsDependenciesChecker()
+    return None

audiometa/utils/os_dependencies_checker/base.py

@@ -0,0 +1,62 @@
+"""Base class for OS-specific dependency checkers."""
+
+from abc import ABC, abstractmethod
+
+
+class OsDependenciesChecker(ABC):
+    """Base class for OS-specific dependency checkers."""
+
+    @classmethod
+    @abstractmethod
+    def get_os_type(cls) -> str:
+        """Get OS type identifier."""
+
+    @abstractmethod
+    def check_tool_available(self, tool_name: str) -> bool:
+        """Check if a tool is available (in PATH or default locations).
+
+        Args:
+            tool_name: Name of the tool to check
+
+        Returns:
+            True if tool is available, False otherwise
+        """
+
+    @abstractmethod
+    def get_installed_version(self, package: str, expected_version: str | None = None) -> str | None:
+        """Get installed version of a package.
+
+        Args:
+            package: Package name
+            expected_version: Optional expected/pinned version
+
+        Returns:
+            Installed version string, or None if not found
+        """
+
+    @staticmethod
+    def _normalize_version(version: str) -> str:
+        """Normalize version string by removing revision suffix.
+
+        Args:
+            version: Version string (e.g., "7.1_4" or "1.5.0")
+
+        Returns:
+            Normalized version without revision suffix
+        """
+        return version.split("_")[0]
+
+    @staticmethod
+    def _versions_match(version1: str, version2: str) -> bool:
+        """Check if two version strings match (handles different precision).
+
+        Args:
+            version1: First version string
+            version2: Second version string
+
+        Returns:
+            True if versions match, False otherwise
+        """
+        v1_normalized = OsDependenciesChecker._normalize_version(version1)
+        v2_normalized = OsDependenciesChecker._normalize_version(version2)
+        return v1_normalized == v2_normalized or v2_normalized.startswith(v1_normalized + ".")

audiometa/utils/os_dependencies_checker/config.py

@@ -0,0 +1,77 @@
+"""Configuration loading for OS-specific dependency checkers."""
+
+import tomllib
+from pathlib import Path
+
+
+def _load_config_file(project_root: Path, filename: str) -> dict | None:
+    """Load a TOML configuration file."""
+    config_path = project_root / filename
+    if not config_path.exists():
+        return None
+
+    try:
+        with config_path.open("rb") as f:
+            return tomllib.load(f)
+    except Exception:
+        return None
+
+
+def load_dependencies_pinned_versions() -> dict[str, dict[str, str]] | None:
+    """Load pinned versions from system-dependencies-prod.toml and system-dependencies-test-only.toml.
+
+    Returns:
+        Dictionary mapping tool names to OS-specific versions, or None if config not found
+    """
+    # Try to find config files relative to this file
+    # This file is in audiometa/utils/os_dependencies_checker/, so go up to project root
+    project_root = Path(__file__).parent.parent.parent.parent
+
+    # Load prod and test configs
+    prod_config = _load_config_file(project_root, "system-dependencies-prod.toml")
+    test_config = _load_config_file(project_root, "system-dependencies-test-only.toml")
+
+    if not prod_config and not test_config:
+        return None
+
+    try:
+        # Merge configs (test can override prod if needed, though they shouldn't overlap)
+        config = {}
+        if prod_config:
+            config.update(prod_config)
+        if test_config:
+            # Merge OS sections
+            for os_type in ["ubuntu", "macos", "windows"]:
+                if os_type in test_config:
+                    if os_type not in config:
+                        config[os_type] = {}
+                    config[os_type].update(test_config[os_type])
+
+        pinned_versions: dict[str, dict[str, str]] = {}
+
+        # Extract versions for each OS
+        for os_type in ["ubuntu", "macos", "windows"]:
+            if os_type not in config:
+                continue
+
+            os_config = config[os_type]
+            for tool in ["ffmpeg", "flac", "mediainfo", "id3v2", "bwfmetaedit", "exiftool"]:
+                if tool not in os_config:
+                    continue
+
+                version_value = os_config[tool]
+                # Handle both string values and dict values (for bwfmetaedit, exiftool on Windows)
+                if isinstance(version_value, str):
+                    version = version_value
+                elif isinstance(version_value, dict) and "pinned_version" in version_value:
+                    version = version_value["pinned_version"]
+                else:
+                    continue
+
+                if tool not in pinned_versions:
+                    pinned_versions[tool] = {}
+                pinned_versions[tool][os_type] = version
+    except Exception:
+        return None
+    else:
+        return pinned_versions