Porting Pithos to macOS: Four Merged PRs, One Rewritten Design, and a Red CI Nobody Had Fixed
Vicente Louvet
- 8 minutes read - 1673 wordsI like Pandora. I use a Mac. And the best Pandora client on Linux, the GTK 3, Python Pithos, has never supported macOS. Last release was 1.6.2 back in March 2024. The maintainer, TingPing (Patrick), is a one-person operation, and the project had no merges at all for over two years. My goal, set in mid-September: get Pithos running on my Mac, then send whatever it took upstream as pull requests he could actually review.
Two days later the project had its first merges since 2024, and they were mine. That sounds like a victory lap. This post is the more honest version: four merged PRs, one of them redesigned on request, a CI that had been red for months before anyone fixed it, and the single biggest discovery of the whole trip, that a one-maintainer project rewards you in proportion to how much upstream time you decide not to spend.
Why Pithos #
Pithos is a GTK 3, Python desktop client for Pandora Radio. It is Linux-first.
macOS support is not just missing; it was never on the roadmap. The dependencies that
make it run on a Mac are all in Homebrew, and only the monolithic gstreamer formula
still exists there. The separate gst-plugins-* formulae are gone. So the working set
that got it from source to sound:
brew install gtk+3 pygobject3 gobject-introspection gstreamer meson ninja adwaita-icon-theme
Build with Meson, run from the source tree through a small wrapper script. A real Pandora login worked on the Mac on day one, and that was the point. Everything after that was about making it proper instead of just making it work.
Read the maintainer first #
Before writing a line of code I read the maintainer. From his comments on an earlier, withdrawn GTK 4 modernisation PR I pulled out four ground rules: one purpose per PR; new features in their own PRs; generated code needs proper authors; and he has very little review time. Rule four is the one that governs everything else.
I also checked all 260 past PRs and 464 issues for duplicates before opening anything. That turned up a lesson I will use forever: grep the diffs of open PRs, not the titles. The withdrawn PR’s title hid an icon-handling rewrite that several duplicate checks on titles never surfaced.
Every commit carries me as author and an AI co-author trailer, because some of the code was written with an assistant, and he had said he wanted that visible. If you use tooling on public work, name it.
The CI that had been red for months #
Upstream CI had been red on every pull request and on master since at least January
2026. The Flatpak build and all 10 Meson tests passed. The failure was the final artifact
upload, because bilelmoussaoui/flatpak-github-actions@v2 was calling GitHub’s retired
artifact API. The fix was to move to
flatpak/flatpak-github-actions/flatpak-builder@v6 and the
ghcr.io/flathub-infra/flatpak-github-actions:gnome-50 image.
The trap: v6 in the old image dies with spawn dbus-daemon ENOENT. The action and the
image have to change together. Then the maintainer asked for one more thing: bump the Flatpak runtime from 41 to 50 and test it. That meant a Linux rig,
a ThinkPad, with flatpak-builder, xvfb, and a faithful copy of the action’s test
step.
The GNOME 50 SDK surfaced two real regressions. The pylast 2.2.0 sdist no longer
builds, because pip’s isolated build wants setuptools and --no-index offers none. I
moved the manifest to the pylast 4.5.0 wheel after an AST comparison showed every call
the plugin makes is identical. And the SDK has no appstream-util, so an appstream
validation test was silently dropping, taking the suite from 10 tests to 9, until a
fallback to appstreamcli validate --no-net restored 10 of 10. Upstream CI went green,
and the artifact uploaded.
Side lesson worth keeping: a fork’s CI only runs on a pull request inside the fork, or on a push to master, and the fork also runs CodeQL. Select runs by workflow file and head SHA. Never trust “newest run.”
The icon that crashed master #
Master crashed on startup with a stock Adwaita 50 icon theme, because
emblem-favorite-symbolic no longer exists. I confirmed it on Ubuntu 26.04 as well; MATE’s
Yaru theme hides it. The fix is a one-line fallback to starred-symbolic. Small,
cross-platform, and it got its own PR, because it is exactly the kind of small thing that
dies when it is stuffed into a bigger change.
The keyring design he made me redo #
Pithos stores the Pandora password with libsecret, which does not exist on macOS. My
first version wrapped the macOS security(1) command line tool. Review came back: “I
don’t really love this design. I’d rather you just pull in the keyring python package”.
His point is sharp: keyring talks to each platform’s native credential store, which
would cover Windows too, instead of one shelling out.
So I rewrote it. A KeyringService in pithos/keyring_backend.py wraps
keyring.get/set/delete_password on the app’s existing worker thread, with service name
io.github.Pithos.Account and account set to the email. util.py gained is_macos()
and is_windows(), plus the gate that picks libsecret or keyring depending on platform.
A second commit stopped notify.py from forcing the freedesktop notification backend on
macOS.
Verification: macOS with keyring 25.7.0, the macOS Keychain backend, a real login, 32
stations, and playback. Then the credential path only on Windows 11 through the
WinVaultKeyring backend. The app itself has never launched on Windows, and the PR says
so plainly.
The bonus that almost got buried: keyring reads the items the old security(1) code
had written, so there was no migration. He merged about two minutes after CI went green.
Two more small ones #
PR #731 fixed a hard crash in ErrorPlugin, harvested from the withdrawn PR’s fork.
plugin.py assigned the enabled GObject property before calling
GObject.Object.__init__, which raises a TypeError on every failed plugin load. One-line fix, its own PR, and the commit body credits the
original author.
PR #732 is still open as of this post. pandora.py logged the login request JSON at
debug level, including the password. The maintainer asked for the URL and body redaction
to be separate helpers, then it was amended and waiting.
On the mechanics: he rebased rather than merge-committed, so every commit carries me as
author and the co-author trailers survived. A stale CHANGES_REQUESTED badge stayed on
the keyring PR after the merge. That is GitHub metadata, not an outstanding request.
Things I learned the hard way #
pithos -t runs against a mock Pandora service. No login, no network, no audio. Use it
for smoke tests instead of muting the Mac and doing a real login. I muted twice before
learning.
Never run with -d while real credentials are set. The debug log contained the login
JSON. That observation became PR #732.
Setting the GStreamer volume to 0 does not mute. The sink’s volume comes back through a
notify::volume signal and overwrites the setting. The Linux PipeWire stream came up at
1.0 and the Mac at 0.64, and both login tests played out loud. Mute at the OS, not in the
app.
On macOS, GSettings land in the NSUserDefaults domain org.python.python, shared by
every Python GLib app on the machine.
First launch on macOS sits 25 to 30 seconds in the session-bus probe before logging
Failed to connect to session bus and continuing. It is not a hang. I killed it twice
before learning that. DBUS_SESSION_BUS_ADDRESS=disabled: skips the probe instantly.
Testing the Windows keyring path over SSH fails with WinError 1312 on
CredRead, “A specified logon session does not exist”. Key-based SSH is a network
logon with no credential set, so Credential Manager is unreachable. Not a code bug. Run
it in the desktop session through a scheduled task with an interactive logon type and
read the output file back over SSH.
And a test-harness pattern worth stealing: stub the app’s gobject_worker module with a
synchronous send() in a temp package directory, then import the real
keyring_backend.py. The test exercises shipping code, not a re-implementation. 13 of 13
on each platform.
What is still open #
To be blunt about coverage: a .app bundle, media keys, MPRIS, and the tray icon are all
untested on macOS. A Homebrew formula exists on a local branch and has not been proposed
anywhere. homebrew-core is not the right target yet: 1.6.2 predates macOS support, core
rejects HEAD-only formulae, and GUI-only apps are pushed to Cask, which needs a prebuilt
.app. A tap inside the project’s own repo, a HomebrewFormula/ directory, would work
with the two-argument brew tap form.
PR #732 is open. I am not calling any of this complete, and the PRs never claimed to.
Takeaways #
- Read the maintainer before writing code. One purpose per PR, new features separate, and time is the scarcest resource he has. Guarding his time is the whole game.
- Grep the diffs of open PRs, not their titles. The withdrawn PR’s title hid an icon-handling rewrite that only its diff revealed.
- A one-line fix deserves a PR of its own. The icon crash and the ErrorPlugin crash both merged fast because their scope was trivial to review.
- Prefer the maintained library over wrapping a shell tool.
keyringcovered the platform surface better thansecurity(1)ever would, and the reviewer saw that in seconds. - The new CI stack may not match the old tests. The GNOME 50 SDK dropped both
appstream-utiland the setuptools build, and both needed explicit fallbacks. - A muted volume is not a mute. When the sink overwrites your setting, mute at the OS.
- Distinguish the bug from the environment.
WinError 1312over SSH was a logon type issue, not a code defect, and shipping the fix unchanged was the right call. - Honor the trail. AI-assisted code got a co-author trailer and proper credit to the withdrawn PR’s author, exactly as the maintainer asked.
Two days, four merges, the project’s first since 2024, and a CI that had been red for months. Not bad for reading the maintainer first and spending most of the effort deciding what not to submit.