chore: modernize Python tooling (uv, PEP 621, semantic-release, src layout)

.github/workflows/ci.yml

@@ -7,13 +7,15 @@ on:
     branches:
     - '**'
   workflow_dispatch:
+  workflow_call:
 
 concurrency:
   group: "${{ github.workflow }}-${{ github.ref }}"
   cancel-in-progress: true
 
 jobs:
   tests:
+    name: ${{ matrix.toxenv }}
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -22,21 +24,23 @@ jobs:
         python-version: ['3.12']
         toxenv: [django42, django52, quality, package]
 
+    permissions:
+      contents: read
+
     steps:
     - name: checkout repo
       uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       with:
         submodules: recursive
 
-    - name: setup python
-      uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+    - name: Setup uv
+      uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
       with:
+        enable-cache: true
         python-version: ${{ matrix.python-version }}
 
-    - name: Install Dependencies
-      run: make requirements
+    - name: Install CI dependencies
+      run: uv sync --group ci
 
     - name: Run Tests
-      env:
-        TOXENV: ${{ matrix.toxenv }}
-      run: tox
+      run: uv run tox -e ${{ matrix.toxenv }}

.github/workflows/release.yml

@@ -0,0 +1,116 @@
+name: Semantic Release
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  # The same aggregate a pull request has to pass, so the release runs exactly
+  # the checks that were required to merge -- and picks up any package added to
+  # ci.yml later without needing a change here.
+  run_ci:
+    uses: ./.github/workflows/ci.yml
+
+  release:
+    # Every package this workflow publishes has to build before we tag
+    # anything. The GitHub release and the PyPI uploads cannot be taken back,
+    # so a package that only fails to build in its publish job would leave the
+    # release half-finished.
+    needs: [run_ci]
+    runs-on: ubuntu-latest
+    if: github.ref_name == 'master'
+    concurrency:
+      group: ${{ github.workflow }}-release-${{ github.ref_name }}
+      cancel-in-progress: false
+
+    permissions:
+      contents: write
+
+    steps:
+      # Note: We checkout the repository at the branch that triggered the workflow.
+      # Python Semantic Release will automatically convert shallow clones to full clones
+      # if needed to ensure proper history evaluation. However, we forcefully reset the
+      # branch to the workflow sha because it is possible that the branch was updated
+      # while the workflow was running, which prevents accidentally releasing un-evaluated
+      # changes.
+      - name: Setup | Checkout Repository on Release Branch
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.ref_name }}
+
+      - name: Setup | Force release branch to be at workflow sha
+        run: |
+          git reset --hard ${{ github.sha }}
+
+      - name: Action | Semantic Version Release
+        id: release
+        # Adjust tag with desired version if applicable.
+        uses: python-semantic-release/python-semantic-release@9a026e9303981c866c3425723009becb2437c757 # v10.6.2
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          git_committer_name: "github-actions"
+          git_committer_email: "actions@users.noreply.github.com"
+          changelog: "false"
+          # Commit, tag, push and build, but don't create the GitHub release.
+          # We create it ourselves in the next step so that the distributions
+          # are attached before the release is published. See that step for why.
+          vcs_release: "false"
+
+      # This repo has immutable releases enabled, which freezes a release's
+      # assets the moment it is published, so assets cannot be attached
+      # afterwards. Everything we want on the release has to be built by now
+      # and passed to this one command, which creates the release as a draft,
+      # uploads the assets, and only then publishes it:
+      # https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/immutable-releases
+      - name: Publish | Create GitHub Release with Assets
+        if: steps.release.outputs.released == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Reuse the release notes python-semantic-release generated for us.
+          RELEASE_NOTES: ${{ steps.release.outputs.release_notes }}
+          TAG: ${{ steps.release.outputs.tag }}
+        run: |
+          # Output the release notes to a file
+          printf '%s' "$RELEASE_NOTES" > "$RUNNER_TEMP/release_notes.md"
+          # Creates the release as a draft, uploads the assets, and then
+          # publishes it -- all within this one command.
+          gh release create "$TAG" \
+            --verify-tag \
+            --title "$TAG" \
+            --notes-file "$RUNNER_TEMP/release_notes.md" \
+            dist/*
+
+      - name: Upload | Distribution Artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: steps.release.outputs.released == 'true'
+        with:
+          name: distribution-artifacts
+          path: dist/
+          if-no-files-found: error
+
+    outputs:
+      released: ${{ steps.release.outputs.released || 'false' }}
+      version: ${{ steps.release.outputs.version }}
+
+  publish_to_pypi:
+    # 1. Separate out the publish step from the github release step to run each step at
+    #    the least amount of token privilege
+    # 2. Also, publishing can fail, and its better to have a separate job if you need to retry
+    #    and it won't require reversing the release.
+    runs-on: ubuntu-latest
+    needs: release
+    if: github.ref_name == 'master' && needs.release.outputs.released == 'true'
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Setup | Download Build Artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distribution-artifacts
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

MANIFEST.in

@@ -1,4 +1,2 @@
 include LICENSE
 include README.md
-include requirements/base.in
-include requirements/constraints.txt

Makefile

@@ -1,9 +1,10 @@
 .PHONY: clean compile_translations dummy_translations \
-	extract_translations dummy_translations help
+	extract_translations dummy_translations help \
+	test quality
 
 .DEFAULT_GOAL := help
 
-WORKING_DIR := image_explorer
+WORKING_DIR := src/image_explorer
 EXTRACT_DIR := $(WORKING_DIR)/conf/locale/en/LC_MESSAGES
 EXTRACTED_DJANGO_PARTIAL := $(EXTRACT_DIR)/django-partial.po
 EXTRACTED_DJANGOJS_PARTIAL := $(EXTRACT_DIR)/djangojs-partial.po
@@ -22,31 +23,19 @@ clean: ## remove generated byte code, coverage reports, and build artifacts
 	rm -fr dist/
 	rm -fr *.egg-info
 
-piptools: ## install pinned version of pip-compile and pip-sync
-	pip install -r requirements/pip.txt
-	pip install -r requirements/pip-tools.txt
+test: ## run tests
+	mkdir -p var
+	uv run pytest $(posargs)
 
-requirements: piptools  ## install test requirements locally
-	pip-sync requirements/ci.txt
+quality: ## run linting
+	uv run pylint --fail-under=9.0 src/image_explorer
 
-requirements_python: piptools  ## install all requirements locally
-	pip-sync requirements/base.txt requirements/ci.txt requirements/test.txt requirements/private.*
+requirements: ## install development environment requirements
+	uv sync --group dev
 
-# Define PIP_COMPILE_OPTS=-v to get more information during make upgrade.
-PIP_COMPILE = pip-compile --upgrade $(PIP_COMPILE_OPTS)
-
-upgrade: export CUSTOM_COMPILE_COMMAND=make upgrade
-upgrade: ## update the requirements/*.txt files with the latest packages satisfying requirements/*.in
-	pip install -qr requirements/pip-tools.txt
-	# Make sure to compile files after any other files they include!
-	$(PIP_COMPILE) --allow-unsafe -o requirements/pip.txt requirements/pip.in
-	$(PIP_COMPILE) -o requirements/pip-tools.txt requirements/pip-tools.in
-	pip install -qr requirements/pip.txt
-	pip install -qr requirements/pip-tools.txt
-	$(PIP_COMPILE) -o requirements/base.txt requirements/base.in
-	$(PIP_COMPILE) -o requirements/test.txt requirements/test.in
-	$(PIP_COMPILE) -o requirements/ci.txt requirements/ci.in
-	sed -i '/^[dD]jango==/d' requirements/test.txt
+upgrade: ## update uv.lock and constraints with the latest packages
+	uv run --with edx-lint edx_lint write_uv_constraints pyproject.toml
+	uv lock --upgrade
 
 ## Localization targets
 

pyproject.toml

@@ -0,0 +1,142 @@
+[build-system]
+requires = ["setuptools", "setuptools-scm>8.1"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xblock-image-explorer"
+description = "XBlock - Image Explorer"
+readme = "README.md"
+license = "AGPL-3.0"
+license-files = ["LICENSE"]
+authors = [
+    {name = "edX", email = "oscm@edx.org"},
+]
+keywords = ["Python", "edx", "xblock"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: Django",
+    "Framework :: Django :: 4.2",
+    "Framework :: Django :: 5.2",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+]
+requires-python = ">=3.12"
+dynamic = ["version"]
+dependencies = [
+    "xblock[django]",
+]
+
+[project.urls]
+Homepage = "https://github.com/openedx/xblock-image-explorer"
+
+[project.entry-points."xblock.v1"]
+image-explorer = "image_explorer:ImageExplorerBlock"
+
+[tool.setuptools_scm]
+version_scheme = "only-version"
+local_scheme = "no-local-version"
+# Dummy version number for when .git isn't accessible.
+# This happens, for example, when bind-mounting into a Docker image.
+fallback_version = "0.0.0.dev0"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["image_explorer*"]
+
+[tool.setuptools.package-data]
+"image_explorer" = [
+    "static/**",
+    "templates/**",
+    "public/**",
+    "conf/locale/**",
+]
+
+[tool.setuptools.exclude-package-data]
+"*" = ["tests*", "*.tests*", "spec*", "*.spec*"]
+
+[tool.coverage.run]
+branch = true
+source_pkgs = ["image_explorer"]
+omit = [
+    "*/tests/*",
+    "*/migrations/*",
+    "*/__pycache__/*",
+    "*/settings.py",
+]
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]
+
+[tool.coverage.html]
+directory = "htmlcov"
+
+[dependency-groups]
+# Base test dependencies (no Django — pinned per group below)
+test-base = [
+    "mock",
+    "pytest-cov",
+    "pytest-django",
+    "xblock-sdk",
+]
+# Default test group uses current supported Django (5.2)
+test = [
+    {include-group = "test-base"},
+    "Django>=5.2,<6.0",
+]
+# Legacy Django 4.2 support
+django42 = [
+    {include-group = "test-base"},
+    "Django>=4.2,<5.0",
+]
+quality = [
+    {include-group = "test"},
+    "edx-lint",
+    "pycodestyle",
+]
+package = [
+    "build",
+    "twine",
+]
+# Minimal CI group — install first, then call uv run tox
+ci = [
+    "tox",
+    "tox-uv>=1",
+]
+dev = [
+    {include-group = "quality"},
+    {include-group = "ci"},
+    {include-group = "package"},
+]
+
+[tool.semantic_release]
+# version is dynamic via setuptools-scm; no version_toml needed
+build_command = "python -m pip install --upgrade build && SETUPTOOLS_SCM_PRETEND_VERSION=$NEW_VERSION python -m build"
+
+[tool.edx_lint]
+uv_constraints = []
+
+# NOTE: [tool.uv].constraint-dependencies is machine-managed.
+# Run: uv run --with edx-lint edx_lint write_uv_constraints pyproject.toml
+[tool.uv]
+package = true
+default-groups = []
+conflicts = [
+    [
+        {group = "test"},
+        {group = "django42"},
+    ],
+]
+constraint-dependencies = [
+    "Django<6.0",
+    "elasticsearch<7.14.0",
+]