Add Docker-based test harness with Transloadit CLI signature parity (#44)

* Add Docker-based test harness with Transloadit CLI parity

* Add optional end-to-end upload test harness

* Run E2E upload test in CI and improve diagnostics

* Use standard key secrets for CI E2E job

* Remove host/region overrides from E2E flow

* Skip E2E job for forked pull requests

* Skip coverage when running E2E job

* Prepare 1.0.3 release

* move RELEASE.md -> CONTRIBUTING.md

* typo

* Document streamlined release flow and add registry script

* Simplify release script to only target PyPI

Author: kvz

.gitattributes

@@ -0,0 +1 @@
+*.jpg binary

.github/workflows/ci.yml

@@ -20,8 +20,8 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: '20'
-      - name: Install tsx
-        run: npm install -g tsx
+      - name: Install Transloadit CLI
+        run: npm install -g transloadit
 
       - name: Set up Python
         uses: actions/setup-python@v4
@@ -89,3 +89,46 @@ jobs:
           path: |
             coverage.json
             htmlcov/
+
+  python-e2e:
+    runs-on: ubuntu-latest
+    needs: python
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    env:
+      PYTHON_SDK_E2E: "1"
+      TRANSLOADIT_KEY: ${{ secrets.TRANSLOADIT_KEY }}
+      TRANSLOADIT_SECRET: ${{ secrets.TRANSLOADIT_SECRET }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Install Transloadit CLI
+        run: npm install -g transloadit
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+          architecture: x64
+          cache: 'pip'
+
+      - name: Install Poetry
+        run: pip install --upgrade poetry
+
+      - name: Install dependencies
+        run: poetry install
+
+      - name: Ensure credentials present
+        run: |
+          if [ -z "$TRANSLOADIT_KEY" ] || [ -z "$TRANSLOADIT_SECRET" ]; then
+            echo "TRANSLOADIT_KEY and TRANSLOADIT_SECRET secrets must be configured for the E2E job" >&2
+            exit 1
+          fi
+
+      - name: Run E2E upload test
+        env:
+          TEST_NODE_PARITY: 0
+        run: |
+          poetry run pytest tests/test_e2e_upload.py -q --maxfail=1 --no-cov

.gitignore

@@ -43,6 +43,7 @@ htmlcov/
 .cache
 nosetests.xml
 coverage.xml
+coverage.json
 *.cover
 .hypothesis/
 
@@ -98,6 +99,9 @@ ENV/
 # mkdocs documentation
 /site
 
+# Docker/local build helpers
+.docker-cache/
+
 # mypy
 .mypy_cache/
 

CHANGELOG.md

@@ -1,3 +1,9 @@
+### 1.0.3/ 2025-28-10 ###
+* Added a Docker-based test harness (`scripts/test-in-docker.sh`) that mirrors our GitHub Actions matrix locally, including optional Smart CDN parity checks via the official Transloadit CLI.
+* Introduced an opt-in end-to-end image resize test (`tests/test_e2e_upload.py`) plus supporting `chameleon.jpg` fixture; enable by setting `PYTHON_SDK_E2E=1` along with `TRANSLOADIT_KEY`/`TRANSLOADIT_SECRET`.
+* Updated CI to run the E2E upload on Python 3.12 with guarded secrets and to skip coverage for that targeted job.
+* Documented the new workflows and ensured the Transloadit CLI integration replaces the legacy TypeScript helper.
+
 ### 1.0.2/ 2024-03-12 ###
 * Add support for Python 3.13
 

CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing
+
+## Release Checklist
+
+Use this checklist whenever you cut a new version of the Python SDK.
+
+### Prerequisites
+
+- Docker installed (our helper scripts build and run inside the project Docker image).
+- Writable Transloadit GitHub repository access.
+- A PyPI API token with upload rights to `pytransloadit` (`PYPI_TOKEN`). Store it in your shell or `.env`.
+- Optionally, a TestPyPI token (`PYPI_TEST_TOKEN`) if you want to dry‑run the release before pushing to the real registry.
+
+### 1. Prepare the Release Commit
+
+1. Update the version in all synced files:
+   - `pyproject.toml`
+   - `transloadit/__init__.py`
+   - `tests/test_request.py` (the `Transloadit-Client` header)
+2. Add a matching entry to `CHANGELOG.md`.
+3. Run the test matrix (add `PYTHON_SDK_E2E=1` if you want to exercise the live upload):
+   ```bash
+   ./scripts/test-in-docker.sh --python 3.12
+   ```
+4. Commit the changes with a message such as `Prepare 1.0.3 release`.
+
+### 2. Tag the Release
+
+After landing the release commit on `main` (or the branch you will tag), create and push an annotated tag:
+
+```bash
+git tag -a v1.0.3 -m "v1.0.3"
+git push origin main --tags
+```
+
+### 3. Publish to PyPI
+
+The `scripts/notify-registry.sh` helper publishes from inside our Docker image and performs the usual safety checks (clean git tree, version consistency, changelog entry). It looks for tokens in the environment or `.env`.
+
+Publish to the real registry:
+
+```bash
+PYPI_TOKEN=... scripts/notify-registry.sh
+```
+
+### 4. Announce the Release
+
+1. Draft a GitHub release for the new tag and paste the changelog entry.
+2. Confirm that the [Read the Docs build](https://transloadit.readthedocs.io/en/latest/) completes (it is triggered when you publish the GitHub release).
+
+That’s it—PyPI and the documentation are now up to date. For additional background see the internal guide: <https://github.com/transloadit/team-internals/blob/HEAD/_howtos/2020-12-14-maintain-python-sdk.md>.

Dockerfile

@@ -0,0 +1,31 @@
+# syntax=docker/dockerfile:1
+
+ARG PYTHON_VERSION=3.12
+FROM python:${PYTHON_VERSION}-slim AS base
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    POETRY_VIRTUALENVS_IN_PROJECT=true
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+       curl \
+       gnupg \
+       ca-certificates \
+       build-essential \
+       git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Node.js 20 (for Smart CDN parity tests) and supporting CLI tooling
+RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends nodejs \
+    && npm install -g transloadit \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Poetry so we match the GitHub Actions toolchain
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir poetry
+
+WORKDIR /workspace

README.md

@@ -48,6 +48,30 @@ See [readthedocs](https://transloadit.readthedocs.io) for full API documentation
 
 ### Running tests
 
+You can mirror our GitHub Actions setup locally by running the test matrix inside Docker:
+
+```bash
+scripts/test-in-docker.sh
+```
+
+This script will:
+
+- build images for the Python versions we test in CI (3.9–3.13)
+- install Poetry, Node.js 20, and the Transloadit CLI
+- pass credentials from `.env` (if present) so end-to-end tests can run against real Transloadit accounts
+
+Signature parity tests use `npx transloadit smart_sig` under the hood, matching the reference implementation used by our other SDKs. Our GitHub Actions workflow also runs the E2E upload against Python 3.12 on every push/PR using a dedicated Transloadit test account (wired through the `TRANSLOADIT_KEY` and `TRANSLOADIT_SECRET` secrets).
+
+Pass `--python 3.12` (or set `PYTHON_VERSIONS`) to restrict the matrix, or append a custom command after `--`, for example `scripts/test-in-docker.sh -- pytest -k smartcdn`.
+
+To exercise the optional end-to-end upload against a real Transloadit account, provide `TRANSLOADIT_KEY` and `TRANSLOADIT_SECRET` (via environment variables or `.env`) and set `PYTHON_SDK_E2E=1`:
+
+```bash
+PYTHON_SDK_E2E=1 scripts/test-in-docker.sh --python 3.12 -- pytest tests/test_e2e_upload.py
+```
+
+The test uploads `chameleon.jpg`, resizes it, and asserts on the live assembly results.
+
 If you have a global installation of `poetry`, you can run the tests with:
 
 ```bash
@@ -72,4 +96,8 @@ Generate a coverage report with:
 poetry run pytest --cov=transloadit --cov-report=html tests
 ```
 
-Then view the coverage report locally by opening `htmlcov/index.html` in your browser.
+Then view the coverage report locally by opening `htmlcov/index.html` in your browser.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local development, testing, and release instructions.

RELEASE.md

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pytransloadit"
-version = "1.0.2"
+version = "1.0.3"
 description = "A Python Integration for Transloadit's file uploading and encoding service."
 authors = ["Ifedapo Olarewaju"]
 maintainers = ["Florian Kuenzig", "Arnaud Limbourg"]
@@ -48,6 +48,9 @@ build-backend = "poetry.core.masonry.api"
 [tool.pytest.ini_options]
 addopts = "--cov=transloadit --cov-report=term-missing"
 testpaths = ["tests"]
+markers = [
+    "e2e: marks tests that hit the live Transloadit API"
+]
 
 [tool.coverage.run]
 source = ["transloadit"]