Skip to content

Commit 944b922

Browse files
gavin-aguiargavin-aguiar
committed
Migrating to uv
1 parent 3533587 commit 944b922

File tree

342 files changed

+15513
-8508
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

342 files changed

+15513
-8508
lines changed

‎.claude/settings.local.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"WebFetch(domain:github.com)",
5+
"WebFetch(domain:raw.githubusercontent.com)",
6+
"Bash(poe --help:*)",
7+
"Bash(ruff:*)",
8+
"Bash(poe --list:*)",
9+
"Bash(poe)",
10+
"Bash(poe lint --help:*)"
11+
]
12+
}
13+
}

‎.github/workflows/uv-ci.yml‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
###########################
3+
# UV-based CI Workflow #
4+
###########################
5+
6+
name: UV CI - Lint, Format, Type Check, and Test
7+
8+
on: [push, pull_request, workflow_dispatch]
9+
10+
jobs:
11+
lint-and-test:
12+
name: Lint, Format, Type Check, and Test
13+
runs-on: ${{ matrix.os }}
14+
strategy:
15+
fail-fast: false
16+
matrix:
17+
os: [ubuntu-latest, windows-latest, macos-latest]
18+
python-version: ["3.10", "3.11", "3.12", "3.13"]
19+
20+
steps:
21+
- name: Checkout Code
22+
uses: actions/checkout@v4
23+
24+
- name: Install UV
25+
uses: astral-sh/setup-uv@v5
26+
with:
27+
enable-cache: true
28+
cache-dependency-glob: "workers/pyproject.toml"
29+
30+
- name: Set up Python ${{ matrix.python-version }}
31+
run: uv python install ${{ matrix.python-version }}
32+
33+
- name: Install Dependencies
34+
working-directory: workers
35+
run: uv sync --all-extras --dev
36+
37+
- name: Run Ruff Format Check
38+
working-directory: workers
39+
run: uv run poe fmt --check
40+
if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
41+
42+
- name: Run Ruff Linter
43+
working-directory: workers
44+
run: uv run poe lint
45+
46+
- name: Run Type Checking
47+
working-directory: workers
48+
run: uv run poe mypy
49+
continue-on-error: true # Type checking might have issues initially
50+
51+
- name: Build Protos
52+
working-directory: workers
53+
run: uv run poe build-protos
54+
55+
- name: Run Tests
56+
working-directory: workers
57+
run: uv run poe test-cov
58+
env:
59+
PYTHONPATH: ${{ github.workspace }}/workers
60+
61+
- name: Upload Coverage Reports
62+
if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
63+
uses: codecov/codecov-action@v4
64+
with:
65+
file: ./workers/htmlcov/index.html
66+
flags: unittests
67+
name: codecov-umbrella
68+
fail_ci_if_error: false
69+
70+
pre-commit:
71+
name: Pre-commit Hooks
72+
runs-on: ubuntu-latest
73+
74+
steps:
75+
- name: Checkout Code
76+
uses: actions/checkout@v4
77+
78+
- name: Install UV
79+
uses: astral-sh/setup-uv@v5
80+
with:
81+
enable-cache: true
82+
83+
- name: Set up Python
84+
run: uv python install 3.13
85+
86+
- name: Install Dependencies
87+
working-directory: workers
88+
run: uv sync --all-extras --dev
89+
90+
- name: Run Pre-commit
91+
working-directory: workers
92+
run: uv run poe pre-commit-run

‎.pre-commit-config.yaml‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
11
repos:
2-
- repo: https://github.com/psf/black
3-
rev: 24.1.1
2+
# Ruff - replaces black, isort, and flake8 with a single fast tool
3+
- repo: https://github.com/astral-sh/ruff-pre-commit
4+
rev: v0.11.8
45
hooks:
5-
- id: black
6-
language_version: python3
7-
- repo: https://github.com/PyCQA/isort
8-
rev: 5.12.0
6+
# Run the linter
7+
- id: ruff
8+
args: [--fix]
9+
# Run the formatter
10+
- id: ruff-format
11+
12+
# UV lockfile maintenance
13+
- repo: https://github.com/astral-sh/uv-pre-commit
14+
rev: 0.9.18
915
hooks:
10-
- id: isort
11-
- repo: https://github.com/PyCQA/flake8
12-
rev: 7.0.0
13-
hooks:
14-
- id: flake8
16+
- id: uv-lock

‎DEVELOPMENT.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
# Development Guide
2+
3+
This guide explains how to set up your development environment and use the modernized tooling for the Azure Functions Python Worker.
4+
5+
## Quick Start
6+
7+
### Prerequisites
8+
9+
- [uv](https://docs.astral.sh/uv/) - Fast Python package installer and resolver
10+
11+
### Setup
12+
13+
Run the development setup script:
14+
15+
```bash
16+
./devsetup.sh
17+
```
18+
19+
This script will:
20+
1. Install Python versions 3.10, 3.11, 3.12, and 3.13
21+
2. Create a virtual environment (defaults to Python 3.13)
22+
3. Install all dependencies
23+
4. Build protocol buffers
24+
5. Install pre-commit hooks
25+
26+
### Manual Setup
27+
28+
If you prefer manual setup or need to customize the Python version:
29+
30+
```bash
31+
# Install Python versions
32+
uv python install 3.10 3.11 3.12 3.13
33+
34+
# Create virtual environment with specific Python version
35+
PYTHON_VERSION=3.12 uv venv --python 3.12
36+
37+
# Install dependencies (from workers directory)
38+
cd workers
39+
uv sync --all-extras --dev
40+
41+
# Build protos
42+
uv run invoke -c tests/test_setup build-protos
43+
44+
# Install pre-commit hooks
45+
uv run poe pre-commit-install
46+
```
47+
48+
## Development Workflow
49+
50+
### Available Tasks
51+
52+
All tasks are defined in `workers/pyproject.toml` and can be run using `uv run poe <task>`:
53+
54+
#### Code Quality
55+
56+
```bash
57+
# Format code with ruff
58+
uv run poe fmt
59+
60+
# Lint code (check for issues)
61+
uv run poe lint
62+
63+
# Lint and auto-fix issues
64+
uv run poe lint-fix
65+
66+
# Type check with mypy
67+
uv run poe mypy
68+
69+
# Run all checks (format, lint, mypy, test)
70+
uv run poe check
71+
```
72+
73+
#### Testing
74+
75+
```bash
76+
# Run tests
77+
uv run poe test
78+
79+
# Run tests with coverage report
80+
uv run poe test-cov
81+
82+
# Run tests in parallel
83+
uv run poe test-parallel
84+
```
85+
86+
#### Development Setup
87+
88+
```bash
89+
# Build protocol buffers
90+
uv run poe build-protos
91+
92+
# Setup webhost
93+
uv run poe setup-webhost
94+
95+
# Setup extensions
96+
uv run poe setup-extensions
97+
98+
# Setup all (protos + webhost + extensions)
99+
uv run poe setup-all
100+
```
101+
102+
#### Pre-commit
103+
104+
```bash
105+
# Install pre-commit hooks
106+
uv run poe pre-commit-install
107+
108+
# Run pre-commit on all files
109+
uv run poe pre-commit-run
110+
```
111+
112+
### Traditional Commands (Still Supported)
113+
114+
If you prefer using traditional commands directly:
115+
116+
```bash
117+
# Activate virtual environment first
118+
source .venv/bin/activate # Linux/Mac
119+
.venv\Scripts\activate # Windows
120+
121+
# Then run commands directly
122+
pytest
123+
ruff check .
124+
ruff format .
125+
mypy azure_functions_worker
126+
```
127+
128+
## Tooling
129+
130+
### Ruff
131+
132+
We use [Ruff](https://docs.astral.sh/ruff/) as a single replacement for:
133+
- **black** (formatting)
134+
- **isort** (import sorting)
135+
- **flake8** (linting)
136+
137+
Ruff is significantly faster and provides a unified configuration.
138+
139+
**Configuration:** See `[tool.ruff]` section in `workers/pyproject.toml`
140+
141+
### UV
142+
143+
We use [uv](https://docs.astral.sh/uv/) for:
144+
- Python version management
145+
- Virtual environment creation
146+
- Dependency installation and resolution
147+
- Task execution
148+
149+
**Benefits:**
150+
- Faster than pip (10-100x in many cases)
151+
- Better dependency resolution
152+
- Built-in Python version management
153+
- Reproducible builds with lockfiles
154+
155+
### Poethepoet
156+
157+
We use [poethepoet](https://poethepoet.natn.io/) for task automation.
158+
159+
**Benefits:**
160+
- Cross-platform task definitions
161+
- Integration with uv
162+
- Simple TOML configuration
163+
- Task dependencies and composition
164+
165+
## Pre-commit Hooks
166+
167+
Pre-commit hooks automatically run before each commit to ensure code quality:
168+
169+
1. **Ruff linting** - Auto-fixes common issues
170+
2. **Ruff formatting** - Formats code consistently
171+
3. **UV lockfile** - Keeps dependency lockfile updated
172+
173+
To bypass hooks (not recommended):
174+
```bash
175+
git commit --no-verify
176+
```
177+
178+
## Migration Notes
179+
180+
### From Old Tooling
181+
182+
| Old | New | Notes |
183+
|-----|-----|-------|
184+
| `black .` | `uv run poe fmt` | Ruff format instead of black |
185+
| `isort .` | `uv run poe fmt` | Ruff handles import sorting |
186+
| `flake8` | `uv run poe lint` | Ruff check instead of flake8 |
187+
| `pip install -e .[dev]` | `uv sync --all-extras --dev` | UV for dependency management |
188+
| `pytest` | `uv run poe test` | Can still use pytest directly |
189+
| `invoke ...` | `uv run poe build-protos` | Invoke still used for build tasks |
190+
191+
### Configuration Files
192+
193+
- **Ruff configuration:** `workers/pyproject.toml` under `[tool.ruff]`
194+
- **Task definitions:** `workers/pyproject.toml` under `[tool.poe.tasks]`
195+
- **Pre-commit hooks:** `.pre-commit-config.yaml` in root
196+
- **Legacy flake8 config:** `.github/linters/tox.ini` (for CI compatibility)
197+
198+
## Continuous Integration
199+
200+
The GitHub Actions workflows will continue to work with both old and new tooling during the transition period. The new ruff-based workflow is faster and provides better error messages.
201+
202+
## Troubleshooting
203+
204+
### UV not found
205+
```bash
206+
curl -LsSf https://astral.sh/uv/install.sh | sh
207+
# Restart your shell or run: source ~/.bashrc (or ~/.zshrc)
208+
```
209+
210+
### Python version not available
211+
```bash
212+
uv python install 3.13 # or any other version
213+
```
214+
215+
### Dependency issues
216+
```bash
217+
cd workers
218+
uv sync --all-extras --dev --refresh
219+
```
220+
221+
### Pre-commit hook failures
222+
```bash
223+
uv run poe pre-commit-run # Run all hooks manually
224+
```
225+
226+
## Resources
227+
228+
- [UV Documentation](https://docs.astral.sh/uv/)
229+
- [Ruff Documentation](https://docs.astral.sh/ruff/)
230+
- [Poethepoet Documentation](https://poethepoet.natn.io/)
231+
- [Pre-commit Documentation](https://pre-commit.com/)

0 commit comments

Comments
 (0)