Developer setup¶

This guide covers everything needed to develop and test pymqrest locally.

Prerequisites¶

Tool	Version	Purpose
Python	3.12+	Runtime
`uv`	0.10.4	Package and environment management
Docker	Latest	Local MQ containers (integration tests)
`markdownlint`	Latest	Docs validation
`git-cliff`	Latest	Changelog generation (releases only)

Install uv:

python3 -m pip install uv==0.10.4

Required repositories¶

pymqrest depends on two sibling repositories:

Repository	Purpose
pymqrest	This project
vergil-tooling	Canonical project standards (referenced by `AGENTS.md` and git hooks)
mq-rest-admin-dev-environment	Dockerized MQ test infrastructure (local and CI)

Recommended directory layout¶

Clone all three repositories as siblings:

~/dev/
├── mq-rest-admin-python/
├── vergil-tooling/
└── mq-rest-admin-dev-environment/

cd ~/dev
git clone https://github.com/mq-rest-admin-project/mq-rest-admin-python.git
git clone https://github.com/vergil-project/vergil-tooling.git
git clone https://github.com/mq-rest-admin-project/mq-rest-admin-dev-environment.git

Initial setup¶

cd pymqrest

# Install all dependencies including dev group
uv sync --group dev

# The Claude Code hook guard (.claude/hooks/guard.sh) blocks raw
# git/gh commands — use vrg-git / vrg-gh wrappers.

Running validation¶

The full validation suite matches CI hard gates:

vrg-docker-run -- vrg-validate

Individual checks can be run separately:

vrg-docker-run -- vrg-validate --check lint
vrg-docker-run -- vrg-validate --check typecheck
vrg-docker-run -- vrg-validate --check test
vrg-docker-run -- vrg-validate --check audit
vrg-docker-run -- vrg-validate --check common

Running integration tests¶

Integration tests require running MQ containers. Start the containers, seed test objects, then run the tests:

# Start both queue managers
./scripts/dev/mq_start.sh

# Seed deterministic test objects
./scripts/dev/mq_seed.sh

# Run integration tests
MQ_REST_ADMIN_RUN_INTEGRATION=1 uv run pytest -m integration

See local MQ container for full container configuration, credentials, gateway routing, and troubleshooting.

CI pipeline overview¶

CI runs on every pull request and enforces the same gates as local validation. The pipeline includes:

Unit tests on Python 3.12, 3.13, and 3.14
Integration tests against real MQ queue managers via the shared mq-rest-admin-project/mq-rest-admin-dev-environment/.github/actions/setup-mq action
Standards compliance (ruff, mypy, ty, markdown lint, commit messages, repository profile)
Dependency audit (pip-audit)
Release gates (version checks, changelog validation) for PRs targeting main