chore: manage dependencies with uv (Universal-Commerce-Protocol#126)

Author: drewolson-google

.github/workflows/docs.yml

@@ -57,29 +57,14 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
 
-      - name: Setup Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: 3.13
-
-      - name: Restore pip cache
-        uses: actions/cache@v4
-        with:
-          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements-docs.txt') }}
-          path: ~/.cache/pip
-          restore-keys: |
-            ${{ runner.os }}-pip-
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v7
 
       - name: Install documentation dependencies
-        run: pip install -r requirements-docs.txt
+        run: uv sync
 
       - name: Lint YAML files
-        run: yamllint -c .github/linters/.yamllint.yml .
-
-      - name: Install uv
-        run: |
-          curl -LsSf https://astral.sh/uv/install.sh | sh
-          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+        run: uv run yamllint -c .github/linters/.yamllint.yml .
 
       - name: Check for changed files in spec
         id: spec_files_changed
@@ -102,12 +87,12 @@ jobs:
 
       - name: Build Documentation (PR Check)
         if: github.event_name == 'pull_request'
-        run: mkdocs build --strict
+        run: uv run mkdocs build --strict
 
       - name: Deploy development version from main branch
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         run: |
-          mike deploy --push draft
+          uv run mike deploy --push draft
 
       - name: Deploy release version
         if: startsWith(github.ref, 'refs/heads/release/')
@@ -116,8 +101,8 @@ jobs:
           VERSION_NAME=${GITHUB_REF#refs/heads/release/}
 
           # Deploy this version, tag it as 'latest', and set it as the default site root
-          mike deploy --push --update-aliases $VERSION_NAME latest
-          mike set-default --push latest
+          uv run mike deploy --push --update-aliases $VERSION_NAME latest
+          uv run mike set-default --push latest
 
       - name: Create GitHub Release and Tag
         if: startsWith(github.ref, 'refs/heads/release/')

CONTRIBUTING.md

@@ -190,7 +190,7 @@ You can run many of these checks locally before committing by installing and
 using `pre-commit`:
 
 ```bash
-pip install pre-commit
+uv tool install pre-commit
 pre-commit install
 ```
 
@@ -212,12 +212,12 @@ This will set up pre-commit hooks to run automatically when you `git commit`.
 ### Spec Development
 
 1. Make relevant updates to JSON files in `source/`
-2. Run `python generate_schemas.py` to generate updated files in `spec/`
+2. Run `uv run generate_schemas.py` to generate updated files in `spec/`
 3. Check outputs from step above to ensure deltas are expected. You may need to
    extend `generate_schemas.py` if you are introducing a new generation concept
 
 To validate JSON and YAML files format and references in `spec/`, run
-`python validate_specs.py`.
+`uv run validate_specs.py`.
 
 If you change any JSON schemas in `spec/`, you must regenerate any SDK client
 libraries that depend on them. For example, to regenerate Python Pydantic
@@ -230,25 +230,26 @@ are updated to ensure there are no broken references or stale/missing contents.
 
 ### Documentation Development
 
-1. Ensure dependencies are installed: `pip install -r requirements-docs.txt`
-2. Run the development server: `mkdocs serve --watch spec`
+1. Ensure dependencies are installed: `uv sync`
+2. Run the development server: `uv run mkdocs serve --watch spec`
 3. Open **<http://127.0.0.1:8000>** in your browser
 4. Before submitting a pull request with documentation changes, run
-    `mkdocs build --strict` to ensure there are no warnings or errors. Our CI
+    `uv run mkdocs build --strict` to ensure there are no warnings or errors. Our CI
     build uses this command and will fail if warnings are present (e.g.,
     broken links).
 
-### Using a virtual environment (Recommended)
+### Using uv (Recommended)
 
-To avoid polluting your global environment, use a virtual environment. Prefix
-the virtual environment name with a `.` so the versioning control systems don't
-track pip install files:
+This project uses `uv` to manage dependencies and virtual environments. To set up
+your development environment:
 
 ```bash
-$ sudo apt-get install virtualenv python3-venv
-$ virtualenv .ucp # or python3 -m venv .ucp
-$ source .ucp/bin/activate
-(.ucp) $ pip install -r requirements-docs.txt
-(.ucp) $ mkdocs serve --watch spec
-(.ucp) $ deactivate # when done
+# Install dependencies and set up the virtual environment
+$ uv sync
+
+# Run development commands using 'uv run'
+$ uv run mkdocs serve --watch spec
 ```
+
+`uv` will automatically manage a virtual environment in the `.venv` directory.
+You don't need to manually activate it if you use `uv run`.

generate_schemas.py

@@ -23,7 +23,7 @@
 Pass 3: Generates Embedded Protocol OpenRPC spec by aggregating methods
 from source/services/shopping/embedded.json and extension schemas.
 
-Usage: python generate_schemas.py
+Usage: uv run generate_schemas.py
 """
 
 import copy

pyproject.toml

@@ -4,9 +4,6 @@ version = "2026.01.23"
 description = "Universal Commerce Protocol"
 readme = "README.md"
 requires-python = ">=3.10"
-dependencies = [
-    "datamodel-code-generator[http]>=0.50.0",
-]
 
 [tool.ruff]
 line-length = 80
@@ -15,6 +12,22 @@ indent-width = 2
 [tool.setuptools]
 packages = []
 
+[dependency-groups]
+dev = [
+    "datamodel-code-generator[http]>=0.50.0",
+    "mike==2.1.3",
+    "mkdocs-llmstxt==0.5.0",
+    "mkdocs-macros-plugin==1.4.0",
+    "mkdocs-material[imaging]>=9.0.0",
+    "mkdocs-redirects==1.2.2",
+    "mkdocs-site-urls==0.3.1",
+    "yamllint==1.35.1",
+]
+
+[[tool.uv.index]]
+url = "https://pypi.org/simple"
+default = true
+
 [tool.ruff.format]
 quote-style = "double"
 indent-style = "space"

requirements-docs.txt

@@ -43,7 +43,7 @@ echo "Generating Pydantic models from $SCHEMA_DIR to temporary dir $OUTPUT_DIR..
 # Run generation using uv
 uv run \
 	--link-mode=copy \
-	--extra-index-url https://pypi.org/simple python \
+	python \
 	-m datamodel_code_generator \
 	--input "$SCHEMA_DIR" \
 	--input-file-type jsonschema \