Rebase

.github/workflows/tests.yaml

@@ -0,0 +1,124 @@
+# Inspired by python-package
+
+name: Tests
+on:
+  push:
+    paths:
+    - supysonic/**
+    - tests/**
+    - pyproject.toml
+  pull_request:
+    paths:
+    - supysonic/**
+    - tests/**
+    - pyproject.toml
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+      fail-fast: false
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v7
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .[test]
+    - name: Run tests
+      run: |
+        coverage run -m unittest
+    - name: Upload coverage
+      uses: codecov/codecov-action@v7
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+      if: ${{ !cancelled() }}
+
+  postgres:
+    name: PostgreSQL
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: supysonic
+        ports:
+        - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v7
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.13"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .[test,test-db]
+    - name: Enable citext extension
+      run: psql "postgresql://postgres:postgres@localhost/supysonic" -c 'CREATE EXTENSION IF NOT EXISTS citext'
+    - name: Run tests
+      env:
+        SUPYSONIC_TEST_DB_URI: postgres://postgres:postgres@localhost/supysonic
+      run: |
+        coverage run -m unittest
+    - name: Upload coverage
+      uses: codecov/codecov-action@v7
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+      if: ${{ !cancelled() }}
+
+  mariadb:
+    name: MariaDB
+    runs-on: ubuntu-latest
+    services:
+      mariadb:
+        image: mariadb:11
+        env:
+          MARIADB_ROOT_PASSWORD: root
+          MARIADB_DATABASE: supysonic
+        ports:
+        - 3306:3306
+        options: >-
+          --health-cmd "healthcheck.sh --connect --innodb_initialized"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v7
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.13"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .[test,test-db]
+    - name: Run tests
+      env:
+        SUPYSONIC_TEST_DB_URI: mysql://root:root@127.0.0.1/supysonic
+      run: |
+        coverage run -m unittest
+    - name: Upload coverage
+      uses: codecov/codecov-action@v7
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+      if: ${{ !cancelled() }}

.gitignore

@@ -10,6 +10,8 @@ __pycache__/
 # Distribution / packaging
 .Python
 env/
+*env/
+py3.*/
 build/
 develop-eggs/
 dist/
@@ -64,4 +66,7 @@ target/
 *~
 
 *.orig
+.vscode
 
+# Supysonic runtime-related files
+/cache/

.readthedocs.yaml

@@ -0,0 +1,11 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+formats: all

PACKAGING.md

@@ -0,0 +1,70 @@
+# Packaging Notes
+
+Notes for distro package maintainers.
+
+## Man pages
+
+Man pages are not included in the PyPI distribution. They must be built from
+the Sphinx sources in `docs/` using the `man` builder:
+
+```
+sphinx-build -b man docs <destdir>
+```
+
+This produces five section-1 pages, to be installed under `/usr/share/man/man1/`:
+
+| File | Description |
+|---|---|
+| `supysonic-cli.1` | Management command-line interface |
+| `supysonic-cli-user.1` | User management sub-commands |
+| `supysonic-cli-folder.1` | Folder management sub-commands |
+| `supysonic-daemon.1` | Background daemon |
+| `supysonic-server.1` | Standalone web server |
+
+`sphinx` must be available at build time. No other Sphinx extensions are required.
+
+## Configuration sample
+
+A sample configuration file is provided at `config.sample` in the repository
+root. It is not installed by the Python build. The conventional install path is:
+
+```
+/usr/share/doc/supysonic/config.sample
+```
+
+Users copy it to one of the locations Supysonic searches at startup:
+
+- `/etc/supysonic` (system-wide)
+- `~/.supysonic` (user, short form)
+- `~/.config/supysonic/supysonic.conf` (user, XDG-style)
+- `supysonic.conf` (current working directory)
+
+## Entry-point scripts
+
+Three console scripts are declared in `pyproject.toml`:
+
+| Script | Purpose |
+|---|---|
+| `supysonic-cli` | Administrative CLI (library management, user management, …) |
+| `supysonic-daemon` | Optional background daemon (file watcher, jukebox, background scans) |
+| `supysonic-server` | Built-in WSGI server (development / simple deployments) |
+
+### systemd unit for the daemon
+
+The daemon (`supysonic-daemon`) is a long-running process suitable for a
+systemd service. A minimal unit file:
+
+```ini
+[Unit]
+Description=Supysonic Daemon
+
+[Service]
+User=supysonic
+Group=supysonic
+ExecStart=/usr/bin/supysonic-daemon
+
+[Install]
+WantedBy=multi-user.target
+```
+
+See the [daemon documentation](https://supysonic.readthedocs.io/en/latest/setup/daemon.html).