Migrate to uv, ruff, and pyproject.toml

.github/dependabot.yml

@@ -1,9 +1,9 @@
-# Automatically update versions for pip
+# Automatically update versions for uv
 
 version: 2
 updates:
   # Maintain dependencies for Python
-  - package-ecosystem: "pip"
+  - package-ecosystem: "uv"
     directory: "/"
     schedule:
       interval: "monthly"

.github/workflows/pre-commit.yml

@@ -28,5 +28,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
-      - uses: pre-commit/action@v3.0.1
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-python: true
+      - name: Run prek
+        run: uvx prek run --all-files

.github/workflows/python-publish.yml

@@ -12,15 +12,14 @@ jobs:
       id-token: write
     steps:
       - uses: actions/checkout@v6
-      - name: Set up Python
-        uses: actions/setup-python@v6
         with:
-          python-version: 3.9
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install setuptools wheel pre-commit
+          fetch-depth: 0
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-python: true
       - name: Build distribution
-        run: make dist
+        run: uv build
       - name: Publish package distributions to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/pythontest.yml

@@ -20,7 +20,7 @@ jobs:
         uses: fkirc/skip-duplicate-actions@master
         with:
           github_token: ${{ github.token }}
-          paths: '["**.py", "requirements_test.txt", ".github/workflows/pythontest.yml"]'
+          paths: '["**.py", "pyproject.toml", "uv.lock", ".github/workflows/pythontest.yml"]'
   unit_test:
     name: Python unit tests
     needs: pre_job
@@ -30,16 +30,19 @@ jobs:
       fail-fast: false
       matrix:
         os: [windows-latest, ubuntu-latest, macos-latest]
-        python-version: [3.9, '3.10', '3.11', '3.12', '3.13']
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
     steps:
       - uses: actions/checkout@v6
         if: ${{ needs.pre_job.outputs.should_skip != 'true' }}
-      - name: Set up Python ${{ matrix.python-version }}
+        with:
+          fetch-depth: 0
+      - name: Set up uv
         if: ${{ needs.pre_job.outputs.should_skip != 'true' }}
-        uses: actions/setup-python@v6
+        uses: astral-sh/setup-uv@v7
         with:
+          enable-cache: true
+          cache-python: true
           python-version: ${{ matrix.python-version }}
-          cache: 'pip'
       - name: Install Ubuntu dependencies
         run: |
           sudo apt-get -y -qq update
@@ -104,17 +107,6 @@ jobs:
         run: |
           Add-Content -Path $env:GITHUB_PATH -Value "$env:GITHUB_WORKSPACE\tools\ffmpeg-master-latest-win64-gpl\bin" -Encoding utf8
           Add-Content -Path $env:GITHUB_PATH -Value "$env:GITHUB_WORKSPACE\tools\poppler-21.11.0\Library\bin" -Encoding utf8
-      - name: Install tox
-        if: ${{ needs.pre_job.outputs.should_skip != 'true' }}
-        run: |
-          python -m pip install --upgrade pip
-          pip install tox
-      - name: tox env cache
-        if: ${{ needs.pre_job.outputs.should_skip != 'true' && !startsWith(runner.os, 'windows') }}
-        uses: actions/cache@v5
-        with:
-          path: ${{ github.workspace }}/.tox/py${{ matrix.python-version }}
-          key: ${{ runner.os }}-tox-py${{ matrix.python-version }}-${{ hashFiles('setup.py') }}
-      - name: Test with tox
+      - name: Run tests
         if: ${{ needs.pre_job.outputs.should_skip != 'true' }}
-        run: tox -e py${{ matrix.python-version }}
+        run: uv run --group test --extra google_drive pytest

.gitignore

@@ -49,7 +49,6 @@ pip-delete-this-directory.txt
 
 # Unit test / coverage reports
 htmlcov/
-.tox/
 .coverage
 .coverage.*
 .cache
@@ -137,3 +136,6 @@ cache.sqlite
 
 chefdata/
 audio_cache.sqlite
+
+# uv
+.venv/

.pre-commit-config.yaml

@@ -1,15 +1,10 @@
 repos:
-  - repo: https://github.com/python/black
-    rev: 21.12b0
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.6
     hooks:
-      - id: black
-        types_or: [python, pyi]
-        additional_dependencies: ['click==8.0.4']
-  - repo: https://github.com/pycqa/flake8
-    rev: 7.1.1
-    hooks:
-      - id: flake8
-        exclude: (?x)(.*examples.*)
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.1.0
     hooks:
@@ -20,10 +15,6 @@ repos:
       - id: debug-statements
       - id: end-of-file-fixer
         exclude: '^.+?\.json$'
-  - repo: https://github.com/asottile/reorder_python_imports
-    rev: v2.6.0
-    hooks:
-      - id: reorder-python-imports
   - repo: https://github.com/google/yamlfmt
     rev: v0.14.0
     hooks:
@@ -35,3 +26,7 @@ repos:
       - id: actionlint
         # Expects shellcheck to be installed on the system
         # https://github.com/koalaman/shellcheck#installing
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.11.2
+    hooks:
+      - id: uv-lock

.readthedocs.yml

@@ -6,7 +6,8 @@ build:
     python: "3.11"
   jobs:
     pre_install:
-      - pip install -e .
+      - pip install uv
+      - uv pip install -e . --system
 sphinx:
   configuration: docs/conf.py
 python:

AGENTS.md

@@ -5,19 +5,19 @@ Guidance for AI coding agents working in this repository.
 ## Quick Start
 
 ```bash
-pip install -e '.[test,dev]'        # install (use uv pip if venv was created with uv)
-pytest                              # run all tests
-pytest tests/test_files.py          # run a single test file
-pytest -k 'test_something'         # filter by test name
-pre-commit run --all-files          # lint (the ONLY way to run linting)
+uv sync --group dev                 # install (creates .venv and installs all dev dependencies)
+uv run --group test pytest          # run all tests
+uv run --group test pytest tests/test_files.py   # run a single test file
+uv run --group test pytest -k 'test_something'   # filter by test name
+uvx prek run --all-files            # lint (the ONLY way to run linting)
 ```
 
 **System dependencies:** `ffmpeg` and `poppler-utils`.
 
 ## Critical Gotchas
 
-- **Linting:** Always use `pre-commit run --all-files`. Never run black, flake8, or other tools directly.
-- **Line length:** 160 characters, enforced by pre-commit.
+- **Linting:** Always use `uvx prek run --all-files`. Never run ruff, black, flake8, or other tools directly.
+- **Line length:** 160 characters, enforced by prek/ruff.
 - **New file types require exactly two changes:** (1) a conversion handler in `convert.py`, (2) a metadata extractor in `extract_metadata.py`. That's it. Do NOT touch `classes/files.py` or `classes/nodes.py` — the existing File/Node subclasses there are legacy backwards-compatibility APIs that are NOT needed for new file types. The pipeline infers kinds and presets automatically.
 - **Test placement:** Pipeline tests go in `tests/pipeline/` — add to existing files like `test_convert.py` and `test_extract_metadata.py`. Do not create new test files.
 - **Validation logic:** Each handler implements only the validation its spec requires. Do not copy validation from other handlers (e.g., do not add HTML body parsing or empty-body checks unless the spec explicitly requires them).

CLAUDE.md

@@ -24,7 +24,7 @@ Three stages with ordered handlers: **transfer** (download) → **convert** (com
 
 - The pipeline code is the reference architecture — follow its OOP patterns when writing new code.
 - Older code (especially `ricecooker/classes/`) has less test coverage. Take extra care when modifying it.
-- PRs target `main` on `learningequality/ricecooker`. CI tests Python 3.9–3.13 on Linux, macOS, and Windows.
+- PRs target `main` on `learningequality/ricecooker`. CI tests Python 3.9–3.13 on Linux, macOS, and Windows using uv.
 
 ### Adding support for new file types
 

CONTRIBUTING.md

@@ -49,9 +49,7 @@ Becoming a ricecooker developer
 -------------------------------
 
 Ready to contribute? In order to work on the `ricecooker` code you'll first need
-to make you have [Python 3](https://www.python.org/downloads/) on your computer.
-You'll also need to install the Python package [pip](https://pypi.org/project/pip/)
-if you don't have it already.
+to have [Python 3.9+](https://www.python.org/downloads/) on your computer.
 
 Here are the steps for setting up `ricecooker` for local development:
 
@@ -65,46 +63,23 @@ Here are the steps for setting up `ricecooker` for local development:
     cd ricecooker/
     ```
 
-3. Create a Python virtual environment for this project (optional, but recommended):
+3. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) if you don't have it already:
 
-   * Install the `virtualenv` package using the command
-     ```
-     pip install virtualenv
-     ```
-
-   * The next steps depends if you're using a UNIX system (Mac/Linux) or Windows:
-      * For UNIX operating systems:
-         * Create a virtual env called `venv` in the current directory using the
-           command:
-           ```
-           virtualenv -p python3 venv
-           ```
-         * Activate the virtualenv called `venv` by running:
-           ```
-           source venv/bin/activate
-           ```
-           Your command prompt will change to indicate you're working inside `venv`.
+    ```
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    ```
 
-      * For Windows systems:
-         * Create a virtual env called `venv` in the current directory using the
-           following command:
-           ```
-           virtualenv -p C:/Python36/python.exe venv
-           ```
-           You may need to adjust the `-p` argument depending on where your version
-           of Python is located. Note you'll need Python version 3.5 or higher.
-         * Activate the virtualenv called `venv` by running:
-           ```
-           .\venv\Scripts\activate
-           ```
+    On Windows:
+    ```
+    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+    ```
 
-4. Install the `ricecooker` code in the virtual environment using these commands:
+4. Install the `ricecooker` code and its dependencies:
 
     ```
-    pip install -e .
+    uv sync --group dev
     ```
 
-
 5. Create a branch for local development:
 
     ```
@@ -114,24 +89,23 @@ Here are the steps for setting up `ricecooker` for local development:
    Now you can make your changes locally.
 
 
-6. When you're done making changes, check that your changes pass flake8 linter rules
-   and the `ricecooker` test suite, including testing other Python versions with tox:
+6. When you're done making changes, check that your changes pass linting
+   and the `ricecooker` test suite:
 
-   To run the tests you will need to install the extra depedencies tagged "test"
-
-   ```
-   pip install -e .[test]
-   ```
-
-   Running the tests
+   Run linting:
+    ```
+    uvx prek run --all-files
+    ```
 
+   Run the tests:
     ```
-    flake8 ricecooker tests
-    pytest
-    tox
+    uv run --group test pytest
     ```
 
-   To get `flake8` and `tox`, just `pip install` them into your virtualenv.
+   Run tests across all supported Python versions:
+    ```
+    make test-all
+    ```
 
 
 7. Commit your changes and push your branch to GitHub:
@@ -157,8 +131,7 @@ Before you submit a pull request, check that it meets these guidelines:
 2. If the pull request adds functionality, the docs should be updated. Put
    your new functionality into a function with a docstring, and add the
    feature to the list in `README.md`.
-3. The pull request should work for Python 3.5+. Check
-   [https://travis-ci.org/github/learningequality/ricecooker/pull_requests](https://travis-ci.org/github/learningequality/ricecooker/pull_requests)
+3. The pull request should work for Python 3.9+. Check the GitHub Actions CI
    and make sure that the tests pass for all supported Python versions.
 
 

ISSUE.md

@@ -0,0 +1,60 @@
+---
+issue: 662
+target_branch: main
+repo: learningequality/ricecooker
+updated_at: "2026-03-31T21:48:28Z"
+---
+
+<!---HEADER START-->
+
+<img height="20px" src="https://i.imgur.com/c7hUeb5.jpeg">
+
+❌ **This issue is not open for contribution. Visit <a href="https://learningequality.org/contributing-to-our-open-code-base/" target="_blank">Contributing guidelines</a>** to learn about the contributing process and how to find suitable issues.
+
+<img height="20px" src="https://i.imgur.com/c7hUeb5.jpeg">
+
+<!---HEADER END-->
+
+## Overview
+
+Migrate from pip/tox/setup.py to uv, and replace flake8/black/reorder-python-imports with ruff, following the same approach as learningequality/kolibri#14457.
+
+**Complexity:** Low
+**Target branch:** main
+
+### Context
+
+Kolibri has migrated to uv for Python version management, virtual environments, dependency resolution, and CI. The same migration should be applied across the ecosystem for consistency. Ricecooker already has yamlfmt and actionlint in its pre-commit config.
+
+### The Change
+
+- Convert `setup.py`/`setup.cfg` to `pyproject.toml` with PEP 735 dependency groups
+- Replace custom versioning with setuptools-scm
+- Replace tox with direct uv invocation in CI
+- Replace flake8/black/reorder-python-imports with ruff
+- Replace pre-commit with prek
+- Update CI workflows to use `astral-sh/setup-uv` with `enable-cache: true` and `cache-python: true` (this may need to be turned off for Windows workflows - can check on CI)
+- Configure `exclude-newer = "7 days"` with `exclude-newer-package` exemption for `le-utils` in `[tool.uv]` for supply chain safety
+- Add `uv-lock` pre-commit hook (from `astral-sh/uv-pre-commit`) to keep `uv.lock` in sync
+- Update developer documentation
+
+### Acceptance Criteria
+
+- [ ] `pyproject.toml` replaces `setup.py`/`setup.cfg` as the single source of project metadata and configuration
+- [ ] Versioning handled by setuptools-scm
+- [ ] `tox.ini` removed; CI uses uv directly
+- [ ] Linting and formatting handled by ruff (replacing black, flake8, reorder-python-imports)
+- [ ] Pre-commit uses prek
+- [ ] CI workflows use `astral-sh/setup-uv@v7`
+- [ ] `exclude-newer` cooldown configured in pyproject.toml
+- [ ] `uv-lock` pre-commit hook added to `.pre-commit-config.yaml`
+- [ ] All existing tests pass
+- [ ] Developer documentation updated
+
+### References
+
+- https://github.com/learningequality/kolibri/pull/14457 — Kolibri uv migration (reference implementation)
+
+## AI usage
+
+This issue was drafted by Claude Code based on the Kolibri uv migration work.