Plesty Documentation

Scaffold a Device Project

Use plesty init device to generate a complete project layout ready for implementation.

The command

mkdir plesty-power-meter && cd plesty-power-meter
uv run --directory /path/to/plesty-sdk plesty init device

Or, if plesty-sdk is globally installed:

mkdir plesty-power-meter && cd plesty-power-meter
plesty init device

With explicit options:

plesty --project-dir ~/projects/plesty-power-meter init device \
  --name power_meter \
  --author "Jane Doe" \
  --email jane@example.com

plesty init infers the module name from the directory: plesty-power-meter → power_meter. The --name flag overrides this.

Generated layout

plesty-power-meter/
├── plesty/
│   └── power_meter/
│       ├── __init__.py          # public exports
│       ├── __main__.py          # entry point (guarded by __name__ == "__main__")
│       ├── base_device.py       # BaseDeviceSyncModel subclass
│       └── device.py            # thin wrapper / DocDevice for manual generation
├── docs/
│   ├── index.md                 # Gate 5 requirement
│   └── toc.yaml
├── tests/
│   ├── __init__.py
│   └── test_power_meter.py      # smoke tests covering all public methods
├── .env.example                 # credential template — real values go in .env (never committed)
├── .git/
│   └── hooks/
│       └── pre-push             # runs plesty check (standard from pyproject.toml)
├── .gitignore
├── .gitlab-ci.yml               # plesty-standard-ci component
├── CHANGELOG.md                 # Gate 5 requirement
├── LICENSE
├── LICENSES/
│   └── LGPL-3.0-or-later.txt
├── REUSE.toml                   # licensing metadata for non-code files
├── pyproject.toml
└── README.md

Parameter and operation schemas are not part of the scaffold — you add them during implementation; see Schemas.

What init does automatically

After copying the template, plesty init:

  1. Formats generated files — runs ruff format with the SDK config, so the scaffold already passes Gate 2 from commit zero.
  2. Creates the initial git commit — required by versioningit to resolve a package version from git history.
  3. Installs the pre-push hook — writes .git/hooks/pre-push to run plesty check using the standard in pyproject.toml.

First check after scaffolding

uv sync
uv run plesty check

A freshly scaffolded project passes all quantum gates immediately. If any gate fails on a fresh scaffold, that is a bug in plesty init — report it.

pyproject.toml highlights

[project]
name = "plesty-power-meter"
dynamic = ["version"]
dependencies = ["plesty-lib"]   # deliberately unpinned — tracks the newest release

[dependency-groups]
dev = ["pytest>=9.0.0", "pytest-cov>=5.0", "mypy>=1.0", "plesty-sdk>=0.2.0"]

[tool.plesty]
# standard derives from the release version (no tag yet = pixel);
# set standard = "quantum" to pin it.
module_type = "device"

The module_type = "device" line activates Gate d1 — the Device API Pipeline test.