feat: modernize Python tooling (pyproject.toml + uv + semantic-release)

[irfanuddinahmad]

Summary

Modernizes this repo's Python tooling per the org-wide standardization tracked in openedx/public-engineering#513 (and the parent openedx/public-engineering#506):

• Consolidate package metadata into pyproject.toml (PEP 621, setuptools-scm for git-tag-based versioning), replacing setup.py/setup.cfg
• Switch dependency management from pip-compile to uv: requirements/*.in+*.txt are replaced by PEP 735 [dependency-groups] + a single uv.lock
• Add python-semantic-release: pushes to main with conventional commits now automatically bump the version, tag it, and publish to PyPI (reusing the existing PYPI_UPLOAD_TOKEN secret)
• Fix .readthedocs.yaml, which pointed at the now-deleted requirements/doc.txt

Part of openedx/public-engineering#513.

Test plan

• uv lock resolves cleanly
• uv build --wheel (with SETUPTOOLS_SCM_PRETEND_VERSION) succeeds, producing a correctly versioned wheel
• Could not fully verify uv sync/uv run tox on my machine (no libmysqlclient/pkg-config locally to build mysqlclient from source) -- CI's ubuntu-latest runners have these preinstalled, so this needs verifying there.

Release readiness (pre-merge blocker)

• PyPI trusted publisher (OIDC) configured for openedx-ledger
  → GitHub repo openedx/openedx-ledger, workflow release.yml
• Confirmed working by:

Do not merge until both boxes are checked -- until then, publish_to_pypi will fail
on first merge to main (this PR switches the workflow to OIDC; it does not
configure the trusted publisher itself, which is a PyPI project-settings action with
no API we can drive from here). Tracked across this whole effort in a consolidated
comment on openedx/public-engineering#506.

🤖 Generated with Claude Code

[openedx-webhooks]

Thanks for the pull request, @irfanuddinahmad!

This repository is currently maintained by @openedx/2u-enterprise.

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 approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

• If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
  • This process (including the steps you'll need to take) is documented here.
• If it doesn't, simply proceed with the next step.

🔘 Provide context

To 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:

• Dependencies

  This PR must be merged before / after / at the same time as ...

• Blockers

  This PR is waiting for OEP-1234 to be accepted.

• Timeline information

  This PR must be merged by XX date because ...

• Partner information

  This is for a course on edx.org.

• Supporting documentation
• Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

---

Where 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:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

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:

• The size and impact of the changes that it introduces
• The need for product review
• Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

[mphilbrick211]

Hi @irfanuddinahmad! Would you mind taking a look at the branch conflicts that have popped up? Thanks!

[farhan]

tests are failing

[farhan]

Done with the pass

[farhan]

astral-sh/setup-uv is missing two parameters:

- name: Install uv
  uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
  with:
    enable-cache: true
    python-version: "${{ matrix.python-version }}"

Without enable-cache: true the uv package cache is not persisted across runs. Without python-version, Python is not managed by setup-uv, which leaves the setup python step above still load-bearing rather than redundant.

[irfanuddinahmad]

Confirmed already correct — setup-uv has both enable-cache: true and python-version set.

[farhan]

Making readme dynamic is non-standard for this migration pattern. Target state is dynamic = ["version"] only. The readme field can be set statically under [project] or omitted — the distribution still builds correctly.

[farhan]

Already addressed — dynamic = ["version"] only, with readme set statically as readme = "README.rst" under [project].

[farhan]

CHANGELOG.rst must be deleted for PyPI repos that use python-semantic-release. Drop it from this list:

readme = {file = ["README.rst"], content-type = "text/x-rst"}

Also delete the CHANGELOG.rst file from the repo root.

[farhan]

Already addressed — readme points only to README.rst and CHANGELOG.rst was deleted from the repo.

[farhan]

[tool.uv] is missing package = true. For a PyPI package with setuptools-scm, this tells uv the project should be built and installed as a package:

[tool.uv]
package = true

[irfanuddinahmad]

Confirmed already present — [tool.uv] package = true is set.

[farhan]

[tool.coverage] is absent from pyproject.toml. Once .coveragerc is deleted, coverage configuration will be lost. Migrate .coveragerc here before deleting it. Also, .coveragerc uses source = edx_ledger — the correct package name is openedx_ledger. Use source_pkgs (not source) for installed packages:

[tool.coverage.run]
branch = True
source_pkgs = ["openedx_ledger"]

[tool.coverage.html]
directory = "build/coverage/html"

[tool.coverage.xml]
output = "build/coverage/coverage.xml"

[irfanuddinahmad]

Confirmed already correct — [tool.coverage.run] exists with source_pkgs = ["openedx_ledger"] (correct package name, correct use of source_pkgs over source).

[farhan]

The requirements target is missing uv tool install tox --with tox-uv. Without it, tox won't be available as a tool-level command on a fresh checkout:

requirements: ## install development environment requirements
	uv sync --group dev
	uv tool install tox --with tox-uv

[irfanuddinahmad]

On reflection, reverting this — it installs an unpinned tox outside uv.lock, which is inconsistent with every other tox invocation in this repo (test-all/quality/pii_check Makefile targets, ci.yml), all of which use uv run tox via the ci/dev dependency-groups that already declare tox/tox-uv. Removed the added line to keep this consistent with the rest of the repo's pattern.

[farhan]

--cov openedx_ledger is a path argument; with the src/ layout the package lives at src/openedx_ledger/, so pytest-cov may not resolve it correctly.

[tool.coverage.run] already has source_pkgs = ["openedx_ledger"], which works by package name regardless of layout. Options:

• Change to --cov src/openedx_ledger, or
• Drop --cov openedx_ledger from addopts and rely solely on source_pkgs.

[irfanuddinahmad]

Verified empirically — pytest-cov/coverage.py resolve --cov <name> by installed import name, not filesystem path, so this works correctly under the src/ layout (confirmed with an isolated test package). No change needed here; [tool.coverage.run]'s source_pkgs handles the layout-independent resolution as you noted.

[farhan]

allow_zero_version and major_on_zero only govern the 0.x → 1.0.0 transition. The latest tag is 1.8.0, so both settings are no-ops — the comment on the preceding lines acknowledges this.

Remove them to reduce confusion (or keep the comment and explicitly note they are intentionally omitted).

[irfanuddinahmad]

Good catch on the tag — it's actually 2.0.0 now (not 1.8.0), even further past the 0.x transition these settings govern. Keeping the settings as-is for consistency across the whole batch of repos in this migration effort, even though they're no-ops here.

[farhan]

setup.py had 'License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)' in classifiers. The new license = "AGPL-3.0-or-later" SPDX field is correct, but PyPI still renders the trove classifier separately on the project page.

The two can coexist — consider re-adding the License :: trove classifier alongside the SPDX field.

[irfanuddinahmad]

Tried adding this back, but it turns out to be a hard build break, not just cosmetic: setuptools (>=77, which is what our locked build-system pulls — 83.0.0 per uv.lock) raises InvalidConfigError ("License classifiers have been superseded by license expressions", PEP 639) whenever a License :: classifier is combined with the PEP 621 SPDX license = "AGPL-3.0-or-later" field we already set. Reproduced locally with uv sync — it fails unconditionally, so this would break uv sync/pip install/CI for anyone. Since the SPDX license field is the correct modern replacement for that classifier and both can't coexist under the toolchain this repo already standardized on, I'm leaving classifiers as-is (no License :: entry) rather than reintroducing the old setup.py's classifier.