deckr 0.2.0

Deckr core contracts and runtime primitives for hardware, plugins, and controllers

deckr

deckr is the stable Python core for the Deckr ecosystem.

It holds the shared contracts and runtime primitives that other components can build on without pulling in controller-specific behavior. In practice that means:

• hardware event models and wire formats
• plugin manifests, events, and message types
• shared runtime utilities such as MQTT helpers and component lifecycle support

Python-specific invariant recipe helpers now live with the controller-side runtime, not in deckr core.

The controller now lives in its own sibling repository:

• https://github.com/kws/deckr-controller

Repository Layout

src/deckr/
  core/        Generic runtime utilities and messaging primitives
  hardware/    Hardware-facing shared contracts and wire models
  hw/          Compatibility shim for older imports
  plugin/      Plugin-facing contracts and manifests
tests/

Requirements

• Python 3.11+
• uv

Quick Start

Install the project and development tooling:

uv sync

Run the default validation suite:

uv run ruff check .
uv run lint-imports
uv run pytest

Build distributables:

uv build

Package Boundaries

The core architectural rule is that deckr stays reusable and controller-free. If code is specific to orchestration, rendering policy, device lifecycle management, or controller configuration, it belongs in deckr-controller, not here.

Internal boundaries are enforced with .importlinter:

• deckr.core must not import deckr.hardware
• deckr.core must not import deckr.plugin
• deckr.hardware must not import deckr.plugin

Run the contract checks with:

uv run lint-imports

Plugin Protocol Layers

The plugin contract is intentionally split into an Elgato-aligned core plus Deckr-specific extensions:

• deckr.plugin.core_api
  • The minimum surface a controller-lite implementation should support.
  • Keeps set_title, set_image, set_state, show_alert, show_ok, settings, open_url, and switch_to_profile close to Stream Deck semantics.
• deckr.plugin.extensions
  • Deckr-only features such as dynamic pages, screen power control, and graph image capability advertisement.

The key image rule is:

• core set_image: Stream Deck-style image reference, typically a plugin-local path or a data URI / base64 image string
• Deckr graph image extension: still uses set_image, but the string can be a Deckr graph-image data URI with media type application/vnd.deckr.graph+json

deckr.hw Rename

The shared hardware package has been renamed from deckr.hw to deckr.hardware.

New code should import deckr.hardware. A lightweight compatibility shim is kept in place for older deckr.hw imports while downstream packages migrate.

Releases

This repository now releases a single distribution: deckr.

• The source of truth for the published version is the root pyproject.toml.
• Use package tags in the form deckr-vX.Y.Z.
• Stable releases use normal PEP 440 versions such as 0.3.0.
• After each stable release, bump immediately to the next development line, e.g. 0.4.0.dev0, in a separate follow-up commit.

Release Flow

1. Update version in pyproject.toml to the stable release number.

2. Run the validation suite:

   uv run ruff check .
   uv run lint-imports
   uv run pytest
   

3. Refresh the lockfile:

   uv lock --refresh
   

4. Commit the release, for example:

   git commit -am "chore(deckr): release v0.3.0"
   

5. Tag the release commit:

   git tag deckr-v0.3.0
   

6. Build from the tag so the artifacts match the stable version exactly:

   git checkout deckr-v0.3.0
   uv build
   git checkout -
   

7. Publish the wheel and sdist using your usual PyPI workflow.

8. Immediately bump pyproject.toml to the next development version, refresh the lockfile, and commit that separately:

   uv lock --refresh
   git commit -am "chore(deckr): bump to development release 0.4.0.dev0"
   

The stable tag should always point at the stable release commit, not the later .dev0 commit.