Added media browsing request

CHANGELOG.md

@@ -9,6 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 _Changes in the next release_
 
+### Added
+- Media browsing and searching features to media-player entity.
+
+### Breaking Changes
+- Renamed `MediaType` to `MediaContentType` and changed enums to lowercase. See media-player entity documentation for more information.
+- Changed `str, Enum` to new Python 3.11 `StrEnum` class.
+
 ---
 
 ## v0.5.2 - 2026-01-30

tests/test_media_player.py

@@ -0,0 +1,159 @@
+"""
+Tests for media player entity.
+"""
+
+import unittest
+from ucapi.media_player import SearchMediaFilter, MediaClass, BrowseMediaItem
+
+
+class TestMediaPlayer(unittest.TestCase):
+    """Media player tests."""
+
+    def test_search_media_filter_media_classes(self):
+        """Test SearchMediaFilter media_classes with standard and custom values."""
+        # Test with standard MediaClass
+        smf = SearchMediaFilter(media_classes=[MediaClass.ALBUM, MediaClass.TRACK])
+        self.assertEqual(smf.media_classes, [MediaClass.ALBUM, MediaClass.TRACK])
+
+        # Test with strings that match MediaClass
+        smf = SearchMediaFilter(media_classes=["album", "track"])
+        self.assertEqual(smf.media_classes, [MediaClass.ALBUM, MediaClass.TRACK])
+
+        # Test with custom string values
+        try:
+            smf = SearchMediaFilter(media_classes=["custom_class", "another_one"])
+            self.assertEqual(smf.media_classes, ["custom_class", "another_one"])
+        except ValueError as e:
+            self.fail(
+                f"SearchMediaFilter raised ValueError for custom media classes: {e}"
+            )
+
+    def test_search_media_filter_mixed_classes(self):
+        """Test SearchMediaFilter with a mix of MediaClass and custom strings."""
+        try:
+            smf = SearchMediaFilter(media_classes=[MediaClass.ALBUM, "custom_class"])
+            self.assertEqual(smf.media_classes, [MediaClass.ALBUM, "custom_class"])
+        except ValueError as e:
+            self.fail(
+                f"SearchMediaFilter raised ValueError for mixed media classes: {e}"
+            )
+
+    def test_search_media_filter_none(self):
+        """Test SearchMediaFilter with None media_classes."""
+        smf = SearchMediaFilter(media_classes=None)
+        self.assertIsNone(smf.media_classes)
+
+    def test_search_media_filter_from_dict(self):
+        """Test SearchMediaFilter.from_dict with custom values."""
+        data = {
+            "media_classes": ["album", "custom_class"],
+            "artist": "Some Artist",
+            "album": "Some Album",
+        }
+        try:
+            smf = SearchMediaFilter.from_dict(data)
+            self.assertEqual(smf.media_classes, [MediaClass.ALBUM, "custom_class"])
+            self.assertEqual(smf.artist, "Some Artist")
+            self.assertEqual(smf.album, "Some Album")
+        except ValueError as e:
+            self.fail(
+                f"SearchMediaFilter.from_dict raised ValueError for custom media classes: {e}"
+            )
+
+    def test_browse_media_item_validation_mandatory(self):
+        """Test BrowseMediaItem mandatory field validation."""
+        # Valid mandatory fields
+        item = BrowseMediaItem(media_id="id1", title="Title")
+        self.assertEqual(item.media_id, "id1")
+        self.assertEqual(item.title, "Title")
+
+        # media_id empty
+        with self.assertRaisesRegex(
+            ValueError, "media_id must be at least 1 characters"
+        ):
+            BrowseMediaItem(media_id="", title="Title")
+
+        # media_id too long
+        with self.assertRaisesRegex(
+            ValueError, "media_id must be at most 255 characters"
+        ):
+            BrowseMediaItem(media_id="a" * 256, title="Title")
+
+        # media_id wrong type
+        with self.assertRaisesRegex(TypeError, "media_id must be str, got int"):
+            BrowseMediaItem(media_id=123, title="Title")
+
+        # title empty
+        with self.assertRaisesRegex(ValueError, "title must be at least 1 characters"):
+            BrowseMediaItem(media_id="id1", title="")
+
+        # title too long
+        with self.assertRaisesRegex(ValueError, "title must be at most 255 characters"):
+            BrowseMediaItem(media_id="id1", title="a" * 256)
+
+    def test_browse_media_item_validation_optional(self):
+        """Test BrowseMediaItem optional field validation."""
+        # subtitle
+        with self.assertRaisesRegex(
+            ValueError, "subtitle must be at least 1 characters"
+        ):
+            BrowseMediaItem(media_id="id1", title="Title", subtitle="")
+        with self.assertRaisesRegex(
+            ValueError, "subtitle must be at most 255 characters"
+        ):
+            BrowseMediaItem(media_id="id1", title="Title", subtitle="a" * 256)
+
+        # artist
+        with self.assertRaisesRegex(ValueError, "artist must be at least 1 characters"):
+            BrowseMediaItem(media_id="id1", title="Title", artist="")
+        with self.assertRaisesRegex(
+            ValueError, "artist must be at most 255 characters"
+        ):
+            BrowseMediaItem(media_id="id1", title="Title", artist="a" * 256)
+
+        # album
+        with self.assertRaisesRegex(ValueError, "album must be at least 1 characters"):
+            BrowseMediaItem(media_id="id1", title="Title", album="")
+        with self.assertRaisesRegex(ValueError, "album must be at most 255 characters"):
+            BrowseMediaItem(media_id="id1", title="Title", album="a" * 256)
+
+        # media_class (only when it's a string)
+        # Note: media class is allowed to be empty!
+        BrowseMediaItem(media_id="id1", title="Title", media_class="")
+
+        with self.assertRaisesRegex(
+            ValueError, "media_class must be at most 255 characters"
+        ):
+            BrowseMediaItem(media_id="id1", title="Title", media_class="a" * 256)
+        # Verify it accepts MediaClass enum without error
+        BrowseMediaItem(media_id="id1", title="Title", media_class=MediaClass.ALBUM)
+
+        # media_type (only when it's a string)
+        # Note: media type is allowed to be empty!
+        BrowseMediaItem(media_id="id1", title="Title", media_type="")
+
+        with self.assertRaisesRegex(
+            ValueError, "media_type must be at most 255 characters"
+        ):
+            BrowseMediaItem(media_id="id1", title="Title", media_type="a" * 256)
+
+    def test_browse_media_item_validation_thumbnail(self):
+        """Test BrowseMediaItem thumbnail field validation."""
+        # Valid length
+        BrowseMediaItem(media_id="id1", title="Title", thumbnail="a" * 32768)
+
+        # Too short (empty)
+        with self.assertRaisesRegex(
+            ValueError, "thumbnail must be at least 1 characters"
+        ):
+            BrowseMediaItem(media_id="id1", title="Title", thumbnail="")
+
+        # Too long
+        with self.assertRaisesRegex(
+            ValueError, "thumbnail must be at most 32768 characters"
+        ):
+            BrowseMediaItem(media_id="id1", title="Title", thumbnail="a" * 32769)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_paging.py

@@ -0,0 +1,131 @@
+"""Unit tests for Paging and Pagination classes."""
+
+import json
+import unittest
+from dataclasses import asdict
+
+from ucapi.api_definitions import Pagination, Paging
+
+
+class TestPaging(unittest.TestCase):
+    """Test cases for the Paging class."""
+
+    def test_paging_default(self):
+        """Test default Paging instantiation."""
+        paging = Paging()
+        self.assertEqual(paging.page, 1)
+        self.assertEqual(paging.limit, 10)
+        self.assertEqual(paging.offset, 0)
+
+    def test_paging_custom(self):
+        """Test custom Paging instantiation."""
+        paging = Paging(page=2, limit=20)
+        self.assertEqual(paging.page, 2)
+        self.assertEqual(paging.limit, 20)
+        self.assertEqual(paging.offset, 20)
+
+    def test_paging_invalid_page(self):
+        """Test validation for invalid page number."""
+        with self.assertRaises(ValueError) as cm:
+            Paging(page=0)
+        self.assertIn("Invalid page: 0", str(cm.exception))
+
+        with self.assertRaises(ValueError):
+            Paging(page=-1)
+
+    def test_paging_invalid_limit(self):
+        """Test validation for invalid limit."""
+        with self.assertRaises(ValueError) as cm:
+            Paging(limit=0)
+        self.assertIn("Invalid limit: 0", str(cm.exception))
+
+        with self.assertRaises(ValueError):
+            Paging(limit=-1)
+        with self.assertRaises(ValueError):
+            Paging(limit=10000)
+
+    def test_paging_from_dict(self):
+        """Test constructing Paging from a dictionary."""
+        data = {"page": 3, "limit": 50}
+        paging = Paging.from_dict(data)
+        self.assertEqual(paging.page, 3)
+        self.assertEqual(paging.limit, 50)
+
+    def test_paging_from_dict_defaults(self):
+        """Test constructing Paging from an empty dictionary using defaults."""
+        paging = Paging.from_dict({})
+        self.assertEqual(paging.page, 1)
+        self.assertEqual(paging.limit, 10)
+
+    def test_paging_serialization(self):
+        """Test Paging JSON serialization."""
+        paging = Paging(page=2, limit=25)
+        serialized = asdict(paging)
+        self.assertEqual(serialized, {"page": 2, "limit": 25})
+
+        # Verify JSON round-trip
+        json_str = json.dumps(serialized)
+        self.assertEqual(json.loads(json_str), {"page": 2, "limit": 25})
+
+
+class TestPagination(unittest.TestCase):
+    """Test cases for the Pagination class."""
+
+    def test_pagination_instantiation(self):
+        """Test Pagination instantiation with all fields."""
+        pagination = Pagination(page=1, limit=10, count=100)
+        self.assertEqual(pagination.page, 1)
+        self.assertEqual(pagination.limit, 10)
+        self.assertEqual(pagination.count, 100)
+
+    def test_pagination_no_count(self):
+        """Test Pagination instantiation without count."""
+        pagination = Pagination(page=2, limit=20)
+        self.assertEqual(pagination.page, 2)
+        self.assertEqual(pagination.limit, 20)
+        self.assertIsNone(pagination.count)
+
+    def test_pagination_invalid_page(self):
+        """Test validation for invalid page number."""
+        with self.assertRaises(ValueError) as cm:
+            Pagination(page=0, limit=10)
+        self.assertIn("page must be >= 1", str(cm.exception))
+
+    def test_pagination_invalid_limit(self):
+        """Test validation for invalid limit."""
+        with self.assertRaises(ValueError) as cm:
+            Pagination(page=1, limit=-1)
+        self.assertIn("Invalid limit", str(cm.exception))
+
+    def test_pagination_limit_out_of_range(self):
+        """Test validation for invalid limit."""
+        with self.assertRaises(ValueError) as cm:
+            Pagination(page=1, limit=10000)
+        self.assertIn("Invalid limit", str(cm.exception))
+
+    def test_pagination_invalid_count(self):
+        """Test validation for invalid count."""
+        with self.assertRaises(ValueError) as cm:
+            Pagination(page=1, limit=10, count=-1)
+        self.assertIn("count cannot be negative", str(cm.exception))
+
+    def test_pagination_serialization(self):
+        """Test Pagination JSON serialization."""
+        pagination = Pagination(page=1, limit=10, count=100)
+        serialized = asdict(pagination)
+        self.assertEqual(serialized, {"page": 1, "limit": 10, "count": 100})
+
+    def test_pagination_serialization_no_count(self):
+        """Test Pagination JSON serialization when count is None."""
+        pagination = Pagination(page=2, limit=20)
+        json_data = asdict(pagination)
+
+        # Note: In JS/TS, undefined keys are omitted during JSON.stringify.
+        # In Python, None becomes `null` in JSON.
+        # This is not an issue: the Remote core service treats `null` as "not existing".
+        self.assertIn("count", json_data)
+        self.assertIsNone(json_data["count"])
+
+
+if __name__ == "__main__":
+    unittest.main()

ucapi/__init__.py

@@ -19,6 +19,8 @@
     DriverSetupRequest,
     Events,
     IntegrationSetupError,
+    Paging,
+    Pagination,
     RequestUserConfirmation,
     RequestUserInput,
     SetupAction,
@@ -42,7 +44,20 @@
 from .climate import Climate  # noqa: F401
 from .cover import Cover  # noqa: F401
 from .light import Light  # noqa: F401
-from .media_player import MediaPlayer  # noqa: F401
+from .media_player import (  # noqa: F401
+    BrowseMediaItem,
+    BrowseOptions,
+    BrowseResults,
+    MediaClass,
+    MediaContentType,
+    MediaPlayAction,
+    MediaPlayer,
+    RepeatMode,
+    SearchMediaFilter,
+    SearchMediaItem,
+    SearchOptions,
+    SearchResults,
+)
 from .remote import Remote  # noqa: F401
 from .select import Select  # noqa: F401
 from .sensor import Sensor  # noqa: F401