chore(ci): fix-ups across Make / Docker / GitHub Actions (#3241)

.github/workflows/ci.yml

@@ -47,7 +47,7 @@ jobs:
             - name: Install dependencies
               run: |
                   python3 -m pip install --upgrade pip
-                  pip3 install -r test-requirements.txt -r requirements.txt
+                  pip3 install '.[ssh,dev]'
             - name: Run unit tests
               run: |
                   docker logout

.readthedocs.yml

@@ -4,14 +4,14 @@ sphinx:
   configuration: docs/conf.py
 
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: '3.10'
+    python: '3.12'
 
 python:
   install:
-    - requirements: docs-requirements.txt
     - method: pip
       path: .
       extra_requirements:
         - ssh
+        - docs

Dockerfile

@@ -1,17 +1,13 @@
 # syntax=docker/dockerfile:1
 
 ARG PYTHON_VERSION=3.12
-
 FROM python:${PYTHON_VERSION}
 
 WORKDIR /src
-
-COPY requirements.txt /src/requirements.txt
-RUN pip install --no-cache-dir -r requirements.txt
-
-COPY test-requirements.txt /src/test-requirements.txt
-RUN pip install --no-cache-dir -r test-requirements.txt
-
 COPY . .
-ARG SETUPTOOLS_SCM_PRETEND_VERSION_DOCKER
-RUN pip install --no-cache-dir .
+
+ARG VERSION
+RUN --mount=type=cache,target=/cache/pip \
+    PIP_CACHE_DIR=/cache/pip \
+    SETUPTOOLS_SCM_PRETEND_VERSION=${VERSION} \
+    pip install .[ssh]

Dockerfile-docs

@@ -11,7 +11,12 @@ RUN addgroup --gid $gid sphinx \
  && useradd --uid $uid --gid $gid -M sphinx
 
 WORKDIR /src
-COPY requirements.txt docs-requirements.txt ./
-RUN pip install --no-cache-dir -r requirements.txt -r docs-requirements.txt
+COPY . .
+
+ARG VERSION
+RUN --mount=type=cache,target=/cache/pip \
+    PIP_CACHE_DIR=/cache/pip \
+    SETUPTOOLS_SCM_PRETEND_VERSION=${VERSION} \
+    pip install .[ssh,docs]
 
 USER sphinx

Makefile

@@ -11,12 +11,17 @@ ifeq ($(PLATFORM),Linux)
 	uid_args := "--build-arg uid=$(shell id -u) --build-arg gid=$(shell id -g)"
 endif
 
+SETUPTOOLS_SCM_PRETEND_VERSION_DOCKER ?= $(shell git describe --match '[0-9]*' --dirty='.m' --always --tags 2>/dev/null | sed -r 's/-([0-9]+)/.dev\1/' | sed 's/-/+/')
+ifeq ($(SETUPTOOLS_SCM_PRETEND_VERSION_DOCKER),)
+	SETUPTOOLS_SCM_PRETEND_VERSION_DOCKER = "dev"
+endif
+
 .PHONY: all
 all: test
 
 .PHONY: clean
 clean:
-	-docker rm -f dpy-dind-py3 dpy-dind-certs dpy-dind-ssl
+	-docker rm -f dpy-dind dpy-dind-certs dpy-dind-ssl
 	find -name "__pycache__" | xargs rm -rf
 
 .PHONY: build-dind-ssh
@@ -25,51 +30,62 @@ build-dind-ssh:
 		--pull \
 		-t docker-dind-ssh \
 		-f tests/Dockerfile-ssh-dind \
+		--build-arg VERSION=${SETUPTOOLS_SCM_PRETEND_VERSION_DOCKER} \
 		--build-arg ENGINE_VERSION=${TEST_ENGINE_VERSION} \
 		--build-arg API_VERSION=${TEST_API_VERSION} \
 		--build-arg APT_MIRROR .
 
-.PHONY: build-py3
-build-py3:
+.PHONY: build
+build:
 	docker build \
 		--pull \
 		-t docker-sdk-python3 \
 		-f tests/Dockerfile \
+		--build-arg VERSION=${SETUPTOOLS_SCM_PRETEND_VERSION_DOCKER} \
 		--build-arg APT_MIRROR .
 
 .PHONY: build-docs
 build-docs:
-	docker build -t docker-sdk-python-docs -f Dockerfile-docs $(uid_args) .
+	docker build \
+		-t docker-sdk-python-docs \
+		-f Dockerfile-docs \
+		--build-arg VERSION=${SETUPTOOLS_SCM_PRETEND_VERSION_DOCKER} \
+		$(uid_args) \
+		.
 
 .PHONY: build-dind-certs
 build-dind-certs:
-	docker build -t dpy-dind-certs -f tests/Dockerfile-dind-certs .
+	docker build \
+		-t dpy-dind-certs \
+		-f tests/Dockerfile-dind-certs \
+		--build-arg VERSION=${SETUPTOOLS_SCM_PRETEND_VERSION_DOCKER} \
+		.
 
 .PHONY: test
-test: ruff unit-test-py3 integration-dind integration-dind-ssl
+test: ruff unit-test integration-dind integration-dind-ssl
 
-.PHONY: unit-test-py3
-unit-test-py3: build-py3
+.PHONY: unit-test
+unit-test: build
 	docker run -t --rm docker-sdk-python3 py.test tests/unit
 
-.PHONY: integration-test-py3
-integration-test-py3: build-py3
+.PHONY: integration-test
+integration-test: build
 	docker run -t --rm -v /var/run/docker.sock:/var/run/docker.sock docker-sdk-python3 py.test -v tests/integration/${file}
 
 .PHONY: setup-network
 setup-network:
 	docker network inspect dpy-tests || docker network create dpy-tests
 
 .PHONY: integration-dind
-integration-dind: integration-dind-py3
+integration-dind: integration-dind
 
-.PHONY: integration-dind-py3
-integration-dind-py3: build-py3 setup-network
-	docker rm -vf dpy-dind-py3 || :
+.PHONY: integration-dind
+integration-dind: build setup-network
+	docker rm -vf dpy-dind || :
 
 	docker run \
 		--detach \
-		--name dpy-dind-py3 \
+		--name dpy-dind \
 		--network dpy-tests \
 		--pull=always \
 		--privileged \
@@ -82,22 +98,22 @@ integration-dind-py3: build-py3 setup-network
 		--rm \
 		--tty \
 		busybox \
-		sh -c 'while ! nc -z dpy-dind-py3 2375; do sleep 1; done'
+		sh -c 'while ! nc -z dpy-dind 2375; do sleep 1; done'
 
 	docker run \
-		--env="DOCKER_HOST=tcp://dpy-dind-py3:2375" \
+		--env="DOCKER_HOST=tcp://dpy-dind:2375" \
 		--env="DOCKER_TEST_API_VERSION=${TEST_API_VERSION}" \
 		--network dpy-tests \
 		--rm \
 		--tty \
 		docker-sdk-python3 \
 		py.test tests/integration/${file}
 
-	docker rm -vf dpy-dind-py3
+	docker rm -vf dpy-dind
 
 
 .PHONY: integration-dind-ssh
-integration-dind-ssh: build-dind-ssh build-py3 setup-network
+integration-dind-ssh: build-dind-ssh build setup-network
 	docker rm -vf dpy-dind-ssh || :
 	docker run -d --network dpy-tests --name dpy-dind-ssh --privileged \
 		docker-dind-ssh dockerd --experimental
@@ -116,7 +132,7 @@ integration-dind-ssh: build-dind-ssh build-py3 setup-network
 
 
 .PHONY: integration-dind-ssl
-integration-dind-ssl: build-dind-certs build-py3 setup-network
+integration-dind-ssl: build-dind-certs build setup-network
 	docker rm -vf dpy-dind-certs dpy-dind-ssl || :
 	docker run -d --name dpy-dind-certs dpy-dind-certs
 
@@ -164,13 +180,13 @@ integration-dind-ssl: build-dind-certs build-py3 setup-network
 	docker rm -vf dpy-dind-ssl dpy-dind-certs
 
 .PHONY: ruff
-ruff: build-py3
+ruff: build
 	docker run -t --rm docker-sdk-python3 ruff docker tests
 
 .PHONY: docs
 docs: build-docs
 	docker run --rm -t -v `pwd`:/src docker-sdk-python-docs sphinx-build docs docs/_build
 
 .PHONY: shell
-shell: build-py3
+shell: build
 	docker run -it -v /var/run/docker.sock:/var/run/docker.sock docker-sdk-python3 python

README.md

@@ -6,7 +6,7 @@ A Python library for the Docker Engine API. It lets you do anything the `docker`
 
 ## Installation
 
-The latest stable version [is available on PyPI](https://pypi.python.org/pypi/docker/). Either add `docker` to your `requirements.txt` file or install with pip:
+The latest stable version [is available on PyPI](https://pypi.python.org/pypi/docker/). Install with pip:
 
     pip install docker
 

pyproject.toml

@@ -36,13 +36,34 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+# ssh feature allows DOCKER_HOST=ssh://... style connections
 ssh = [
     "paramiko>=2.4.3",
 ]
-tls = []  # kept for backwards compatibility
+# tls is always supported, the feature is a no-op for backwards compatibility
+tls = []
+# websockets can be used as an alternate container attach mechanism but
+# by default docker-py hijacks the TCP connection and does not use Websockets
+# unless attach_socket(container, ws=True) is called
 websockets = [
     "websocket-client >= 1.3.0",
 ]
+# docs are dependencies required to build the ReadTheDocs site
+# this is only needed for CI / working on the docs!
+docs = [
+    "myst-parser==0.18.0",
+    "Sphinx==5.1.1",
+
+]
+# dev are dependencies required to test & lint this project
+# this is only needed if you are making code changes to docker-py!
+dev = [
+    "coverage==7.2.7",
+    "pytest==7.4.2",
+    "pytest-cov==4.1.0",
+    "pytest-timeout==2.1.0",
+    "ruff==0.1.8",
+]
 
 [project.urls]
 Changelog = "https://docker-py.readthedocs.io/en/stable/change-log.html"

tests/Dockerfile

@@ -1,7 +1,6 @@
 # syntax=docker/dockerfile:1
 
 ARG PYTHON_VERSION=3.12
-
 FROM python:${PYTHON_VERSION}
 
 RUN apt-get update && apt-get -y install --no-install-recommends \
@@ -27,16 +26,10 @@ RUN curl -sSL -o /opt/docker-credential-pass.tar.gz \
     chmod +x /usr/local/bin/docker-credential-pass
 
 WORKDIR /src
+COPY . .
 
-COPY requirements.txt /src/requirements.txt
-RUN --mount=type=cache,target=/root/.cache/pip \
-    pip install -r requirements.txt
-
-COPY test-requirements.txt /src/test-requirements.txt
-RUN --mount=type=cache,target=/root/.cache/pip \
-    pip install -r test-requirements.txt
-
-COPY . /src
-ARG SETUPTOOLS_SCM_PRETEND_VERSION=99.0.0+docker
-RUN --mount=type=cache,target=/root/.cache/pip \
-    pip install -e .
+ARG VERSION
+RUN --mount=type=cache,target=/cache/pip \
+    PIP_CACHE_DIR=/cache/pip \
+    SETUPTOOLS_SCM_PRETEND_VERSION=${VERSION} \
+    pip install .[dev,ssh,websockets]

tox.ini

@@ -6,11 +6,8 @@ skipsdist=True
 usedevelop=True
 commands =
     py.test -v --cov=docker {posargs:tests/unit}
-deps =
-    -r{toxinidir}/test-requirements.txt
-    -r{toxinidir}/requirements.txt
+extras = dev
 
 [testenv:ruff]
 commands = ruff docker tests setup.py
-deps =
-    -r{toxinidir}/test-requirements.txt
+extras = dev