harmony-plugin-api 0.1.0__py3-none-any.whl

harmony_plugin_api/__init__.py

@@ -0,0 +1,48 @@
+from .context import (
+    PluginContext,
+    PluginDialogBridge,
+    PluginMediaBridge,
+    PluginServiceBridge,
+    PluginSettingsBridge,
+    PluginStorageBridge,
+    PluginThemeBridge,
+    PluginUiBridge,
+)
+from .cover import (
+    PluginArtistCoverResult,
+    PluginArtistCoverSource,
+    PluginCoverResult,
+    PluginCoverSource,
+)
+from .lyrics import PluginLyricsResult, PluginLyricsSource
+from .manifest import Capability, PluginManifest, PluginManifestError
+from .media import PluginPlaybackRequest, PluginTrack
+from .online import PluginOnlineProvider
+from .plugin import HarmonyPlugin
+from .registry_types import SettingsTabSpec, SidebarEntrySpec
+
+__all__ = [
+    "Capability",
+    "HarmonyPlugin",
+    "PluginArtistCoverResult",
+    "PluginArtistCoverSource",
+    "PluginContext",
+    "PluginCoverResult",
+    "PluginCoverSource",
+    "PluginDialogBridge",
+    "PluginLyricsResult",
+    "PluginLyricsSource",
+    "PluginManifest",
+    "PluginManifestError",
+    "PluginMediaBridge",
+    "PluginOnlineProvider",
+    "PluginPlaybackRequest",
+    "PluginServiceBridge",
+    "PluginSettingsBridge",
+    "PluginStorageBridge",
+    "PluginThemeBridge",
+    "PluginTrack",
+    "PluginUiBridge",
+    "SettingsTabSpec",
+    "SidebarEntrySpec",
+]

harmony_plugin_api/context.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol
+
+from .cover import PluginArtistCoverSource, PluginCoverSource
+from .lyrics import PluginLyricsSource
+from .manifest import PluginManifest
+from .online import PluginOnlineProvider
+from .registry_types import SettingsTabSpec, SidebarEntrySpec
+
+
+class PluginSettingsBridge(Protocol):
+    def get(self, key: str, default: Any = None) -> Any:
+        ...
+
+    def set(self, key: str, value: Any) -> None:
+        ...
+
+
+class PluginStorageBridge(Protocol):
+    @property
+    def data_dir(self) -> Path:
+        ...
+
+    @property
+    def cache_dir(self) -> Path:
+        ...
+
+    @property
+    def temp_dir(self) -> Path:
+        ...
+
+
+class PluginThemeBridge(Protocol):
+    def register_widget(self, widget) -> None:
+        ...
+
+    def get_qss(self, template: str) -> str:
+        ...
+
+    def current_theme(self):
+        ...
+
+
+class PluginDialogBridge(Protocol):
+    def information(self, parent, title: str, message: str):
+        ...
+
+    def warning(self, parent, title: str, message: str):
+        ...
+
+    def question(self, parent, title: str, message: str, buttons, default_button):
+        ...
+
+    def critical(self, parent, title: str, message: str):
+        ...
+
+    def setup_title_bar(self, dialog, container_layout, title: str, **kwargs):
+        ...
+
+
+class PluginUiBridge(Protocol):
+    def register_sidebar_entry(self, spec: SidebarEntrySpec) -> None:
+        ...
+
+    def register_settings_tab(self, spec: SettingsTabSpec) -> None:
+        ...
+
+    @property
+    def theme(self) -> PluginThemeBridge:
+        ...
+
+    @property
+    def dialogs(self) -> PluginDialogBridge:
+        ...
+
+
+class PluginMediaBridge(Protocol):
+    def cache_remote_track(self, request: Any, progress_callback=None, force: bool = False):
+        ...
+
+    def add_online_track(self, request: Any):
+        ...
+
+    def play_online_track(self, request: Any) -> int | None:
+        ...
+
+    def add_online_track_to_queue(self, request: Any) -> int | None:
+        ...
+
+    def insert_online_track_to_queue(self, request: Any) -> int | None:
+        ...
+
+
+class PluginServiceBridge(Protocol):
+    def register_lyrics_source(self, source: PluginLyricsSource) -> None:
+        ...
+
+    def register_cover_source(self, source: PluginCoverSource) -> None:
+        ...
+
+    def register_artist_cover_source(self, source: PluginArtistCoverSource) -> None:
+        ...
+
+    def register_online_music_provider(self, provider: PluginOnlineProvider) -> None:
+        ...
+
+    @property
+    def media(self) -> PluginMediaBridge:
+        ...
+
+
+@dataclass(frozen=True)
+class PluginContext:
+    plugin_id: str
+    manifest: PluginManifest
+    logger: Any
+    http: Any
+    events: Any
+    language: str
+    storage: PluginStorageBridge
+    settings: PluginSettingsBridge
+    ui: PluginUiBridge
+    services: PluginServiceBridge

harmony_plugin_api/cover.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class PluginCoverResult:
+    item_id: str
+    title: str
+    artist: str
+    album: str = ""
+    duration: float | None = None
+    source: str = ""
+    cover_url: str | None = None
+    extra_id: str | None = None
+
+
+@dataclass(frozen=True)
+class PluginArtistCoverResult:
+    artist_id: str
+    name: str
+    source: str = ""
+    cover_url: str | None = None
+    album_count: int | None = None
+
+
+class PluginCoverSource(Protocol):
+    source_id: str
+    display_name: str
+
+    def search(
+        self,
+        title: str,
+        artist: str,
+        album: str = "",
+        duration: float | None = None,
+    ) -> list[PluginCoverResult]:
+        ...
+
+
+class PluginArtistCoverSource(Protocol):
+    source_id: str
+    display_name: str
+
+    def search(
+        self,
+        artist_name: str,
+        limit: int = 10,
+    ) -> list[PluginArtistCoverResult]:
+        ...

harmony_plugin_api/lyrics.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class PluginLyricsResult:
+    song_id: str
+    title: str
+    artist: str
+    album: str = ""
+    duration: float | None = None
+    source: str = ""
+    cover_url: str | None = None
+    lyrics: str | None = None
+    accesskey: str | None = None
+    supports_yrc: bool = False
+
+
+class PluginLyricsSource(Protocol):
+    source_id: str
+    display_name: str
+
+    def search(
+        self,
+        title: str,
+        artist: str,
+        limit: int = 10,
+    ) -> list[PluginLyricsResult]:
+        ...
+
+    def get_lyrics(self, result: PluginLyricsResult) -> str | None:
+        ...

harmony_plugin_api/manifest.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+
+Capability = Literal[
+    "sidebar",
+    "settings_tab",
+    "lyrics_source",
+    "cover",
+    "online_music_provider",
+]
+
+_ALLOWED_CAPABILITIES = {
+    "sidebar",
+    "settings_tab",
+    "lyrics_source",
+    "cover",
+    "online_music_provider",
+}
+
+
+class PluginManifestError(ValueError):
+    pass
+
+
+def _require_str(data: dict[str, Any], key: str) -> str:
+    value = data.get(key)
+    if not isinstance(value, str):
+        raise PluginManifestError(f"Manifest field '{key}' must be a string")
+    if not value.strip():
+        raise PluginManifestError(
+            f"Manifest field '{key}' must be a non-empty string"
+        )
+    return value
+
+
+@dataclass(frozen=True)
+class PluginManifest:
+    id: str
+    name: str
+    version: str
+    api_version: str
+    entrypoint: str
+    entry_class: str
+    capabilities: tuple[str, ...]
+    min_app_version: str
+    max_app_version: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "PluginManifest":
+        required = (
+            "id",
+            "name",
+            "version",
+            "api_version",
+            "entrypoint",
+            "entry_class",
+            "capabilities",
+            "min_app_version",
+        )
+        missing = [key for key in required if key not in data]
+        if missing:
+            raise PluginManifestError(f"Missing manifest keys: {', '.join(missing)}")
+
+        capabilities_raw = data["capabilities"]
+        if isinstance(capabilities_raw, str) or not isinstance(
+            capabilities_raw, (list, tuple)
+        ):
+            raise PluginManifestError(
+                "Manifest field 'capabilities' must be a list/tuple of strings"
+            )
+        if not all(isinstance(item, str) for item in capabilities_raw):
+            raise PluginManifestError(
+                "Manifest field 'capabilities' must be a list/tuple of strings"
+            )
+        capabilities = tuple(capabilities_raw)
+        unknown = sorted(set(capabilities) - _ALLOWED_CAPABILITIES)
+        if unknown:
+            raise PluginManifestError(f"Unknown capabilities: {', '.join(unknown)}")
+
+        max_app_version = data.get("max_app_version")
+        if max_app_version is not None and not isinstance(max_app_version, str):
+            raise PluginManifestError(
+                "Manifest field 'max_app_version' must be a string if provided"
+            )
+
+        return cls(
+            id=_require_str(data, "id"),
+            name=_require_str(data, "name"),
+            version=_require_str(data, "version"),
+            api_version=_require_str(data, "api_version"),
+            entrypoint=_require_str(data, "entrypoint"),
+            entry_class=_require_str(data, "entry_class"),
+            capabilities=capabilities,
+            min_app_version=_require_str(data, "min_app_version"),
+            max_app_version=max_app_version,
+        )

harmony_plugin_api/media.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class PluginTrack:
+    track_id: str
+    title: str
+    artist: str
+    album: str = ""
+    duration: int | None = None
+    artwork_url: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class PluginPlaybackRequest:
+    provider_id: str
+    track_id: str
+    title: str
+    quality: str
+    metadata: dict[str, Any]

harmony_plugin_api/online.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from .media import PluginPlaybackRequest, PluginTrack
+
+__all__ = ["PluginOnlineProvider", "PluginPlaybackRequest", "PluginTrack"]
+
+
+class PluginOnlineProvider(Protocol):
+    provider_id: str
+    display_name: str
+
+    def create_page(self, context: Any, parent: Any = None) -> Any:
+        ...
+
+    def get_playback_url_info(
+        self,
+        track_id: str,
+        quality: str,
+    ) -> dict[str, Any] | None:
+        ...

harmony_plugin_api/plugin.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from .context import PluginContext
+
+
+class HarmonyPlugin(Protocol):
+    plugin_id: str
+
+    def register(self, context: PluginContext) -> None:
+        ...
+
+    def unregister(self, context: PluginContext) -> None:
+        ...

harmony_plugin_api/registry_types.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass(frozen=True)
+class SidebarEntrySpec:
+    plugin_id: str
+    entry_id: str
+    title: str
+    order: int
+    icon_name: str | None
+    page_factory: Callable[[Any, Any], Any]
+    icon_path: str | None = None
+    title_provider: Callable[[], str] | None = None
+
+
+@dataclass(frozen=True)
+class SettingsTabSpec:
+    plugin_id: str
+    tab_id: str
+    title: str
+    order: int
+    widget_factory: Callable[[Any, Any], Any]
+    title_provider: Callable[[], str] | None = None

harmony_plugin_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: harmony-plugin-api
+Version: 0.1.0
+Summary: Pure plugin SDK for Harmony plugins
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# harmony-plugin-api
+
+Pure plugin SDK for Harmony plugins.
+
+This package only contains stable plugin-facing protocols, models, manifest parsing,
+and registry spec types. It does not include Harmony host runtime implementations.
+
+Host-specific theme, dialog, runtime, and bootstrap integrations must be provided by
+the Harmony application and injected through `PluginContext`.

harmony_plugin_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+harmony_plugin_api/__init__.py,sha256=iDJRmODGObV7TjkObODdxn0sRFUQtgj-TQmMwCNomfE,1248
+harmony_plugin_api/context.py,sha256=xwrvJdO2cVkvMI4TGM28a178WRZ6Yia0iHD9tqVoJlU,2933
+harmony_plugin_api/cover.py,sha256=bZriYoqrtGvZ-qzYNtEROZ-oM9SpEL7zDb9LyIaBgHU,994
+harmony_plugin_api/lyrics.py,sha256=J80kfjH30kCQu6VKWU8Xyjb9hubkE-yAaE1nu3lfCrU,704
+harmony_plugin_api/manifest.py,sha256=HkLMLpwWLqPz-wt7gXums0-KiXUhBoINTvFJKaYJfwA,2978
+harmony_plugin_api/media.py,sha256=q6EitBdC6Kok-RFNiL3HGTT5014u0TKu6MbQqULGJcQ,495
+harmony_plugin_api/online.py,sha256=YdNpYqDgJ1-ioM8alT8OUjXj0X3RAEBtnOztJi0YjUk,499
+harmony_plugin_api/plugin.py,sha256=gb_xJxsbiVe92w9l1Ha_Vxxq4cho4iIqSfvmdDGZM-M,292
+harmony_plugin_api/registry_types.py,sha256=865dUJL0N4JLT2WtOx24Tq-0XeDhzLNguzOWtXJNRX0,587
+harmony_plugin_api-0.1.0.dist-info/METADATA,sha256=N3t9OewjiACRTuZ4qPH2Yux-_lWIpNbZosZFvIv3JzU,548
+harmony_plugin_api-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+harmony_plugin_api-0.1.0.dist-info/top_level.txt,sha256=rcwqJQgD3vPenHOfVtcdrv0Lpfkm3jpJuYl4nP7gtgk,19
+harmony_plugin_api-0.1.0.dist-info/RECORD,,

harmony_plugin_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

harmony_plugin_api-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+harmony_plugin_api