Development Setup

This guide covers setting up a local development environment for gamesheet-sdk-py.

1. Prerequisites

  • Python 3.11, 3.12, 3.13, or 3.14

  • Git

  • Modern Linux, macOS, or Windows system

2. Initial Setup

2.1. Clone and Create Environment

git clone https://github.com/bdperkin/gamesheet-sdk-py.git
cd gamesheet-sdk-py

# Create isolated virtual environment
uv venv .venv
source .venv/bin/activate  # Linux/macOS
# or: .venv\Scripts\activate  # Windows

2.2. Install Dependencies

# Install everything (recommended for full development)
uv sync --all-extras

# Or install only what you need:
uv sync --extra dev --extra pytest --extra docs  # dev tools + tests + docs
uv sync --extra dev --extra pytest        # minimal: dev tools + tests only

2.3. Install Playwright Browsers

uv run playwright install chromium

2.4. Install Pre-commit Hooks

# Install commit-msg hook for Conventional Commits enforcement
pre-commit install --hook-type commit-msg

# Install pre-commit hook for code quality checks
pre-commit install

3. Running Tests

# Full test suite
uv run pytest

# Skip slow browser-based tests
uv run pytest -m "not browser"

# With coverage report
uv run pytest --cov

# Single test file
pytest tests/test_smoke.py

# Single test function
pytest tests/test_smoke.py::test_version_is_string

# With verbose output
pytest -v

# Stop on first failure
pytest -x

4. Code Quality

4.1. Pre-commit Hooks

# Run all hooks on all files
pre-commit run --all-files

# Run specific hook
pre-commit run ty --all-files
pre-commit run ruff --all-files

# Update hook versions
pre-commit autoupdate

4.2. Type Checking

# Astral ty
uv run --extra ty ty check

4.3. Linting

# Run all linters via pre-commit
uv run pre-commit run --all-files

# Run code quality and duplicate code checks via pylint (matches CI job)
uv run --extra pylint pylint .
# or use the Makefile shortcut:
make pylint

# Individual linters
uv run --extra semgrep semgrep scan --config auto --error

4.4. Formatting

# Auto-fix with make
make format

# Or run formatters individually via uv
uv run --extra ruff ruff check --fix
uv run --extra ruff ruff format
uv run --extra mdformat mdformat docs/ *.md

4.5. Complexity Gates

# Check code metrics
make metrics

# Or via uv
uv run --extra radon radon cc --show-complexity --average .

5. Documentation

5.1. Building Docs

# Build HTML docs
make docs

# Or via uv
uv run --extra docs sphinx-build -b html docs docs/_build/html

# Build other formats via uv
uv run --extra docs sphinx-build -b epub docs docs/_build/epub
uv run --extra docs sphinx-build -b man docs docs/_build/man
uv run --extra docs sphinx-build -b latex docs docs/_build/latex && make -C docs/_build/latex all-pdf

5.2. Live Preview

# Auto-rebuild on file changes
make docs-serve

# Or via uv
uv run --extra docs sphinx-autobuild docs docs/_build/html

6. Using uv

uv provides fast, isolated dependency management and tool execution:

# Sync all dependencies
uv sync --all-extras

# Run test suite
uv run pytest

# Run type checker
uv run --extra ty ty check

# Run docs build
uv run --extra docs sphinx-build -b html docs docs/_build/html

7. Makefile Shortcuts

# Show all available targets
make help

# Common workflows
make install       # uv sync --extra dev
make install-all   # uv sync --all-extras
make test          # uv run pytest
make test-fast     # uv run pytest -m "not browser"
make test-cov      # uv run pytest --cov
make format        # auto-format Python, YAML, pyproject
make quality       # dead code, docstring, spelling, and language checks
make types         # uv run --extra ty ty check
make checks        # run all pre-commit hooks
make metrics       # radon complexity analysis
make pylint        # uv run --extra pylint pylint .
make docs          # build HTML docs
make docs-serve    # live-reload docs
make docs-lint     # lint documentation files
make clean         # remove build artifacts
make clean-all     # aggressive clean (includes .venv)

8. Committing Changes

All commits must follow Conventional Commits format:

# Good commits
git commit -m "feat: add new command"
git commit -m "fix(auth): handle expired tokens"
git commit -m "docs: update README"
git commit -m "refactor: simplify login flow"

# Bad commits (will be rejected by pre-commit hook)
git commit -m "added stuff"
git commit -m "bug fix"
git commit -m "WIP"

Common types:

  • feat: — New feature

  • fix: — Bug fix

  • docs: — Documentation only

  • refactor: — Code refactoring

  • test: — Test changes

  • chore: — Maintenance tasks

  • ci: — CI/CD changes

  • build: — Build system changes

9. Troubleshooting

9.1. Pre-commit hook failures

If a hook modifies files (e.g., ruff), stage the changes and commit again:

git add -u
git commit -m "your message"

9.2. Playwright browser issues

If Playwright fails to launch Chromium:

# Reinstall browsers
uv run playwright install --force chromium

# Check installation
uv run playwright install --dry-run

9.3. Virtual environment issues

Clean and rebuild virtual environments:

uv venv --clear .venv
uv sync --all-extras

9.4. Coverage failures

If coverage drops below 100%:

# Generate HTML coverage report
pytest --cov --cov-report=html
open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux

10. Next Steps

  • Read Release Process to understand how releases work

  • Check CLAUDE.md for architecture notes and project patterns

  • Browse docs/ for tutorials, how-tos, and reference documentation