Standards

All Plesty modules — whether in core, hub, or datatools — follow a shared set of practices enforced by plesty-sdk and plesty-ci. This page summarises the key rules. The authoritative sources are SCOPE_v1.0.0.md and CODING_PRACTICES.md in the governance repository.

Naming & Distribution

• Namespace: All modules use the flat plesty.<name> import pattern (e.g. import plesty.powermeter). Deep nested namespaces are discouraged.
• Package name: PyPI distribution names follow plesty-<name> (e.g. plesty-sdk, plesty-powermeter).
• Project folder: plesty-foo-bar containing a foo_bar/ source directory and declared in pyproject.toml as plesty.foo_bar.
• Device naming: Prefer vendor-specific names to avoid conflicts — e.g. plesty-chameleon-laser rather than plesty-laser.

Code Style & Typing

• PEP 8 compliance is required across all code.
• Type hints: Full annotations on all public functions and methods. Gradual typing is acceptable for internal/private code during the pre-1.0.0 phase.
• Formatter & linter: Ruff is the canonical tool. No other formatter should be introduced.
• Static analysis: Mypy in strict mode for core modules.
• Resource management: All hardware interfaces, network connections, and file handles must be managed with with statements. Catch specific exceptions — never bare except:.

Compliance Standard — plesty check

The SDK exposes three progressive compliance levels. Run locally with uv run plesty check.

Enforcement tiers:

• [SDK+CI] — run locally by plesty check and repeated by CI as the authoritative gate. Gates 1–6 are pure static analysis; gates 7–10 may require network access.
• [SDK] — local only. Gate 11 (Docs Build) is skipped in CI because gate 12 performs the authoritative build.
• [CI] — CI only, requiring remote credentials, protected branches, or release infrastructure.

The pre-push git hook installed by plesty init runs gates 1–10 automatically before every push.

Versioning

All packages follow Semantic Versioning (MAJOR.MINOR.PATCH):

During 0.y.z, minor increments may contain breaking changes — read CHANGELOG.md carefully before updating any 0.y.z dependency.

• Git tags use the v prefix: v0.1.0, v1.0.0.
• Every tag on main must correspond to a CHANGELOG.md entry.
• Tags are created only after the CI pipeline passes on main.

Licensing

All Plesty repositories use LGPL (Lesser General Public License) during the current development phase. Introducing code under a different license requires explicit approval from the Product Owner.

Issue & Commit Conventions

Issue and commit titles follow the pattern:

<type>(<scope>): <short summary>

Every issue must carry at least a type:: and a priority:: label. Add scope:: to indicate which subgroup is affected (scope::sdk, scope::lib, scope::hub, scope::ci, scope::website).