Fixing Failures

Common gate failures and how to resolve them — from formatting issues to missing documentation and test coverage.

When a gate fails, plesty check prints an error message explaining what went wrong. This guide covers the most common failures and how to fix them.

Gate 1: Metadata & Namespace

Common failures:

Fix:

# Check pyproject.toml has all required fields
cat pyproject.toml

# Ensure package name follows convention
# Correct: plesty-my-device
# Module path: plesty/my_device/

Gate 2: Code Hygiene & Tooling

Common failures:

Fix:

# Format the code
uv run ruff format --config $(uv run python -c "from importlib.resources import files; print(files('plesty.sdk').joinpath('assets/ruff.toml'))") .

# Run lint and fix what you can
uv run ruff check --fix

# Run mypy and fix type annotations
uv run mypy plesty/

Gate 3: API Interface Matching

Common failures:

Fix:

Ensure your class inherits from the correct base class and implements all required methods:

from plesty.lib.device import BaseDeviceSyncModel

class MyDevice(BaseDeviceSyncModel):
    def connect(self) -> bool:
        ...
    def disconnect(self) -> None:
        ...
    def identity(self) -> str:
        ...

Gate 5: Documentation Completeness

Common failures:

Fix:

# Create or update docs/index.md
touch docs/index.md

# Update CHANGELOG.md with your changes

Gate 6: Dependency Coexistence

Common failures:

Fix:

Replace exact pins with range constraints:

# Wrong
dependencies = ["numpy==1.26.0"]

# Correct
dependencies = ["numpy>=1.26.0,<2.0.0"]

Gate 7: Test Coverage

Common failures:

Fix:

Add more tests to cover untested code paths:

# Run tests with coverage to see what's missing
uv run pytest --cov=plesty --cov-report=term-missing

Gate 10: Vulnerability Audit

Common failures:

Fix:

# Upgrade the affected package
uv lock --upgrade-package <package>
uv sync

Gate d1: Device API Pipeline

Common failures:

Fix:

Check each sub-gate's error message and fix the corresponding issue in your device implementation.

General tips

Next steps