py-sonic2 1.0.4

A Python wrapper library for the Subsonic REST API

py-sonic

This is forked from crustymonkey/py-sonic with added pydantic / typing support. Some AI slop involved. I'm very sorry.

A Python wrapper library for the Subsonic REST API.

Installation

Install from PyPI using pip:

pip install py-sonic2

Or install from source:

git clone https://github.com/m00n/py-sonic.git
cd py-sonic
pip install .

Usage

This library follows the Subsonic REST API. For detailed API documentation, see:

• Subsonic API Documentation
• Python documentation: pydoc libsonic.connection

Basic Tutorial

This is about as basic as it gets. We are just going to set up the connection and then get a couple of random songs.

#!/usr/bin/env python

from pprint import pprint
import libsonic

# We pass in the base url, the username, password, and port number
# Be sure to use https:// if this is an ssl connection!
conn = libsonic.Connection('https://music.example.com' , 'myuser' ,
    'secretpass' , port=443)
# Let's get 2 completely random songs
songs = conn.getRandomSongs(size=2)
# We'll just pretty print the results we got to the terminal
pprint(songs)

As you can see, it's really pretty simple. If you use the documentation provided in the library:

pydoc libsonic.connection

or the api docs on subsonic.org (listed above), you should be able to make use of your server without too much trouble.

Right now, only plain old dictionary structures are returned. The plan for a later release includes the following:

• Proper object representations for Artist, Album, Song, etc.
• Lazy access of members (the song objects aren't created until you want to do something with them)

Development

Building and Publishing

This project includes a Makefile for easy building and publishing:

# View all available commands
make help

# Build the package
make build

# Run full release workflow
make release

# Upload to TestPyPI
make upload-test

# Upload to PyPI
make upload

For detailed instructions, see PYPI_RELEASE.md.

CI/CD

This project uses GitLab CI/CD for automated testing and publishing. The pipeline includes:

• Testing across Python 3.8-3.13
• Code quality checks with ruff
• Security scanning with safety and bandit
• Automated building of distributions
• Publishing to TestPyPI and PyPI

For CI/CD setup and configuration, see CI_CD.md.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.