plesty-sdk · Gate System

Automated Quality Gates

How plesty check enforces PLESTY standards across all HUB modules

plesty-sdk
What is it?

plesty check is the PLESTY developer CLI's core compliance command. It runs a battery of static-analysis, tooling, test, and CI checks against any module in the PLESTY ecosystem — device drivers, analyzers, experiments, or core libraries — and reports a clear pass/fail for each gate.

It enforces three progressively strict standards. Every module declares which standard it targets in pyproject.toml, and the pre-push git hook (installed by plesty init) enforces it automatically before every push.

pixel
Gates 1–2 only. Minimal sanity check for early prototypes.
nebula
Gates 1–6. Full static analysis, API alignment, and docs.
quantum
Gates 1–14 + d1. Required for all published HUB modules.
The Gates
# Tier Gate pixel nebula quantum
1[SDK+CI]Metadata & Namespace✓✓✓
2[SDK+CI]Code Hygiene & Tooling✓✓✓
3[SDK+CI]API Interface Matching—✓✓
4[SDK+CI]Data Layer Compliance—✓✓
5[SDK+CI]Documentation Completeness—✓✓
6[SDK+CI]Dependency Coexistence—✓✓
7[SDK+CI]Automated Test Coverage ≥80%——✓
8[SDK+CI]Semantic Versioning——✓
9[SDK+CI]Licensing Compliance——✓
10[SDK+CI]Vulnerability Audit——✓
11[SDK]Docs Build——✓
12[CI]Docs Deployment——✓
13[CI]Secret Scanning——✓
14[CI]Build & Release (PyPI)——✓
d1[Device]Device API Pipeline——✓
[SDK+CI] Local pre-push + CI authoritative [SDK] Local only, skipped in CI [CI] CI only (needs credentials) [Device] Only when module_type = "device"
Tutorial
1
Set up your module and install the pre-push hook

Add plesty-sdk as a dev dependency and run plesty init once per clone. This installs the git pre-push hook so Gate compliance is checked automatically on every git push.

# pyproject.toml — declare plesty-sdk as a dev dependency [dependency-groups] dev = ["plesty-sdk>=0.2.1"] [tool.plesty] standard = "quantum" module_type = "device"
# Sync dev dependencies and install the pre-push hook uv sync uv run plesty init # Output: ✓ Pre-push hook installed at .git/hooks/pre-push ✓ Hook will run: uv run plesty check --standard quantum
2
Run the check and read the output

Run uv run plesty check --standard quantum from your module's root. Each gate prints a ✓ or fails with a clear error message and the affected file or gate name.

uv run plesty check --standard quantum Checking against standard: quantum ✓ Metadata & Namespace ✓ Code Hygiene (lint) ✓ Code Hygiene (format) ✓ Code Hygiene (types) ✓ API Interface Matching ✓ Data Layer Compliance ✓ Documentation Completeness ✓ Dependency Coexistence ✓ Automated Test Coverage (≥80%) ✓ Semantic Versioning (no commits since last tag) ✓ Licensing Compliance (static) ✓ Vulnerability Audit (no known CVEs) ✓ Docs Build ✓ Device API Pipeline (d1 — 8 mock gates pass) All checks passed.

A failing run looks like this — the gate name and exact error are always printed:

Checking against standard: quantum ✓ Metadata & Namespace ✗ Code Hygiene (format) Error: [Code Hygiene] ruff format check failed — run: uv run ruff format --config <sdk-ruff.toml> . Affected: plesty/mydevice/base_device.py
3
Fix common failures by gate

Gate 2 — Code hygiene: format and lint violations are auto-fixable. Always use the SDK's ruff.toml (line-length 99) — plain ruff format uses a different line length and will re-fail.

# Auto-fix formatting (line-length=99 from plesty-sdk config) uv run ruff format --config $(uv run python -c \ "from importlib.resources import files; \ print(files('plesty.sdk').joinpath('assets/ruff.toml'))") . # Auto-fix lint uv run ruff check --fix .

Gate 4 — Data Layer (missing return types): add explicit return annotations to all public methods.

# Before — Gate 4 fails def get_wavelength(self): return float(self._query("SENS:WAVE?")) # After — Gate 4 passes def get_wavelength(self) -> float: return float(self._query("SENS:WAVE?"))

Gate 5 — Documentation: create docs/index.md and ensure CHANGELOG.md is updated after every tagged commit.

# Minimum docs structure docs/ index.md # Required — at least one line of content toc.yaml # Required — sphinx-external-toc entry CHANGELOG.md # Required — must be updated since last tag

Gate 9 — Licensing: the license field, LICENSE, and COPYING files must all be present.

[project] license = "LGPL-3.0-or-later" license-files = ["LICENSE", "COPYING"]

Gate 10 — Vulnerability Audit: if pip-audit finds a CVE, upgrade the affected package via uv:

uv lock --upgrade-package <package-name> uv sync
4
Let the pre-push hook protect you automatically

Once plesty init has been run, every git push triggers the full compliance check. A failing gate blocks the push.

git push origin feat/my-feature:exp # Pre-push hook runs automatically: Checking against standard: quantum ✓ Metadata & Namespace ✗ Code Hygiene (format) Error: ruff format check failed. error: failed to push some refs to 'gitlab.com:plesty/hub/...' # Push is blocked — fix the issue, then push again

The hook reads standard from your [tool.plesty] section automatically — you never need to pass it manually to the hook.

Complete pyproject.toml reference
# pyproject.toml — minimal plesty-compliant device module [project] name = "plesty-mydevice" dynamic = ["version"] license = "LGPL-3.0-or-later" license-files = ["LICENSE", "COPYING"] description = "PLESTY driver for MyDevice" requires-python = ">=3.12" dependencies = ["plesty-lib>=0.2.6"] [dependency-groups] dev = ["pytest>=9", "plesty-sdk>=0.2.1"] [tool.plesty] standard = "quantum" # enforced by pre-push hook and CI module_type = "device" # activates Gate d1 [tool.plesty.docs] site-name = "MyDevice" docs-dir = "docs" api-reference = true [build-system] requires = ["hatchling", "versioningit"] build-backend = "hatchling.build" [tool.pytest.ini_options] testpaths = ["tests"]
Quick Reference
uv run plesty check
Run at the standard declared in pyproject.toml
uv run plesty check --standard nebula
Override the standard for this run
uv run plesty init
Install pre-push hook (run once per clone)