move

2026-06-18 22:06:40 -05:00
parent 6c5fda9c3a
commit e78383be1f
24 changed files with 0 additions and 0 deletions
@@ -0,0 +1,251 @@
+# uv Project Layout and Dependency Management
+
+Source: https://docs.astral.sh/uv/guides/projects/ | https://docs.astral.sh/uv/concepts/projects/layout/ | https://docs.astral.sh/uv/guides/integration/docker/
+
+---
+
+## Core Files
+
+| File | Purpose | Commit? |
+|------|---------|---------|
+| `pyproject.toml` | Project metadata, deps, tool config | Yes |
+| `uv.lock` | Exact resolved versions, cross-platform | **Yes** |
+| `.python-version` | Default Python version for the project | Yes |
+| `.venv/` | Local virtual environment | No (`.gitignore`) |
+
+**`uv.lock` must be committed.** It is the source of truth for reproducible installs in CI and Docker. Never edit it by hand.
+
+---
+
+## Essential Commands
+
+```bash
+# Initialize a new project (app, not library)
+uv init --app
+
+# Initialize a library (installable package with src layout)
+uv init --lib
+
+# Add a runtime dependency
+uv add fastapi[standard]
+
+# Add multiple dependencies at once
+uv add uvicorn[standard] pydantic-settings
+
+# Add dev-only dependency
+uv add --dev pytest httpx pytest-asyncio ruff mypy
+
+# Remove a dependency
+uv remove requests
+
+# Upgrade a specific package (keeps rest of lockfile intact)
+uv lock --upgrade-package fastapi
+
+# Upgrade all packages
+uv lock --upgrade
+
+# Sync env to lockfile (install/remove as needed)
+uv sync
+
+# Sync without dev deps (e.g., in CI or Docker)
+uv sync --no-dev
+
+# Sync and assert lockfile is up-to-date (for CI / Docker)
+uv sync --locked
+
+# Run a command in the project environment
+uv run pytest
+uv run uvicorn my_app.main:app --reload
+
+# Run a one-off command without installing anything permanently
+uv run --with httpx python -c "import httpx; print(httpx.__version__)"
+```
+
+---
+
+## pyproject.toml Reference
+
+```toml
+[project]
+name = "my-app"
+version = "0.1.0"
+description = "Production FastAPI service"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+readme = "README.md"
+
+dependencies = [
+    "fastapi[standard]>=0.115",
+    "uvicorn[standard]>=0.34",
+    "pydantic-settings>=2.0",
+]
+
+[project.scripts]
+# Creates `my-app` CLI entry point when installed
+my-app = "my_app.main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/my_app"]
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "httpx>=0.27",     # needed for FastAPI TestClient
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+strict-markers = true
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "S"]
+
+[tool.mypy]
+strict = true
+```
+
+---
+
+## src Layout with uv
+
+Use `uv init --lib` or set up manually:
+
+```
+my-app/
+├── pyproject.toml
+├── uv.lock
+├── .python-version    # e.g., "3.12"
+├── .env.example
+├── README.md
+├── src/
+│   └── my_app/
+│       └── __init__.py
+└── tests/
+    └── conftest.py
+```
+
+The `src/` layout prevents the local directory from shadowing the installed package, which would otherwise cause silent test failures when testing the installed version.
+
+**hatchling config for src layout:**
+
+```toml
+[tool.hatch.build.targets.wheel]
+packages = ["src/my_app"]
+```
+
+---
+
+## Migration from pip / requirements.txt
+
+```bash
+# 1. Initialize uv in an existing project
+uv init --no-workspace   # if already has pyproject.toml, skip this
+
+# 2. Import from requirements.txt
+uv add -r requirements.txt
+
+# 3. Import dev requirements
+uv add --dev -r requirements-dev.txt
+
+# 4. Verify lockfile was created
+cat uv.lock | head -20
+
+# 5. Clean up old files
+rm requirements.txt requirements-dev.txt setup.py setup.cfg Pipfile Pipfile.lock
+
+# 6. Add .venv to .gitignore
+echo ".venv/" >> .gitignore
+```
+
+---
+
+## uv in Docker
+
+The canonical pattern uses `--mount=type=cache` for fast rebuilds and `--no-install-project` for layer separation:
+
+```dockerfile
+# Copy uv binary (pin the version)
+COPY --from=ghcr.io/astral-sh/uv:0.5.27 /uv /uvx /bin/
+
+WORKDIR /app
+
+# Layer 1: install dependencies (changes rarely → cached aggressively)
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --locked --no-install-project --no-editable
+
+# Layer 2: copy source and install project (changes frequently)
+COPY . /app
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --locked --no-editable
+```
+
+**Key flags:**
+
+| Flag | Effect |
+|------|--------|
+| `--locked` | Fail if `uv.lock` is out of date with `pyproject.toml` |
+| `--no-install-project` | Install deps but not the project itself (layer separation) |
+| `--no-editable` | Install in non-editable mode (copy code into `.venv`, not symlink) |
+| `--no-dev` | Skip dev dependencies (use in production images) |
+| `--compile-bytecode` | Pre-compile `.pyc` files (faster startup, larger image) |
+
+**After syncing, activate the venv via PATH (not `uv run`) in production:**
+
+```dockerfile
+ENV PATH="/app/.venv/bin:$PATH"
+CMD ["uvicorn", "my_app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+Using `CMD ["uv", "run", "uvicorn", ...]` in production is fine but adds a small overhead and requires uv to be present in the final image.
+
+---
+
+## CI/CD with uv
+
+```yaml
+# GitHub Actions example
+- name: Install uv
+  uses: astral-sh/setup-uv@v4
+  with:
+    version: "0.5.27"   # pin for reproducibility
+
+- name: Sync dependencies
+  run: uv sync --locked
+
+- name: Run tests
+  run: uv run pytest --tb=short
+
+- name: Lint
+  run: uv run ruff check .
+
+- name: Type check
+  run: uv run mypy src/
+```
+
+---
+
+## .gitignore Entries for uv Projects
+
+```
+.venv/
+__pycache__/
+*.pyc
+.env
+dist/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+```
+
+**Do NOT ignore `uv.lock`** — it must be committed.