Pixel & Nebula Gates

The pixel and nebula tiers cover the first six gates. These are the fastest checks, designed to catch common issues early in development.

Pixel (gates 1–2)

Pixel runs pre-commit and completes in seconds.

Gate 1: Metadata & Namespace

Validates the module's pyproject.toml and namespace conventions.

What it checks:

• pyproject.toml has all required fields (name, version, description)
• Package name follows plesty- convention (lowercase, hyphens)
• Python module path uses underscores (plesty//)
• Module type is one of: device, experiment, analyzer, core

Why it matters:

Consistent metadata ensures that PLESTY tools can discover and work with your module automatically.

Gate 2: Code Hygiene & Tooling

Runs the Python toolchain on your code.

What it checks:

• Ruff lint — no linting errors
• Ruff format — code matches canonical formatting
• Mypy — type annotations are correct

Why it matters:

Consistent code style and type safety reduce bugs and make code easier to review.

Nebula (gates 3–6)

Nebula runs pre-push and includes all pixel gates plus four more.

Gate 3: API Interface Matching

Ensures classes that import from plesty-lib properly inherit from base classes.

What it checks:

• Device classes inherit from BaseDeviceSyncModel
• All mandatory methods are implemented
• Method signatures match the base class

Why it matters:

Proper inheritance guarantees that experiments and tools can interact with any device through a consistent API.

Gate 4: Data Layer Compliance

Validates return type annotations and schema definitions.

What it checks:

• Return type annotations on public methods
• No schema shadowing (duplicate parameter keys)
• Data types match schema definitions

Why it matters:

Clear type contracts prevent runtime errors and enable static analysis.

Gate 5: Documentation Completeness

Checks that essential documentation files exist and are up to date.

What it checks:

• docs/index.md exists and is non-empty
• CHANGELOG.md has been updated for the current version

Why it matters:

Documentation is essential for other developers and users to understand your module.

Gate 6: Dependency Coexistence

Ensures dependencies don't use exact version pins.

What it checks:

• No == exact version pins in dependencies
• Version ranges use >= and < constraints

Why it matters:

Exact pins cause dependency conflicts when multiple modules are used together.

Running pixel and nebula

# Run pixel only
uv run plesty check --standard pixel

# Run nebula
uv run plesty check --standard nebula

Next steps

• Learn about the quantum standard — full local verification
• Explore CI-only gates