Development¶

Setting Up uv¶

This project is set up to use uv to manage Python and dependencies. First, be sure you have uv installed.

Then fork the technophile-musicfan/python-gazelle repo (having your own fork will make it easier to contribute) and clone it.

Basic Developer Workflows¶

The Makefile simply offers shortcuts to uv commands for developer convenience. (For clarity, GitHub Actions don’t use the Makefile and just call uv directly.)

# First, install all dependencies and set up your virtual environment.
# This simply runs `uv sync --all-extras` to install all packages,
# including dev dependencies and optional dependencies.
make install

# Run uv sync, lint, and test:
make

# Build wheel:
make build

# Linting (auto-fixes formatting and lint issues):
make lint

# Linting in check-only mode, matching CI (fails on issues, does not modify files):
make lint-check

# Run tests:
make test

# Delete all the build artifacts:
make clean

# Upgrade dependencies to compatible versions:
make upgrade

# To run tests by hand:
uv run pytest   # all tests
uv run pytest -s src/module/some_file.py  # one test, showing outputs

# Build and install current dev executables, to let you use your dev copies
# as local tools:
uv tool install --editable .

# Dependency management directly with uv:
# Add a new dependency:
uv add package_name
# Add a development dependency:
uv add --dev package_name
# Update to latest compatible versions (including dependencies on git repos):
uv sync --upgrade
# Update a specific package:
uv lock --upgrade-package package_name
# Update dependencies on a package:
uv add package_name@latest

# Run a shell within the Python environment:
uv venv
source .venv/bin/activate

See uv docs for details.

IDE setup¶

If you use VSCode or a fork like Cursor or Windsurf, you can install the following extensions:

Python
Based Pyright for type checking. Note that this extension works with non-Microsoft VSCode forks like Cursor.

Supply Chain Hardening¶

Dependencies are an attack surface. Before adding or upgrading any dependency, follow supply-chain-hardening, a concise cross-ecosystem guide on installing dependencies safely. Its key defaults:

Cool-off period: Don't install or upgrade to a release less than 14 days old (absent a documented exception)—most malicious publishes are caught within days. For uv, set UV_EXCLUDE_NEWER to a cutoff date a couple weeks back (uv takes a date, not a duration); this project's CI workflows set it automatically.
Vet before adding: Confirm the package is actually needed and its name is spelled correctly (typosquats are common), and prefer a little first-party code over a new dependency.
Pin, lock, and audit: Commit your uv.lock, pin GitHub Actions to a commit SHA or immutable tag, and run a vulnerability audit (e.g. pip-audit) after changes.

Documentation¶

This file was built with simple-modern-uv.