pympris2 0.2.0__tar.gz

pympris2-0.2.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: pympris2
+Version: 0.2.0
+Summary: An implementation of an MPRIS D-Bus client
+Author: Stefan Tatschner
+Author-email: Stefan Tatschner <stefan.tatschner@mailbox.org>
+License-Expression: EUPL-1.2
+Requires-Dist: sdbus>=0.14.2
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+<!--
+SPDX-FileCopyrightText: 2026 Stefan Tatschner
+
+SPDX-License-Identifier: CC0-1.0
+-->
+
+# pympris2
+
+An implementation of the [MPRIS D-Bus Interface Specification](https://specifications.freedesktop.org/mpris/latest/index.html) using sdbus.
+
+## Example
+
+``` python
+import asyncio
+
+from pympris2 import get_active_players, MPRISInterface
+
+
+async def main() -> None:
+    player = await get_active_players()[0]
+    proxy = MPRISInterface.connect(player)
+    await proxy.play_pause()
+    print(await proxy.volume)
+    await proxy.volume.set_async(0.5)
+    # …
+ 
+
+asyncio.run(main())
+```
+
+All methods and properties of the implemented interfaces are available in the `proxy` object.
+There is also a CLI tool `mprisctl` available; just check `--help`.
+
+## Implementation Status
+
+* [org.mpris.MediaPlayer2](https://specifications.freedesktop.org/mpris/latest/Media_Player.html) implemented
+* [org.mpris.MediaPlayer2.Player](https://specifications.freedesktop.org/mpris/latest/Player_Interface.html) implemented
+* [org.mpris.MediaPlayer2.TrackList](https://specifications.freedesktop.org/mpris/latest/Track_List_Interface.html) not implemented
+* [org.mpris.MediaPlayer2.Playlists](https://specifications.freedesktop.org/mpris/latest/Playlists_Interface.html) not implemented

pympris2-0.2.0/README.md

@@ -0,0 +1,39 @@
+<!--
+SPDX-FileCopyrightText: 2026 Stefan Tatschner
+
+SPDX-License-Identifier: CC0-1.0
+-->
+
+# pympris2
+
+An implementation of the [MPRIS D-Bus Interface Specification](https://specifications.freedesktop.org/mpris/latest/index.html) using sdbus.
+
+## Example
+
+``` python
+import asyncio
+
+from pympris2 import get_active_players, MPRISInterface
+
+
+async def main() -> None:
+    player = await get_active_players()[0]
+    proxy = MPRISInterface.connect(player)
+    await proxy.play_pause()
+    print(await proxy.volume)
+    await proxy.volume.set_async(0.5)
+    # …
+ 
+
+asyncio.run(main())
+```
+
+All methods and properties of the implemented interfaces are available in the `proxy` object.
+There is also a CLI tool `mprisctl` available; just check `--help`.
+
+## Implementation Status
+
+* [org.mpris.MediaPlayer2](https://specifications.freedesktop.org/mpris/latest/Media_Player.html) implemented
+* [org.mpris.MediaPlayer2.Player](https://specifications.freedesktop.org/mpris/latest/Player_Interface.html) implemented
+* [org.mpris.MediaPlayer2.TrackList](https://specifications.freedesktop.org/mpris/latest/Track_List_Interface.html) not implemented
+* [org.mpris.MediaPlayer2.Playlists](https://specifications.freedesktop.org/mpris/latest/Playlists_Interface.html) not implemented

pympris2-0.2.0/pyproject.toml

@@ -0,0 +1,64 @@
+# SPDX-FileCopyrightText: 2026 Stefan Tatschner
+#
+# SPDX-License-Identifier: CC0-1.0
+
+[build-system]
+requires = ["uv_build>=0.11.15,<0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "pympris2"
+version = "0.2.0"
+description = "An implementation of an MPRIS D-Bus client"
+license = "EUPL-1.2"
+readme = "README.md"
+authors = [
+    { name = "Stefan Tatschner", email = "stefan.tatschner@mailbox.org" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "sdbus>=0.14.2",
+]
+
+[project.scripts]
+"mprisctl" = "pympris2.cli:main"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.1.0",
+    "reuse>=6.2.0",
+    "ruff>=0.15.16",
+    "ty>=0.0.46",
+]
+
+[tool.mypy]
+strict = true
+native_parser = true
+num_workers = 4
+
+
+[tool.ruff.lint]
+select = [
+    "B",    # flake8-bugbear
+    "A",    # flake8-builtins
+    "ASYNC",# flake8-async
+    "C4",   # flake8-comprehensions
+    "E",    # pycodestlye
+    "F",    # pyflakes
+    "FA",   # flake8-future-annotations
+    "FLY",  # flynt
+    "FURB", # refurb
+    "I",    # isort
+    "IC",   # flake8-import-conventions
+    "LOG",  # flake8-logging
+    "PGH",  # pygrep-hooks
+    "PIE",  # flake8-pie
+    "PL",   # pylint
+    "PTH",  # flake8-use-pathlib
+    "Q",    # flake8-quotes
+    "RSE",  # flake8-raise
+    "RUF100",  # unused-noqa
+    "TD",   # flake8-todos
+    "TID",  # flake8-tidy-imports
+    "UP",   # pyupgrade
+]

pympris2-0.2.0/src/pympris2/__init__.py

@@ -0,0 +1,213 @@
+# SPDX-FileCopyrightText: 2026 Stefan Tatschner
+#
+# SPDX-License-Identifier: EUPL-1.2
+
+from typing import Self
+
+from sdbus import (
+    DbusInterfaceCommonAsync,
+    dbus_method_async,
+    dbus_property_async,
+    sd_bus_open_user,
+)
+from sdbus_async.dbus_daemon import FreedesktopDbus
+
+
+async def get_active_players() -> list[str]:
+    bus = sd_bus_open_user()
+    proxy = FreedesktopDbus(bus)
+
+    all_services = await proxy.list_names()
+
+    return [name for name in all_services if name.startswith("org.mpris.MediaPlayer2.")]
+
+
+class MediaPlayer2Interface(
+    DbusInterfaceCommonAsync,
+    interface_name="org.mpris.MediaPlayer2",
+):
+    # Raise  ()  →  nothing
+    @dbus_method_async(method_name="Raise")
+    async def raise_(self) -> None:
+        raise NotImplementedError
+
+    # Quit  ()  →  nothing
+    @dbus_method_async()
+    async def quit(self) -> None:
+        raise NotImplementedError
+
+    # CanQuit  b  Read only
+    @dbus_property_async("b")
+    def can_quit(self) -> bool:
+        raise NotImplementedError
+
+    # Fullscreen  b  Read/Write
+    @dbus_property_async("b")
+    def fullscreen(self) -> bool:
+        raise NotImplementedError
+
+    # CanSetFullscreen  b  Read only
+    @dbus_property_async("b")
+    def can_set_fullscreen(self) -> bool:
+        raise NotImplementedError
+
+    # CanRaise  b  Read only
+    @dbus_property_async("b")
+    def can_raise(self) -> bool:
+        raise NotImplementedError
+
+    # HasTrackList  b  Read only
+    @dbus_property_async("b")
+    def has_track_list(self) -> bool:
+        raise NotImplementedError
+
+    # Identity  s  Read only
+    @dbus_property_async("s")
+    def identity(self) -> str:
+        raise NotImplementedError
+
+    # DesktopEntry  s  Read only
+    @dbus_property_async("s")
+    def desktop_entry(self) -> str:
+        raise NotImplementedError
+
+    # SupportedUriSchemes  as  Read only
+    @dbus_property_async("as")
+    def supported_uri_schemes(self) -> list[str]:
+        raise NotImplementedError
+
+    # SupportedMimeTypes  as  Read only
+    @dbus_property_async("as")
+    def supported_mime_types(self) -> list[str]:
+        raise NotImplementedError
+
+
+class MediaPlayer2PlayerInterface(
+    DbusInterfaceCommonAsync,
+    interface_name="org.mpris.MediaPlayer2.Player",
+):
+    # Next  ()  →  nothing
+    @dbus_method_async()
+    async def next(self) -> None:
+        raise NotImplementedError
+
+    # Previous  ()  →  nothing
+    @dbus_method_async()
+    async def previous(self) -> None:
+        raise NotImplementedError
+
+    # Pause  ()  →  nothing
+    @dbus_method_async()
+    async def pause(self) -> None:
+        raise NotImplementedError
+
+    # PlayPause  ()  →  nothing
+    @dbus_method_async()
+    async def play_pause(self) -> None:
+        raise NotImplementedError
+
+    # Stop  ()  →  nothing
+    @dbus_method_async()
+    async def stop(self) -> None:
+        raise NotImplementedError
+
+    # Play  ()  →  nothing
+    @dbus_method_async()
+    async def play(self) -> None:
+        raise NotImplementedError
+
+    # Seek  (x: Offset)  →  nothing
+    @dbus_method_async("x")
+    async def seek(self) -> None:
+        raise NotImplementedError
+
+    # SetPosition  (o: TrackId, x: Position)  →  nothing
+    @dbus_method_async("ox")
+    async def set_position(self) -> None:
+        raise NotImplementedError
+
+    # OpenUri  (s: Uri)  →  nothing
+    @dbus_method_async("s")
+    async def open_uri(self, uri: str) -> None:
+        raise NotImplementedError
+
+    # PlaybackStatus  s ( Playback_Status)  Read only
+    @dbus_property_async("s")
+    def playback_status(self) -> str:
+        raise NotImplementedError
+
+    # LoopStatus  s ( Loop_Status)  Read/Write
+    @dbus_property_async("s")
+    def loop_status(self) -> str:
+        raise NotImplementedError
+
+    # Rate  d ( Playback_Rate)  Read/Write
+    @dbus_property_async("d")
+    def rate(self) -> int:
+        raise NotImplementedError
+
+    # Shuffle  b  Read/Write
+    @dbus_property_async("b")
+    def shuffle(self) -> bool:
+        raise NotImplementedError
+
+    # Metadata  a{sv} ( Metadata_Map)  Read only
+    @dbus_property_async("a{sv}")
+    def metadata(self) -> dict[str, tuple[str, str | int]]:
+        raise NotImplementedError
+
+    # Volume  d ( Volume)  Read/Write
+    @dbus_property_async("d")
+    def volume(self) -> int:
+        raise NotImplementedError
+
+    # Position  x ( Time_In_Us)  Read only
+    @dbus_property_async("x")
+    def position(self) -> int:
+        raise NotImplementedError
+
+    # MinimumRate  d ( Playback_Rate)  Read only
+    @dbus_property_async("d")
+    def minumum_rate(self) -> int:
+        raise NotImplementedError
+
+    # MaximumRate  d ( Playback_Rate)  Read only
+    @dbus_property_async("b")
+    def maximum_rate(self) -> int:
+        raise NotImplementedError
+
+    # CanGoNext  b  Read only
+    @dbus_property_async("b")
+    def can_go_next(self) -> bool:
+        raise NotImplementedError
+
+    # CanGoPrevious  b  Read only
+    @dbus_property_async("b")
+    def can_go_previous(self) -> bool:
+        raise NotImplementedError
+
+    # CanPlay  b  Read only
+    @dbus_property_async("b")
+    def can_play(self) -> bool:
+        raise NotImplementedError
+
+    # CanPause b Read only
+    @dbus_property_async("b")
+    def can_pause(self) -> bool:
+        raise NotImplementedError
+
+    # CanSeek b  Read only
+    @dbus_property_async("b")
+    def can_seek(self) -> bool:
+        raise NotImplementedError
+
+    # CanControl  b  Read only
+    @dbus_property_async("b")
+    def can_control(self) -> bool:
+        raise NotImplementedError
+
+
+class MPRISInterface(MediaPlayer2Interface, MediaPlayer2PlayerInterface):
+    @classmethod
+    def connect(cls, player: str) -> Self:
+        return cls.new_proxy(player, "/org/mpris/MediaPlayer2")

pympris2-0.2.0/src/pympris2/cli.py

@@ -0,0 +1,152 @@
+# SPDX-FileCopyrightText: 2026 Stefan Tatschner
+#
+# SPDX-License-Identifier: EUPL-1.2
+
+import argparse
+import asyncio
+import json
+import sys
+
+from pympris2 import MPRISInterface, get_active_players
+
+
+def parse_args() -> tuple[argparse.Namespace, argparse.ArgumentParser]:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "-p",
+        "--player",
+        metavar="NAME",
+        help="connect to this mpris2 player, default: first available player",
+    )
+
+    subparsers = parser.add_subparsers(title="available commands", required=True)
+
+    sp = subparsers.add_parser("list", help="list the names of available players")
+    sp.set_defaults(cmd="list")
+
+    sp = subparsers.add_parser("play", help="starts or resumes playback")
+    sp.set_defaults(cmd="play")
+
+    sp = subparsers.add_parser("pause", help="pause playback")
+    sp.set_defaults(cmd="pause")
+
+    sp = subparsers.add_parser("play_pause", help="pause or pause playback")
+    sp.set_defaults(cmd="play_pause")
+
+    sp = subparsers.add_parser("stop", help="stop playback")
+    sp.set_defaults(cmd="stop")
+
+    sp = subparsers.add_parser("next", help="skip to the next track in the tracklist")
+    sp.set_defaults(cmd="next")
+
+    sp = subparsers.add_parser(
+        "previous", help="skip to the next track in the tracklist"
+    )
+    sp.set_defaults(cmd="previous")
+
+    sp = subparsers.add_parser("status", help="current playback status")
+    sp.set_defaults(cmd="status")
+
+    sp = subparsers.add_parser(
+        "metadata", help="print metadata information for the current track"
+    )
+    sp.add_argument("--json", action="store_true", help="output as json")
+    sp.set_defaults(cmd="metadata")
+
+    sp = subparsers.add_parser("volume", help="print or set the volume to LEVEL")
+    sp.add_argument(
+        "VOLUME",
+        metavar="LEVEL",
+        type=float,
+        nargs="?",
+        help="value to set volume to from 0.0 to 1.0",
+    )
+    sp.set_defaults(cmd="volume")
+
+    sp = subparsers.add_parser("open", help="open the given URI")
+    sp.add_argument(
+        "URI",
+        help="either file path or remote URL",
+    )
+    sp.set_defaults(cmd="open")
+
+    sp = subparsers.add_parser("loop", help="print or set the loop status")
+    sp.add_argument(
+        "STATUS",
+        metavar="STATUS",
+        nargs="?",
+        choices=["None", "Track", "Playlist"],
+        help="'None', 'Track', or 'Playlist'",
+    )
+    sp.set_defaults(cmd="loop")
+
+    return parser.parse_args(), parser
+
+
+async def get_player_target(chosen: str | None) -> str:
+    avail_players = await get_active_players()
+
+    if isinstance(chosen, str) and chosen in avail_players:
+        return chosen
+
+    return avail_players[0] if avail_players else ""
+
+
+def _remove_dbus_types(d: dict[str, tuple[str, str | int]]) -> dict[str, str | int]:
+    out = {}
+    for k, v in d.items():
+        out[k] = v[1]
+    return out
+
+
+async def _main() -> None:  # noqa: PLR0912
+    args, parser = parse_args()
+
+    if args.cmd == "list":
+        for player in await get_active_players():
+            print(player)
+        sys.exit(0)
+
+    player = await get_player_target(args.player)
+    if not player:
+        parser.error("player not available")
+
+    proxy = MPRISInterface.connect(player)
+    match args.cmd:
+        case "play":
+            await proxy.play()
+        case "play_pause":
+            await proxy.play_pause()
+        case "pause":
+            await proxy.pause()
+        case "stop":
+            await proxy.stop()
+        case "next":
+            await proxy.next()
+        case "previous":
+            await proxy.previous()
+        case "status":
+            print(await proxy.playback_status)
+        case "volume":
+            if args.VOLUME:
+                await proxy.volume.set_async(args.VOLUME)
+            else:
+                print(await proxy.volume)
+        case "loop":
+            if args.STATUS:
+                await proxy.loop_status.set_async(args.STATUS)
+            else:
+                print(await proxy.loop_status)
+        case "open":
+            await proxy.open_uri(args.URI)
+        case "metadata":
+            m = _remove_dbus_types(await proxy.metadata)
+            if args.json:
+                print(json.dumps(m))
+            else:
+                for k, v in m.items():
+                    print(f"{k}: {v}")
+
+
+def main() -> None:
+    asyncio.run(_main())

pympris2-0.2.0/src/pympris2/py.typed

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Stefan Tatschner
+#
+# SPDX-License-Identifier: EUPL-1.2