feat: modernize Python tooling to uv + pyproject.toml + semantic-release - #462
Open
irfanuddinahmad wants to merge 8 commits into
Open
Conversation
Move edx_rest_api_client/ to src/edx_rest_api_client/ per the org-wide decision on openedx/public-engineering#506 (2026-07-15): src/ layout is in scope for this modernization cycle so that editable installs resolve correctly under tools like mypy (see https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/). Update setup.py, .coveragerc, and tox.ini to reference the new path so the repo remains buildable/testable with the existing pip-based tooling until pyproject.toml formalizes the src/ layout in the next commit.
Replace setup.py with PEP 621 static metadata in pyproject.toml: - name, description, classifiers, dependencies as a static list - SPDX license expression + license-files (PEP 639) - setuptools-scm for git-tag-derived versioning (dynamic version) - setuptools packages.find configured for the src/ layout - coverage configuration moved from .coveragerc into [tool.coverage.*] Remove the hardcoded __version__.py module; __version__ is now read via importlib.metadata at runtime (falls back silently if the package isn't installed), so it can no longer go stale relative to the git tag that setuptools-scm derives the build version from.
- Add PEP 735 [dependency-groups] (test-base, test, django42, quality, ci, dev) to pyproject.toml, with a Django 42/52 version matrix via [tool.uv].conflicts - Add [tool.edx_lint].uv_constraints and generate [tool.uv].constraint-dependencies via `edx_lint write_uv_constraints` - Generate and commit uv.lock - Delete requirements/ (pip-compile inputs/outputs); drop the now-stale references in MANIFEST.in - tox.ini: use tox-uv's uv-venv-lock-runner and dependency_groups instead of deps/-r requirements files - Makefile: requirements/test/upgrade targets now use uv sync/uv run tox/uv lock instead of pip-compile and pip-sync - CI: use astral-sh/setup-uv (SHA-pinned) instead of a separate actions/setup-python + pip install step; run tests via `uv run tox`; name matrix jobs by toxenv; add contents: read permissions and fetch-depth: 0 (so setuptools-scm can see tags); add a workflow_call trigger so release.yml can reuse this workflow
- Add [tool.semantic_release] to pyproject.toml (build via `python -m build` with SETUPTOOLS_SCM_PRETEND_VERSION; major_on_zero = false, allow_zero_version = true) - Add release.yml: runs CI via workflow_call, then python-semantic-release cuts the release and publishes to PyPI via OIDC trusted publishing (id-token: write, no stored credentials). Actions are pinned to plain version tags (matching openedx/XBlock's production release.yml) except pypa/gh-action-pypi-publish, which is pinned to its verified commit SHA because @release/v1 is a floating branch, not a tag (root cause of a real production failure in xblocks-core's release run) - Remove publish_pypi.yml: it published on `push: tags` using a stored PYPI_UPLOAD_TOKEN and an unpinned @release/v1 ref; once semantic-release starts pushing version tags this would race with release.yml's OIDC-based publish for the same version - commitlint.yml already existed and needed no changes Pre-flight check: latest git tag v7.0.0 matches the actual latest version on PyPI, so the first semantic-release run will compute a correct next version rather than a stale/lower one.
openedx-webhooks
added
open-source-contribution
|
Thanks for the pull request, @irfanuddinahmad! This repository is currently maintained by Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review. 🔘 Get product approvalIf you haven't already, check this list to see if your contribution needs to go through the product review process.
🔘 Provide contextTo help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:
🔘 Get a green buildIf one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green. DetailsWhere can I find more information?If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources: When can I expect my changes to be merged?Our goal is to get community contributions seen and reviewed as efficiently as possible. However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:
💡 As a result it may take up to several weeks or months to complete a review and merge your PR. |
10 tasks
changelog: "false" was blindly copied from the sample-plugin reference
template in release.yml with no ticket ever requiring it -- CHANGELOG.rst
was never deleted and is still hand-maintained. Wire up PSR to update it
automatically going forward instead of disabling it outright.
- Remove changelog: "false" from release.yml's python-semantic-release step
- Add [tool.semantic_release.changelog] (mode = "update", insertion_flag)
and [tool.semantic_release.changelog.default_templates] (CHANGELOG.rst,
rst) to pyproject.toml
- Add the ".. changelog-insertion-marker" line to the top of CHANGELOG.rst
so PSR's update mode inserts new version sections above it, leaving the
existing hand-written history untouched
- Set tag_format = "v{version}" explicitly to match this repo's actual tag
convention (v7.0.0, v6.2.0, ...) rather than relying on PSR's untested
default
…ernize-python-tooling # Conflicts: # .github/workflows/ci.yml # .github/workflows/publish_pypi.yml
Set changelog: "false" on the PSR release step and remove the [tool.semantic_release.changelog] config / insertion marker. Checked against openedx/XBlock's actual production release.yml (the one repo in this effort that has cut real automated releases) -- every run passes changelog: false and invokes `semantic-release -v version --no-changelog`, and the repo has zero github-actions[bot] commits ever. The auto-changelog config this migration previously added was only ever verified via a local dry-run prototype, never against a real release. feanil flagged the same issue on openedx/DoneXBlock#388: "I thought we were not going to add changelogs since they can't be updated by python-semantic-release the way we have it setup."
Inline tox.ini's [testenv:quality] commands via uv run/uv sync instead of shelling out to `uv run tox -e quality`, matching the no-tox-in- Makefile convention already used elsewhere. tox.ini itself is untouched.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Modernize
edx-rest-api-clientto uv + pyproject.toml (PEP 621/735) + python-semantic-release.Part of openedx/public-engineering#506 (tracked in openedx/public-engineering#516).
edx_rest_api_client/tosrc/edx_rest_api_client/(org-widesrc/layout decision, #506)setup.pywithpyproject.toml(PEP 621 static metadata)uvwith PEP 735 dependency groups; commituv.locktox.inito usetox-uvwithuv-venv-lock-runnerastral-sh/setup-uv; SHA-pin new/changed actionspython-semantic-release+release.yml, publishing to PyPI via OIDCRemoved
Deleted files:
setup.py— replaced bypyproject.tomledx_rest_api_client/__version__.py—__version__is now read viaimportlib.metadataat runtime instead of being hardcoded (it would otherwise go stale relative to the setuptools-scm-derived git-tag version).coveragerc— folded into[tool.coverage.*]inpyproject.tomlrequirements/(all.in/.txtfiles) — replaced by[dependency-groups]+uv.lock.github/workflows/publish_pypi.yml— token-based publish onpush: tags, using an unpinned@release/v1ref; superseded byrelease.yml's OIDC-based publish. Left in place, the two workflows would race to publish the same version through two different auth mechanisms once semantic-release starts pushing tags.No Makefile targets were dropped —
quality,test,requirements,upgrade,validateall still exist and run the same underlying checks, just invoked throughuv/uv run toxinstead ofpip/pip-compile/baretox.Not included / flagged for maintainer judgment
release.yml'spublish_to_pypijob publishes via OIDC (id-token: write, no stored token). This requires an org/maintainer action on PyPI's project settings (Add a trusted publisher) that can't be done from this PR or via API. Until that's configured, the firstreleaserun will succeed butpublish_to_pypiwill fail. Please confirm this is set up (or accept that risk) before merging..github/workflows/upgrade-python-requirements.ymlwill silently stop producing real PRs. This repo has a scheduled caller ofopenedx/.github's reusableupgrade-python-requirements.ymlworkflow. That reusable workflow hardcodesADD_PATHS="requirements"for its PR-creation step, with noadd_paths-style input exposed viaworkflow_call. Now thatrequirements/is deleted,make upgrade's real output (uv.lock/pyproject.tomlchanges) won't match that hardcoded glob — the scheduled job will keep running but produce an empty diff / no PR, with no failure to alert anyone. This can't be fixed from this repo; it needs a fix inopenedx/.github(parameterizeadd_paths, or auto-detectuv.lock) or an accepted decision to leave the scheduled workflow effectively disabled until then. Flagging here rather than leaving it as a silent gap..coveragerchad noomitfor test files (tests live inside the package, so they were counted toward coverage — 99% including tests). The new standardomit = ["*/tests/*", ...]would otherwise measure only production code. To avoid an artificial coverage drop, the one previously-untested line inedx_rest_api_client/__init__.py(thePackageNotFoundErrorfallback branch, which is unreachable in any real test run since the package is always installed) is marked# pragma: no cover. Net result: coverage of production code alone is 99%, matching the pre-migration combined number, so nocodecov.ymlthreshold adjustment was needed.Versioning
Dynamic.
setuptools-scmderives the build version from git tags (version_scheme = "only-version",local_scheme = "no-local-version",fallback_version = "0.0.0"). Pre-flight check: the latest git tag (v7.0.0, confirmed viagit tag --sort=-v:refname) matches the actual latest version published on PyPI (7.0.0), sopython-semantic-release's first run will compute a correct next version.Testing Notes
Verified locally (uv 0.11.30, Python 3.11 and 3.12 via
uv python install):uv lockresolves cleanly (91 packages, no repo-specific constraint overrides needed — the oldpackaging<25.0/platformdirs<4.3.7/pluggy<1.6.0pins fromrequirements/constraints.txt, added for a pylint/tox conflict tracked in unpin constrained dependencies once tox new version is released #379, are no longer needed; current resolved versions of those three packages are mutually compatible)uv sync --group devsucceedsuv run tox(all 5 envs:py311-django42,py311-django52,py312-django42,py312-django52,quality) passes from a clean.venv/.toxstate — 22 tests pass in every env,pycodestyle/pylint/python -m build/twine checkall pass inqualitysrc/edx_rest_api_client, excluding tests), matching pre-migration combined coverageNot verifiable locally: the actual OIDC PyPI publish and the semantic-release GitHub Actions run (both only exercise on push to
master, and OIDC trusted-publisher configuration is a PyPI-side setting — see "Not included" above).Code reviewer notes
src/layout:edx_rest_api_client/→src/edx_rest_api_client/, done as its own commit (refactor: move package to src/ layout) ahead of the metadata/uv/semantic-release commits, per the org-wide decision on #506.pyproject.toml[dependency-groups]:test-base→test/django42(Django version matrix via[tool.uv].conflicts) →quality/ci/dev.tox.ini'sdependency_groups =entries were checked against these actual group names (not copied from a sibling repo).pylint,pycodestyle) left untouched, no ruff — matches the parent issue's actual scope (linting tooling wasn't requested).release.ymlaction pins: everything exceptpypa/gh-action-pypi-publishuses plain version tags (@v10.6.1,@v7,@v8), matchingopenedx/XBlock's actual productionrelease.yml.pypa/gh-action-pypi-publishis pinned toba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1— this is the tag's real commit SHA (verified via the GitHub API), not the tag object SHA thatgit ls-remote --tagsreturns for annotated tags (which is a different, invalid value for auses:pin).This PR was created with Claude Code.