audiometa-python 0.6.0__py3-none-any.whl

audiometa/test/tests/integration/metadata_field/rating/reading/test_base_255_proportional.py

@@ -0,0 +1,58 @@
+from pathlib import Path
+
+import pytest
+
+from audiometa import get_unified_metadata
+from audiometa.utils.unified_metadata_key import UnifiedMetadataKey
+
+
+@pytest.mark.integration
+class TestBase255Proportional:
+    @pytest.mark.parametrize(
+        ("star_rating", "expected_normalized_rating"),
+        [
+            (1, 20),
+            (2, 40),
+            (3, 60),
+            (4, 80),
+            (5, 100),
+        ],
+    )
+    def test_vorbis_flac_traktor(self, assets_dir: Path, star_rating, expected_normalized_rating):
+        file_path = assets_dir / f"rating_vorbis_traktor={star_rating} star.flac"
+        metadata = get_unified_metadata(file_path, normalized_rating_max_value=100)
+        rating = metadata.get(UnifiedMetadataKey.RATING)
+        assert rating is not None
+        assert isinstance(rating, int | float)
+        assert rating == expected_normalized_rating
+
+    def test_none_rating_vorbis_flac_traktor(self, assets_dir: Path):
+        file_path = assets_dir / "rating_vorbis_traktor=none.flac"
+        metadata = get_unified_metadata(file_path, normalized_rating_max_value=100)
+        rating = metadata.get(UnifiedMetadataKey.RATING)
+        assert rating is None
+
+    @pytest.mark.parametrize(
+        ("star_rating", "expected_normalized_rating"),
+        [
+            (1, 20),
+            (2, 40),
+            (3, 60),
+            (4, 80),
+            (5, 100),
+        ],
+    )
+    def test_id3v2_mp3_traktor(self, assets_dir: Path, star_rating, expected_normalized_rating):
+        file_path = assets_dir / f"rating_id3v2_tracktor={star_rating} star.mp3"
+        metadata = get_unified_metadata(file_path, normalized_rating_max_value=100)
+        rating = metadata.get(UnifiedMetadataKey.RATING)
+        assert rating is not None
+        assert isinstance(rating, int | float)
+        assert rating == expected_normalized_rating
+
+    def test_none_rating_id3v2_mp3_traktor(self, assets_dir: Path):
+        file_path = assets_dir / "rating_id3v2_tracktor=none.mp3"
+        metadata = get_unified_metadata(file_path, normalized_rating_max_value=100)
+        rating = metadata.get(UnifiedMetadataKey.RATING)
+        # Traktor "none" may actually be 0, not None
+        assert rating is None or rating == 0

audiometa/test/tests/integration/metadata_field/rating/test_deleting.py

@@ -0,0 +1,117 @@
+import pytest
+
+from audiometa import get_unified_metadata_field, update_metadata
+from audiometa.exceptions import MetadataFieldNotSupportedByMetadataFormatError
+from audiometa.test.helpers.temp_file_with_metadata import temp_file_with_metadata
+from audiometa.utils.metadata_format import MetadataFormat
+from audiometa.utils.unified_metadata_key import UnifiedMetadataKey
+
+
+@pytest.mark.integration
+class TestRatingDeleting:
+    def test_delete_rating_id3v2(self):
+        with temp_file_with_metadata({}, "mp3") as test_file:
+            update_metadata(
+                test_file,
+                {UnifiedMetadataKey.RATING: 50},
+                metadata_format=MetadataFormat.ID3V2,
+                normalized_rating_max_value=100,
+            )
+            assert (
+                get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100) == 50
+            )
+
+            update_metadata(test_file, {UnifiedMetadataKey.RATING: None}, metadata_format=MetadataFormat.ID3V2)
+            assert (
+                get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100)
+                is None
+            )
+
+    def test_delete_rating_id3v1(self):
+        with (
+            temp_file_with_metadata({}, "id3v1") as test_file,
+            pytest.raises(MetadataFieldNotSupportedByMetadataFormatError),
+        ):
+            update_metadata(
+                test_file,
+                {UnifiedMetadataKey.RATING: 50},
+                metadata_format=MetadataFormat.ID3V1,
+                normalized_rating_max_value=100,
+            )
+
+    def test_delete_rating_riff(self):
+        with temp_file_with_metadata({}, "wav") as test_file:
+            update_metadata(
+                test_file,
+                {UnifiedMetadataKey.RATING: 50},
+                metadata_format=MetadataFormat.RIFF,
+                normalized_rating_max_value=100,
+            )
+            assert (
+                get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100) == 50
+            )
+
+            update_metadata(test_file, {UnifiedMetadataKey.RATING: None}, metadata_format=MetadataFormat.RIFF)
+            assert (
+                get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100)
+                is None
+            )
+
+    def test_delete_rating_vorbis(self):
+        with temp_file_with_metadata({}, "flac") as test_file:
+            update_metadata(
+                test_file,
+                {UnifiedMetadataKey.RATING: 50},
+                metadata_format=MetadataFormat.VORBIS,
+                normalized_rating_max_value=100,
+            )
+            assert (
+                get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100) == 50
+            )
+
+            update_metadata(test_file, {UnifiedMetadataKey.RATING: None}, metadata_format=MetadataFormat.VORBIS)
+            assert (
+                get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100)
+                is None
+            )
+
+    def test_delete_rating_preserves_other_fields(self):
+        with temp_file_with_metadata({}, "mp3") as test_file:
+            update_metadata(
+                test_file,
+                {
+                    UnifiedMetadataKey.RATING: 70,
+                    UnifiedMetadataKey.TITLE: "Test Title",
+                    UnifiedMetadataKey.ARTISTS: ["Test Artist"],
+                },
+                normalized_rating_max_value=100,
+            )
+
+            update_metadata(test_file, {UnifiedMetadataKey.RATING: None})
+
+            assert (
+                get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100)
+                is None
+            )
+            assert get_unified_metadata_field(test_file, UnifiedMetadataKey.TITLE) == "Test Title"
+            assert get_unified_metadata_field(test_file, UnifiedMetadataKey.ARTISTS) == ["Test Artist"]
+
+    def test_delete_rating_already_none(self):
+        with temp_file_with_metadata({}, "mp3") as test_file:
+            update_metadata(test_file, {UnifiedMetadataKey.RATING: None})
+            assert (
+                get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100)
+                is None
+            )
+
+    def test_delete_rating_zero(self):
+        with temp_file_with_metadata({}, "mp3") as test_file:
+            update_metadata(test_file, {UnifiedMetadataKey.RATING: 0}, normalized_rating_max_value=100)
+            assert (
+                get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100) == 0
+            )
+            update_metadata(test_file, {UnifiedMetadataKey.RATING: None})
+            assert (
+                get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100)
+                is None
+            )

audiometa/test/tests/integration/metadata_field/rating/test_error_handling.py

@@ -0,0 +1,137 @@
+import pytest
+
+from audiometa import get_unified_metadata_field, update_metadata
+from audiometa.exceptions import FileTypeNotSupportedError, InvalidMetadataFieldTypeError, InvalidRatingValueError
+from audiometa.test.helpers.temp_file_with_metadata import temp_file_with_metadata
+from audiometa.utils.metadata_format import MetadataFormat
+from audiometa.utils.unified_metadata_key import UnifiedMetadataKey
+
+
+@pytest.mark.integration
+class TestRatingErrorHandling:
+    def test_rating_unsupported_file_type(self):
+        with temp_file_with_metadata({}, "mp3") as temp_file_path:
+            temp_file_path.write_bytes(b"fake audio content")
+            temp_txt = temp_file_path.with_suffix(".txt")
+            temp_txt.write_bytes(b"fake audio content")
+
+            with pytest.raises(FileTypeNotSupportedError):
+                get_unified_metadata_field(str(temp_txt), UnifiedMetadataKey.RATING)
+
+            with pytest.raises(FileTypeNotSupportedError):
+                update_metadata(str(temp_txt), {UnifiedMetadataKey.RATING: 85})
+
+    def test_rating_nonexistent_file(self):
+        nonexistent_file = "nonexistent_file.mp3"
+
+        with pytest.raises(FileNotFoundError):
+            get_unified_metadata_field(nonexistent_file, UnifiedMetadataKey.RATING)
+
+        with pytest.raises(FileNotFoundError):
+            update_metadata(nonexistent_file, {UnifiedMetadataKey.RATING: 85})
+
+    def test_write_fractional_values(self):
+        # Fractional values are now supported for half-star ratings (consistent with classic star rating systems)
+        basic_metadata = {"title": "Test Title", "artist": "Test Artist"}
+        with temp_file_with_metadata(basic_metadata, "mp3") as test_file:
+            # 25.5/100 maps to index 3 (1.5 stars), which is valid
+            update_metadata(
+                test_file,
+                {UnifiedMetadataKey.RATING: 25.5},
+                normalized_rating_max_value=100,
+                metadata_format=MetadataFormat.ID3V2,
+            )
+            # Verify it was written correctly
+            rating = get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100)
+            assert rating == 30  # 1.5 stars = 30 on 100-scale
+
+    def test_rating_invalid_string_value(self):
+        with (
+            temp_file_with_metadata({"title": "Test Title", "artist": "Test Artist"}, "mp3") as test_file,
+            pytest.raises(
+                InvalidMetadataFieldTypeError,
+                match="Invalid type for metadata field 'rating': expected Union\\[int, float\\], got str",
+            ),
+        ):
+            update_metadata(test_file, {UnifiedMetadataKey.RATING: "invalid"}, normalized_rating_max_value=100)
+
+    def test_rating_negative_value_rejected_in_normalized_mode(self):
+        with (
+            temp_file_with_metadata({"title": "Test Title", "artist": "Test Artist"}, "mp3") as test_file,
+            pytest.raises(InvalidRatingValueError) as exc_info,
+        ):
+            update_metadata(test_file, {UnifiedMetadataKey.RATING: -1}, normalized_rating_max_value=100)
+        assert "must be non-negative" in str(exc_info.value)
+
+    def test_rating_over_max_value_rejected_in_normalized_mode(self):
+        with temp_file_with_metadata({"title": "Test Title", "artist": "Test Artist"}, "mp3") as test_file:
+            with pytest.raises(InvalidRatingValueError) as exc_info:
+                update_metadata(test_file, {UnifiedMetadataKey.RATING: 101}, normalized_rating_max_value=100)
+            assert "out of range" in str(exc_info.value)
+            assert "must be between 0 and 100" in str(exc_info.value)
+
+    def test_rating_none_value(self):
+        with temp_file_with_metadata({"title": "Test Title", "artist": "Test Artist"}, "mp3") as test_file:
+            update_metadata(test_file, {UnifiedMetadataKey.RATING: None}, normalized_rating_max_value=100)
+            metadata = get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100)
+            assert metadata is None
+
+    def test_rating_without_max_value_allows_any_non_negative_integer(self):
+        with temp_file_with_metadata({"title": "Test Title", "artist": "Test Artist"}, "mp3") as test_file:
+            # Any non-negative integer value should be allowed when normalized_rating_max_value is None
+            update_metadata(test_file, {UnifiedMetadataKey.RATING: 128}, metadata_format=MetadataFormat.ID3V2)
+            update_metadata(test_file, {UnifiedMetadataKey.RATING: 75}, metadata_format=MetadataFormat.ID3V2)
+            update_metadata(test_file, {UnifiedMetadataKey.RATING: 0}, metadata_format=MetadataFormat.ID3V2)
+
+            # Negative values should be rejected
+            with pytest.raises(InvalidRatingValueError) as exc_info:
+                update_metadata(test_file, {UnifiedMetadataKey.RATING: -1}, metadata_format=MetadataFormat.ID3V2)
+            assert "must be non-negative" in str(exc_info.value)
+
+            # Valid value in BASE_100_PROPORTIONAL profile (Vorbis uses this)
+            with temp_file_with_metadata(
+                {"title": "Test Title", "artist": "Test Artist"}, "flac"
+            ) as test_file_flac_path:
+                update_metadata(
+                    test_file_flac_path, {UnifiedMetadataKey.RATING: 50}, metadata_format=MetadataFormat.VORBIS
+                )
+                update_metadata(
+                    test_file_flac_path, {UnifiedMetadataKey.RATING: 128}, metadata_format=MetadataFormat.VORBIS
+                )
+
+    def test_rating_with_normalized_max_validates_profile_values(self):
+        with temp_file_with_metadata({"title": "Test Title", "artist": "Test Artist"}, "mp3") as test_file:
+            # Valid: 50/100 maps to star rating index 5 (2.5 stars), which is valid
+            update_metadata(
+                test_file,
+                {UnifiedMetadataKey.RATING: 50},
+                normalized_rating_max_value=100,
+                metadata_format=MetadataFormat.ID3V2,
+            )
+
+            # Invalid: 37/100 maps to star rating index 4 (2 stars), which is valid
+            # But 110/100 would map to index 11, which is > 10 (invalid)
+            with pytest.raises(InvalidRatingValueError) as exc_info:
+                update_metadata(
+                    test_file,
+                    {UnifiedMetadataKey.RATING: 110},
+                    normalized_rating_max_value=100,
+                    metadata_format=MetadataFormat.ID3V2,
+                )
+            assert "out of range" in str(exc_info.value) or "do not exist in any supported writing profile" in str(
+                exc_info.value
+            )
+
+    def test_invalid_rating_value_error_non_numeric_string(self):
+        with temp_file_with_metadata({}, "mp3") as test_file:
+            with pytest.raises(InvalidMetadataFieldTypeError) as exc_info:
+                update_metadata(test_file, {UnifiedMetadataKey.RATING: "invalid"}, normalized_rating_max_value=100)
+            assert "invalid type for metadata field 'rating'" in str(exc_info.value).lower()
+
+    def test_invalid_rating_value_error_non_numeric_type(self):
+        with temp_file_with_metadata({}, "mp3") as test_file:
+            with pytest.raises(InvalidMetadataFieldTypeError) as exc_info:
+                update_metadata(
+                    test_file, {UnifiedMetadataKey.RATING: {"not": "valid"}}, normalized_rating_max_value=100
+                )
+            assert "invalid type for metadata field 'rating'" in str(exc_info.value).lower()

audiometa/test/tests/integration/metadata_field/rating/writing/metadata_format/test_id3v2.py

@@ -0,0 +1,77 @@
+import pytest
+
+from audiometa import get_unified_metadata_field, update_metadata
+from audiometa.test.helpers.temp_file_with_metadata import temp_file_with_metadata
+from audiometa.utils.metadata_format import MetadataFormat
+from audiometa.utils.unified_metadata_key import UnifiedMetadataKey
+
+
+@pytest.mark.integration
+class TestId3v2RatingWriting:
+    @pytest.mark.parametrize(
+        ("value", "expected"),
+        [
+            (0, 0),
+            (0.5, 13),
+            (1, 1),
+            (1.5, 54),
+            (2, 64),
+            (2.5, 118),
+            (3, 128),
+            (3.5, 186),
+            (4, 196),
+            (4.5, 242),
+            (5, 255),
+        ],
+    )
+    def test_write_base_255_non_proportional_values(self, value, expected):
+        basic_metadata = {"title": "Test Title", "artist": "Test Artist"}
+
+        with temp_file_with_metadata(basic_metadata, "mp3") as test_file:
+            test_metadata = {UnifiedMetadataKey.RATING: value}
+            update_metadata(
+                test_file, test_metadata, normalized_rating_max_value=5, metadata_format=MetadataFormat.ID3V2
+            )
+            rating = get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING)
+            assert rating == expected
+
+    def test_write_none_removes_rating(self):
+        basic_metadata = {"title": "Test Title", "artist": "Test Artist"}
+
+        with temp_file_with_metadata(basic_metadata, "mp3") as test_file:
+            # First write a rating
+            test_metadata = {UnifiedMetadataKey.RATING: 80}
+            update_metadata(
+                test_file, test_metadata, normalized_rating_max_value=100, metadata_format=MetadataFormat.ID3V2
+            )
+            rating = get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100)
+            assert rating == 80
+
+            # Then remove it with None - this may not work as expected in all cases
+            test_metadata = {UnifiedMetadataKey.RATING: None}
+            update_metadata(
+                test_file, test_metadata, normalized_rating_max_value=100, metadata_format=MetadataFormat.ID3V2
+            )
+            rating = get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100)
+            # Rating removal behavior may vary - check if it's None or 0
+            assert rating is None or rating == 0
+
+    def test_write_edge_values(self):
+        basic_metadata = {"title": "Test Title", "artist": "Test Artist"}
+
+        with temp_file_with_metadata(basic_metadata, "mp3") as test_file:
+            # Test minimum value
+            test_metadata = {UnifiedMetadataKey.RATING: 0}
+            update_metadata(
+                test_file, test_metadata, normalized_rating_max_value=100, metadata_format=MetadataFormat.ID3V2
+            )
+            rating = get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100)
+            assert rating == 0
+
+            # Test maximum value
+            test_metadata = {UnifiedMetadataKey.RATING: 100}
+            update_metadata(
+                test_file, test_metadata, normalized_rating_max_value=100, metadata_format=MetadataFormat.ID3V2
+            )
+            rating = get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100)
+            assert rating == 100

audiometa/test/tests/integration/metadata_field/rating/writing/metadata_format/test_riff.py

@@ -0,0 +1,55 @@
+import pytest
+
+from audiometa import get_unified_metadata_field, update_metadata
+from audiometa.test.helpers.temp_file_with_metadata import temp_file_with_metadata
+from audiometa.utils.metadata_format import MetadataFormat
+from audiometa.utils.unified_metadata_key import UnifiedMetadataKey
+
+
+@pytest.mark.integration
+class TestRiffRatingWriting:
+    @pytest.mark.parametrize(
+        ("star_rating", "expected_normalized_rating"),
+        [
+            (0, 0),
+            (0.5, 10),
+            (1, 20),
+            (1.5, 30),
+            (2, 40),
+            (2.5, 50),
+            (3, 60),
+            (3.5, 70),
+            (4, 80),
+            (4.5, 90),
+            (5, 100),
+        ],
+    )
+    def test_write_star_rating(self, star_rating, expected_normalized_rating):
+        basic_metadata = {"title": "Test Title", "artist": "Test Artist"}
+
+        with temp_file_with_metadata(basic_metadata, "wav") as test_file:
+            test_metadata = {UnifiedMetadataKey.RATING: star_rating}
+            update_metadata(
+                test_file, test_metadata, normalized_rating_max_value=5, metadata_format=MetadataFormat.RIFF
+            )
+            rating = get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100)
+            assert rating == expected_normalized_rating
+
+    def test_write_none_removes_rating(self):
+        basic_metadata = {"title": "Test Title", "artist": "Test Artist"}
+
+        with temp_file_with_metadata(basic_metadata, "wav") as test_file:
+            # First write a rating
+            test_metadata = {UnifiedMetadataKey.RATING: 80}
+            update_metadata(
+                test_file, test_metadata, normalized_rating_max_value=100, metadata_format=MetadataFormat.RIFF
+            )
+            rating = get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100)
+            assert rating == 80
+
+            # Then remove it with None
+            test_metadata = {UnifiedMetadataKey.RATING: None}
+            update_metadata(
+                test_file, test_metadata, normalized_rating_max_value=100, metadata_format=MetadataFormat.RIFF
+            )
+            rating = get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100)

audiometa/test/tests/integration/metadata_field/rating/writing/metadata_format/test_vorbis.py

@@ -0,0 +1,57 @@
+import pytest
+
+from audiometa import get_unified_metadata, get_unified_metadata_field, update_metadata
+from audiometa.test.helpers.temp_file_with_metadata import temp_file_with_metadata
+from audiometa.utils.metadata_format import MetadataFormat
+from audiometa.utils.unified_metadata_key import UnifiedMetadataKey
+
+
+@pytest.mark.integration
+class TestVorbisRatingWriting:
+    @pytest.mark.parametrize(
+        ("star_rating", "expected_normalized_rating"),
+        [
+            (0, 0),
+            (0.5, 10),
+            (1, 20),
+            (1.5, 30),
+            (2, 40),
+            (2.5, 50),
+            (3, 60),
+            (3.5, 70),
+            (4, 80),
+            (4.5, 90),
+            (5, 100),
+        ],
+    )
+    def test_write_star_rating(self, star_rating, expected_normalized_rating):
+        basic_metadata = {"title": "Test Title", "artist": "Test Artist"}
+
+        with temp_file_with_metadata(basic_metadata, "flac") as test_file:
+            test_metadata = {UnifiedMetadataKey.RATING: star_rating}
+            update_metadata(
+                test_file, test_metadata, normalized_rating_max_value=5, metadata_format=MetadataFormat.VORBIS
+            )
+            metadata = get_unified_metadata(test_file)
+            rating = metadata.get(UnifiedMetadataKey.RATING)
+            assert rating == expected_normalized_rating
+
+    def test_write_none_removes_rating(self):
+        basic_metadata = {"title": "Test Title", "artist": "Test Artist"}
+
+        with temp_file_with_metadata(basic_metadata, "flac") as test_file:
+            # First write a rating
+            test_metadata = {UnifiedMetadataKey.RATING: 80}
+            update_metadata(
+                test_file, test_metadata, normalized_rating_max_value=100, metadata_format=MetadataFormat.VORBIS
+            )
+            rating = get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100)
+            assert rating == 80
+
+            # Then remove it with None
+            test_metadata = {UnifiedMetadataKey.RATING: None}
+            update_metadata(
+                test_file, test_metadata, normalized_rating_max_value=100, metadata_format=MetadataFormat.VORBIS
+            )
+            rating = get_unified_metadata_field(test_file, UnifiedMetadataKey.RATING, normalized_rating_max_value=100)
+            assert rating is None