build(uv): Lean on uv for all tasks within Makefile (#316)

Author: schloerke

.github/workflows/ci.yaml

@@ -4,19 +4,14 @@ on:
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
-env:
-  UV_SYSTEM_PYTHON: true
 jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: 3.x
-          check-latest: true
-          cache: 'pip'
-      - run: make deps
+      - uses: astral-sh/setup-uv@v3
+      - run: uv python install
+      - run: make dev
       - run: make lint
       - run: make fmt
 
@@ -26,21 +21,18 @@ jobs:
       fail-fast: false
       matrix:
         python-version:
-          - '3.8'
-          - '3.9'
-          - '3.10'
-          - '3.11'
-          - '3.12'
+          - "3.8"
+          - "3.9"
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
     steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-python@v5
-      with:
-        python-version: ${{ matrix.python-version }}
-        check-latest: true
-        cache: 'pip'
-    - run: make deps
-    - run: make dev
-    - run: make test
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv python install ${{ matrix.python-version }}
+      - run: make dev
+      - run: make test
 
   integration-test:
     runs-on: ubuntu-latest
@@ -68,18 +60,20 @@ jobs:
           - 2022.12.0
           - 2022.11.0
     steps:
-    - uses: actions/checkout@v4
-    - uses: docker/setup-buildx-action@v3
-    - name: Write Posit Connect license to disk
-      run: echo "$CONNECT_LICENSE" > ./integration/license.lic
-      env:
-        CONNECT_LICENSE: ${{ secrets.CONNECT_LICENSE }}
-    - run: make -C ./integration ${{ matrix.CONNECT_VERSION }}
-    - uses: actions/upload-artifact@v4
-      if: always()
-      with:
-        name: ${{ matrix.CONNECT_VERSION }} - Integration Test Report
-        path: integration/reports/*.xml
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - name: Write Posit Connect license to disk
+        run: echo "$CONNECT_LICENSE" > ./integration/license.lic
+        env:
+          CONNECT_LICENSE: ${{ secrets.CONNECT_LICENSE }}
+      - uses: astral-sh/setup-uv@v3
+      - run: uv python install
+      - run: make -C ./integration ${{ matrix.CONNECT_VERSION }}
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: ${{ matrix.CONNECT_VERSION }} - Integration Test Report
+          path: integration/reports/*.xml
 
   integration-test-report:
     needs: integration-test
@@ -99,15 +93,11 @@ jobs:
           files: "artifacts/**/*.xml"
           report_individual_runs: true
 
-
   build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: 3.x
-          check-latest: true
-          cache: 'pip'
-      - run: make deps
+      - uses: astral-sh/setup-uv@v3
+      - run: uv python install
+      - run: make dev
       - run: make build

.github/workflows/coverage.yaml

@@ -4,24 +4,18 @@ on:
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
-env:
-  UV_SYSTEM_PYTHON: true
 jobs:
   cov:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: 3.x
-          check-latest: true
-          cache: 'pip'
-      - run: make deps
+      - uses: astral-sh/setup-uv@v3
+      - run: uv python install
       - run: make dev
       - run: make test
       - run: make cov-xml
       - if: ${{ ! github.event.pull_request.head.repo.fork }}
         uses: orgoro/[email protected]
         with:
-            coverageFile: coverage.xml
-            token: ${{ secrets.GITHUB_TOKEN }}
+          coverageFile: coverage.xml
+          token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yaml

@@ -3,25 +3,19 @@ on:
   push:
     tags:
       - "v*.*.*"
-env:
-  UV_SYSTEM_PYTHON: true
 jobs:
   default:
     runs-on: ubuntu-latest
     permissions:
       id-token: write
     steps:
-    - uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-    - uses: actions/setup-python@v5
-      with:
-        python-version: 3.x
-        check-latest: true
-        cache: 'pip'
-    - uses: actions/setup-node@v4
-    - run: make deps
-    - run: make build
-    - run: make install
-    - id: release
-      uses: pypa/gh-action-pypi-publish@release/v1
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v3
+      - run: uv python install
+      - uses: actions/setup-node@v4
+      - run: make build
+      - run: make install
+      - id: release
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/site.yaml

@@ -6,9 +6,6 @@ on:
       - "v*.*.*"
   pull_request:
 
-env:
-  UV_SYSTEM_PYTHON: true
-
 permissions:
   id-token: write
   pages: write
@@ -25,14 +22,9 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: actions/setup-python@v5
-        with:
-          python-version: 3.x
-          check-latest: true
-          cache: 'pip'
-      - run: make deps
-      - run: make build
-      - run: make install
+      - uses: astral-sh/setup-uv@v3
+      - run: uv python install
+      - run: make build install
       - uses: quarto-dev/quarto-actions/setup@v2
       - run: make docs
       - uses: actions/configure-pages@v3
@@ -48,14 +40,10 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: actions/setup-python@v5
-        with:
-          python-version: 3.x
-          check-latest: true
-          cache: 'pip'
+      - uses: astral-sh/setup-uv@v3
+      - run: uv python install
       - uses: actions/setup-node@v4
       - uses: quarto-dev/quarto-actions/setup@v2
-      - run: make deps
       - run: make dev
       - run: make docs
       - id: preview

.gitignore

@@ -27,6 +27,7 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
+uv.lock
 
 # PyInstaller
 #  Usually these files are written by a python script from a template
@@ -166,3 +167,5 @@ cython_debug/
 
 # Ruff
 .ruff_cache/
+
+/.luarc.json

CONTRIBUTING.md

@@ -8,7 +8,7 @@ The `posit-sdk` is a software development kit (SDK) for working with Posit's pro
 
 Before contributing to the `posit-sdk`, ensure that the following prerequisites are met:
 
-- Python >=3.8
+- Python >=3.9
 
 > [!INFO]
 > We require using virtual environments to maintain a clean and consistent development environment.
@@ -17,7 +17,7 @@ Before contributing to the `posit-sdk`, ensure that the following prerequisites
 ## Instructions
 
 > [!WARNING]
-> Executing `make` will install third-party packages in your Python environment. Please review the [`Makefile`](./Makefile) to verify behavior before executing any commands.
+> Executing `make` will install third-party packages in your `.venv` virtual Python environment. Please review the [`Makefile`](./Makefile) to verify behavior before executing any commands.
 
 1. Fork the repository and open it in your development environment.
 2. Activate your Python environment (e.g., `source .venv/bin/activate`)
@@ -33,7 +33,7 @@ Use the default make target to execute the full build pipeline. For details on s
 
 ## Style Guide
 
-We use [Ruff](https://docs.astral.sh/ruff/) for linting and code formatting. Run `make deps` to install it.
+We use [Ruff](https://docs.astral.sh/ruff/) for linting and code formatting.
 
 All proposed changes must successfully pass the `make lint` rules prior to merging.
 

Dockerfile

@@ -1,14 +1,13 @@
 FROM python:3
 
-ENV UV_SYSTEM_PYTHON=true
-
 RUN apt-get update && apt-get install -y make
 
 WORKDIR /sdk
 
-COPY Makefile pyproject.toml requirements.txt requirements-dev.txt vars.mk ./
+COPY Makefile pyproject.toml vars.mk uv.lock ./
 
-RUN --mount=type=cache,mode=0755,target=/root/.cache/pip make deps
+# Run before `COPY src src` to cache dependencies for faster iterative builds
+RUN --mount=type=cache,mode=0755,target=/root/.cache/pip make docker-deps
 
 COPY .git .git
 COPY src src

Makefile

@@ -2,11 +2,11 @@ include vars.mk
 
 .DEFAULT_GOAL := all
 
-.PHONY: build clean cov default deps dev docs ensure-uv fmt fix install it lint test uninstall version help
+.PHONY: build clean cov default dev docker-deps docs ensure-uv fmt fix install it lint test uninstall version help
 
-all: deps dev test lint build
+all: dev test lint build
 
-build:
+build: dev
 	$(UV) build
 
 clean:
@@ -19,62 +19,73 @@ clean:
 	find . -name "__pycache__" -exec rm -rf {} +
 	find . -type d -empty -delete
 
-cov:
-	$(PYTHON) -m coverage report
+cov: dev
+	$(UV) run coverage report
 
-cov-html:
-	$(PYTHON) -m coverage html
+cov-html: dev
+	$(UV) run coverage html
 	open htmlcov/index.html
 
-cov-xml:
-	$(PYTHON) -m coverage xml
-
-deps: ensure-uv
-	$(UV) pip install --upgrade pip setuptools wheel -r requirements.txt -r requirements-dev.txt
+cov-xml: dev
+	$(UV) run coverage xml
 
 dev: ensure-uv
 	$(UV) pip install -e .
 
-docs:
+docker-deps: ensure-uv
+	# Sync given the `uv.lock` file
+	# --frozen : assert that the lock file exists
+	# --no-install-project : do not install the project itself, but install its dependencies
+	$(UV) sync --frozen --no-install-project
+
+docs: ensure-uv
 	$(MAKE) -C ./docs
 
+$(VIRTUAL_ENV):
+	$(UV) venv $(VIRTUAL_ENV)
 ensure-uv:
 	@if ! command -v $(UV) >/dev/null; then \
-		$(PYTHON) -m ensurepip && $(PYTHON) -m pip install uv; \
+		$(PYTHON) -m ensurepip && $(PYTHON) -m pip install "uv >= 0.4.27"; \
 	fi
+	@# Install virtual environment (before calling `uv pip install ...`)
+	@$(MAKE) $(VIRTUAL_ENV) 1>/dev/null
+	@# Be sure recent uv is installed
+	@$(UV) pip install "uv >= 0.4.27" --quiet
 
-fmt:
-	$(PYTHON) -m ruff check --fix
-	$(PYTHON) -m ruff format
+fmt: dev
+	$(UV) run ruff check --fix
+	$(UV) run ruff format
 
-install: ensure-uv
+install: build
 	$(UV) pip install dist/*.whl
 
-it:
+$(UV_LOCK): dev
+	$(UV) lock
+it: $(UV_LOCK)
 	$(MAKE) -C ./integration
 
-lint:
-	$(PYTHON) -m pyright
-	$(PYTHON) -m ruff check
+lint: dev
+	$(UV) run pyright
+	$(UV) run ruff check
 
-test:
-	$(PYTHON) -m coverage run --source=src -m pytest tests
+test: dev
+	$(UV) run coverage run --source=src -m pytest tests
 
 uninstall: ensure-uv
 	$(UV) pip uninstall $(PROJECT_NAME)
 
 version:
-	@$(PYTHON) -m setuptools_scm
+	@$(MAKE) ensure-uv &>/dev/null
+	@$(UV) run --quiet --with "setuptools_scm" python -m setuptools_scm
 
 help:
 	@echo "Makefile Targets"
-	@echo "  all            Run deps, dev, test, lint, and build"
+	@echo "  all            Run dev, test, lint, and build"
 	@echo "  build          Build the project"
 	@echo "  clean          Clean up project artifacts"
 	@echo "  cov            Generate a coverage report"
 	@echo "  cov-html       Generate an HTML coverage report and open it"
 	@echo "  cov-xml        Generate an XML coverage report"
-	@echo "  deps           Install dependencies"
 	@echo "  dev            Install the project in editable mode"
 	@echo "  docs           Build the documentation"
 	@echo "  ensure-uv      Ensure 'uv' is installed"