feat: override default package sources to build plugin testbeds

Author: treyturner

Dockerfile

@@ -23,6 +23,8 @@ ARG APK_BUILD_DEPS=""
 ARG DEFAULT_PIP_SOURCES="beets-beatport4 beets-filetote git+https://github.com/edgars-supe/beets-importreplace.git requests requests_oauthlib beautifulsoup4 pyacoustid pylast python3-discogs-client langdetect flask Pillow"
 # Space-separated distribution names installed in the runtime stage
 ARG DEFAULT_PIP_PACKAGES="beets-beatport4 beets-filetote beets-importreplace requests requests_oauthlib beautifulsoup4 pyacoustid pylast python3-discogs-client langdetect flask Pillow"
+# Space-separated override mappings ("pkg=spec") replacing sources in DEFAULT_PIP_SOURCES
+ARG PIP_SOURCE_OVERRIDES=""
 # Space-separated user Python packages to bundle (wheels built & installed)
 ARG USER_PIP_PACKAGES=""
 # -----------------------------------------------------------
@@ -93,6 +95,30 @@ RUN --mount=type=cache,id=builder-pip,target=/root/.cache/pip,sharing=locked \
       done; \
       default_packages="${filtered# }"; \
     fi; \
+    overrides="${PIP_SOURCE_OVERRIDES}"; \
+    if [ -n "${overrides}" ]; then \
+      for override in ${overrides}; do \
+        pkg="${override%%=*}"; \
+        src="${override#*=}"; \
+        if [ -z "${pkg}" ] || [ -z "${src}" ] || [ "${pkg}" = "${src}" ]; then \
+          echo "Invalid pip override '${override}'. Expected key=value." >&2; \
+          exit 1; \
+        fi; \
+        filtered=''; \
+        for entry in ${default_sources}; do \
+          if [ "${entry}" = "${pkg}" ]; then \
+            continue; \
+          fi; \
+          filtered="${filtered} ${entry}"; \
+        done; \
+        default_sources="${filtered# }"; \
+        if [ -n "${default_sources}" ]; then \
+          default_sources="${default_sources} ${src}"; \
+        else \
+          default_sources="${src}"; \
+        fi; \
+      done; \
+    fi; \
     tmp_dir="$(mktemp -d)"; \
     mv "${beets_wheel}" "${tmp_dir}/"; \
     if [ -n "${default_sources}" ]; then \

README.md

@@ -183,8 +183,29 @@ docker build \
 | `BEETS_REF`              | The git ref of [`beetbox/beets`](https://github.com/beetbox/beets) to build (tag, branch, or SHA)                                 |
 | `APK_BUILD_DEPS`         | Space-separated list of Alpine packages to install at build time                                                                   |
 | `APK_RUNTIME_EXTRAS`     | Space-separated list of Alpine packages to include in the final image                                                             |
+| `PIP_SOURCE_OVERRIDES`   | Space-separated overrides in the form `package=spec`, replacing entries in `DEFAULT_PIP_SOURCES`                                   |
 | `USER_PIP_PACKAGES`      | Space-separated list of user Python packages (wheels). Must already exist on PyPI or a compatible index so they can be wheeled offline. |
 
+#### Overriding default pip sources
+
+Set `PIP_SOURCE_OVERRIDES` to point specific packages at alternative sources (e.g., Git forks) without editing the Dockerfile:
+
+```bash
+docker build \
+  --build-arg PIP_SOURCE_OVERRIDES="beets-beatport4=git+https://github.com/you/beets-beatport4.git@testing" \
+  -t treyturner/beets:test-fork .
+```
+
+For sources already specified as full VCS URLs (like `importreplace`, which defaults to `git+https://github.com/edgars-supe/beets-importreplace.git`), you need to match the exact token:
+
+```bash
+docker build \
+  --build-arg PIP_SOURCE_OVERRIDES="git+https://github.com/edgars-supe/beets-importreplace.git=git+https://github.com/you/beets-importreplace.git@integration-tests" \
+  -t treyturner/beets:test-importreplace .
+```
+
+Multiple overrides can be separated by spaces, as long as each value has no whitespace.
+
 ### Container Lifecycle Overview
 
 Where each build argument and environment variable applies during the image build and container startup sequence.
@@ -202,7 +223,7 @@ Where each build argument and environment variable applies during the image buil
 flowchart TD
   A1["<strong>Build Args</strong><br/>PYTHON_VERSION<br/>PYTHON_BASE_SUFFIX"] --> B0
   A2["<strong>Build Arg</strong><br/>APK_BUILD_DEPS"] --> B1
-  A3["<strong>Build Args</strong><br/>BEETS_REF<br/>DEFAULT_PIP_SOURCES<br/>DEFAULT_PIP_PACKAGES<br/>USER_PIP_PACKAGES"] --> B2
+  A3["<strong>Build Args</strong><br/>BEETS_REF<br/>DEFAULT_PIP_SOURCES<br/>PIP_SOURCE_OVERRIDES<br/>DEFAULT_PIP_PACKAGES<br/>USER_PIP_PACKAGES"] --> B2
   A4["<strong>Build Arg</strong><br/>APK_RUNTIME_EXTRAS"] --> R1
   A5["<strong>Build Args</strong><br/>DEFAULT_PIP_PACKAGES<br/>USER_PIP_PACKAGES"] --> R2
   A6["<strong>Env. Vars</strong><br/>PUID<br/>PGID<br/>UMASK"] --> E1