Contributing¶

Development setup¶

Pygwire uses uv as its package manager.

git clone https://github.com/DHUKK/pygwire.git
cd pygwire
uv sync

Running tests¶

# Unit + integration tests
uv run pytest tests/unit/ tests/integration/ -v

# Or use the Makefile
make test

Proxy functional tests¶

These run against a real PostgreSQL instance through a transparent protocol proxy. Requires Docker.

# Start PostgreSQL and proxy
docker compose -f tests/infrastructure/docker-compose.yml up -d

# Run functional tests
uv run pytest tests/proxy_functional/ -v

# Stop services
docker compose -f tests/infrastructure/docker-compose.yml down -v

Test against a specific PostgreSQL version (13 through 18):

POSTGRES_VERSION=15 docker compose -f tests/infrastructure/docker-compose.yml up -d

Code quality¶

# Lint + type check
make check

# Auto-format
make format

# Or individually
uv run ruff check src/ tests/
uv run ruff format src/ tests/
uv run mypy src/

Pull request guidelines¶

Run make check and make test before submitting.
Add tests for new functionality.
Follow existing code patterns and naming conventions.
Keep PRs focused. One feature or fix per PR.

Project conventions¶

PostgreSQL naming. "backend" = server, "frontend" = client.
Private modules. Message implementations live in _*.py files. The public API is pygwire.messages.
Sans-I/O. The core library must not perform any I/O operations.
Zero-copy. Use memoryview for buffer slicing in hot paths.