ucapi 0.5.2__tar.gz → 0.6.0__tar.gz

{ucapi-0.5.2 → ucapi-0.6.0}/CHANGELOG.md

@@ -11,6 +11,17 @@ _Changes in the next release_
 
 ---
 
+## v0.6.0 - 2026-04-10
+### Breaking Changes
+- Renamed `MediaType` to `MediaContentType` and changed enums to lowercase. See media-player entity documentation for more information ([#50](https://github.com/unfoldedcircle/integration-python-library/pull/50)).
+- Changed `str, Enum` to new Python 3.11 `StrEnum` class ([#54](https://github.com/unfoldedcircle/integration-python-library/pull/54)).
+- All entity constructors require named parameters for the optional fields ([#49](https://github.com/unfoldedcircle/integration-python-library/pull/49), [#54](https://github.com/unfoldedcircle/integration-python-library/pull/54)).
+
+### Added
+- Media browsing and searching features to media-player entity ([#50](https://github.com/unfoldedcircle/integration-python-library/pull/50)).
+- Allow integrations to provide entity icon and description ([#55](https://github.com/unfoldedcircle/integration-python-library/pull/55)).
+
+
 ## v0.5.2 - 2026-01-30
 ### Added
 - Add Select Entity support by @JackJPowell ([#44](https://github.com/unfoldedcircle/integration-python-library/pull/44)).

{ucapi-0.5.2/ucapi.egg-info → ucapi-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucapi
-Version: 0.5.2
+Version: 0.6.0
 Summary: Python wrapper for the Unfolded Circle Integration API
 Author-email: Unfolded Circle ApS <hello@unfoldedcircle.com>
 License: MPL-2.0
@@ -10,7 +10,7 @@ Project-URL: Bug Reports, https://github.com/unfoldedcircle/integration-python-l
 Project-URL: Discord, http://unfolded.chat/
 Project-URL: Forum, https://unfolded.community/
 Platform: any
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
 Classifier: Operating System :: OS Independent

{ucapi-0.5.2 → ucapi-0.6.0}/pyproject.toml

@@ -10,7 +10,7 @@ authors = [
 license = {text = "MPL-2.0"}
 description = "Python wrapper for the Unfolded Circle Integration API"
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)",
     "Operating System :: OS Independent",

ucapi-0.6.0/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()

ucapi-0.6.0/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-0.5.2 → ucapi-0.6.0}/ucapi/__init__.py

@@ -19,6 +19,8 @@ from .api_definitions import (  # isort:skip # noqa: F401
     DriverSetupRequest,
     Events,
     IntegrationSetupError,
+    Paging,
+    Pagination,
     RequestUserConfirmation,
     RequestUserInput,
     SetupAction,
@@ -42,7 +44,20 @@ from .button import Button  # noqa: F401
 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

ucapi-0.6.0/ucapi/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.6.0'
+__version_tuple__ = version_tuple = (0, 6, 0)
+
+__commit_id__ = commit_id = 'g755510031'