Crystalfontz backports (#40)

- Respect `PLUSDECK_CONFIG_FILE`
- Remove `plusdeck`, `plusdeckd` and `plusdeckctl` from Python package
  - Add optional aliases in `./bin`
- Do not export from `plusdeck.dbus`
- `plusdeck.dbus.domain` and `plusdeck.dbus.select` modules
- Overhauled documentation

Author: jfhbrook

.github/workflows/qa.yaml

@@ -31,4 +31,4 @@ jobs:
           npx pyright@latest
       - name: Run tests
         run: |
-          pytest ./tests --ignore=tests/test_integration.py
+          pytest ./tests --ignore-glob='./tests/integration/**'

CHANGELOG.md

@@ -1,11 +1,25 @@
-yyyy/mm/dd Version x.y.z-1
+yyyy/mm/dd Version 5.0.0-1
 ------------------------
-- Include generated DBus interface docs
-- Fix links in documentation
-- CLI respects `CRYSTALFONTZ_CONFIG_FILE` environment variable
-- Remove `tox` from development tools
-- Consistently licensed as MPL-2.0
-- Improved PyPI classifiers
+- CLI changes:
+  - Main CLI respects `PLUSDECK_CONFIG_FILE` environment variable
+  - **BREAKING:** `plusdeck`, `plusdeckd` and `plusdeckctl` have been removed from the Python package in favor of `python3 -m plusdeck`, `python3 -m plusdeck.dbus.service` and `python3 -m plusdeck.dbus.client`, respectively
+  - Optional alias scripts for `plusdeck`, `plusdeck-service` and `plusdeck-dbus` included in the `./bin` folder
+  - DBus service CLI includes a `--system/--user` flag for explicitly selecting the bus
+  - **BREAKING:** DBus client CLI now uses `--user/--default` flag for selecting the bus
+- DBus API Changes:
+  - **BREAKING:** Root `plusdeck.dbus` no longer includes convenience exports
+  - Addition of `plusdeck.dbus.domain` module for domain mapping
+  - Addition of `plusdeck.dbus.select` module for selecting the DBus bus
+- Testing changes:
+  - Additional integration test for DBus
+  - Remove `tox` from development tools
+- Documentation improvements:
+  - Include generated DBus interface docs
+  - Fix links in documentation
+  - General overhaul based on lessons from `crystalfontz`
+- Packaging & Licensing
+  - **BREAKING:** Consistently licensed as MPL-2.0
+  - Improved PyPI classifiers
 
 2025/02/09 Version 4.0.1-1
 --------------------------

bin/plusdeck

@@ -0,0 +1,3 @@
+#!/usr/bin/sh
+
+exec python3 -m plusdeck "$@"

bin/plusdeck-dbus

@@ -0,0 +1,3 @@
+#!/usr/bin/sh
+
+exec python3 -m plusdeck.dbus.client "$@"

bin/plusdeck-service

@@ -0,0 +1,3 @@
+#!/usr/bin/sh
+
+exec python3 -m plusdeck.dbus.service "$@"

docs/dialout.md docs/access.mddocs/dialout.md renamed to docs/access.md

@@ -1,6 +1,14 @@
-# Dialout
+# Access and Permissions
 
-In Linux, by default, accessing serial ports requires `sudo`. This is inconvenient - you probably want your current user to have acccess without using `sudo`.
+In Linux, by default, accessing serial ports requires `sudo`. This is inconvenient - you probably want your current user to have access without using `sudo`. There are two ways to manage this access: either through the DBus service, or with the `dialout` group.
+
+## DBus
+
+The DBus service has the advantage of more fine-grained access control. However, it is only supported in Linux.
+
+For more information, see [DBus Access and Permissions](./dbus/access.md)
+
+## Dialout
 
 Typically, Linux serial ports are generally owned by `root` and are attached to the `dialout` group, with permissions such that members of the `dialout` group may read and write to the port.
 

docs/api/plusdeck.dbus.md

@@ -0,0 +1,46 @@
+# DBus API Overview
+
+The `plusdeck` library includes a DBus service and client. This service allows for multitenancy on Linux - the centralized service controls the serial bus, and clients - including `python3 -m plusdeck.dbus.client` - can connect to the service.
+
+The DBus APIs largely depend on the [sdbus](https://pypi.org/project/sdbus/) Python library, which in turn depends on the [sd-bus](https://www.freedesktop.org/software/systemd/man/latest/sd-bus.html) library. This means that, effectively, the DBus API is only available on Linux. `sdbus` is therefore an optional dependency, under the `dbus` extra.
+
+As a consequence, the DBus API is (unlike the primary `plusdeck` API) not re-exported at the top level. This is to make it viable to run unit tests for parts of the DBus API which don't strictly depend on `sdbus`, namely tests for `plusdeck.dbus.domain`.
+
+For information on the DBus service and client CLI, check out [the core DBus documentation](../../dbus/index.md).
+
+## plusdeck.dbus.client
+
+This module contains the core `DbusClient` class. This class is used for interacting with a live DBus service. This is where most users will want to start.
+
+For more information, view the API docs for [`plusdeck.dbus.client`](./plusdeck.dbus.client.md).
+
+## plusdeck.dbus.domain
+
+The DBus interface uses DBus compatible types, rather than the standard `plusdeck` domain objects. The domain module contains type aliases and mapper classes for converting to and from `plusdeck` domain objects and DBus types. While not strictly necessary for using the client, it's highly recommended.
+
+For more information, view the API docs for [`plusdeck.dbus.domain`](./plusdeck.dbus.domain.md).
+
+## plusdeck.dbus.config
+
+Configuration for the DBus service is a little different than for the serial client. This is because the DBus service doesn't live reload a config after it changes. In other words, if you edit the config file, the DBus service's loaded config will show drift. This module helps track the drift between these sources.
+
+For more information, view the API docs for [`plusdeck.dbus.config`](./plusdeck.dbus.config.md).
+
+## plusdeck.dbus.service
+
+This module contains abstractions for running the DBus service. It will typically be used through [the service CLI](../../dbus/service.md). But this module may be useful for users wishing to embed it in another program.
+
+For more information, view the API docs for [`plusdeck.dbus.service`](./plusdeck.dbus.service.md).
+
+## plusdeck.dbus.select
+
+This module contains convenience functions for configuring which bus the program uses.
+
+For more information, view the API docs for [`plusdeck.dbus.select`](./plusdeck.dbus.select.md).
+
+## plusdeck.dbus.interface
+
+This module contains the core `DbusInterface` class. This is used directly when serving the interface, and subclassed by the client.
+
+For more information, view the API docs for [`plusdeck.dbus.interface`](./plusdeck.dbus.interface.md).
+

docs/api/plusdeck.dbus/index.md

@@ -0,0 +1,7 @@
+# plusdeck.dbus.client
+
+This module contains the core `DbusClient` abstraction, which is used to interact with a DBus service.
+
+For information on how to use `plusdeck` domain objects with the DBus client, see [the API docs for `plusdeck.dbus.domain`](./plusdeck.dbus.domain.md). For examples of how to use the DBus client, look at [the source code for `plusdeckctl`](https://github.com/jfhbrook/plusdeck/blob/main/plusdeck/dbus/client/cli.py).
+
+::: plusdeck.dbus.client

docs/api/plusdeck.dbus/plusdeck.dbus.client.md

@@ -0,0 +1,3 @@
+# plusdeck.dbus.config
+
+::: plusdeck.dbus.config