🚀 3.14.0, #239

* Generating CSS from SCSS. (#231)
* Using `mypy` for type constraints (#216)
* Ref: API: Moving response shaping out of handlers (#240)
* Ref: Moving required params checks (#241)
* Feat: API v2 (#242)
* UI: Switching to API v2.

.github/workflows/CI.yaml

@@ -95,15 +95,15 @@ jobs:
       - name: Install OctoRelay
         run: pip install -e .
       - name: Prepare testing environment
-        run: pip install coverage pylint snapshottest
+        run: pip install coverage pylint snapshottest mypy
       - name: Test
         working-directory: tests
         run: python -m coverage run -m unittest test*.py
       - name: Report the coverage
         working-directory: tests
         run: |
           python -m coverage lcov --omit=test*,_version*
-          python -m coverage report --show-missing --omit=test*,_version*
+          python -m coverage report --show-missing --omit=test*,_version*,snap_*
       - name: Coveralls
         uses: coverallsapp/github-action@v2
         continue-on-error: true
@@ -112,6 +112,8 @@ jobs:
           flag-name: python-${{ matrix.python }}-octoprint-${{ matrix.octoprint }}
           parallel: true
           file: ./tests/coverage.lcov
+      - name: Types checking
+        run: mypy ./octoprint_octorelay
       - name: Lint
         run: pylint --rcfile=.pylintrc ./octoprint_octorelay ./tests
 

.gitignore

@@ -6,3 +6,4 @@ OctoRelay.egg-info
 .coverage
 coverage.lcov
 octorelay.js
+octorelay.css

CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## Version 3
 
+### 3.14.0
+
+- UI: Generating CSS from SCSS.
+- Using `mypy` for type constraints.
+- Introducing the plugin API v2.
+  - This feature aims to establish consistency and improve clarity across inputs and responses of the plugin API.
+  - This feature is opt-in until the next major release of the plugin.
+  - Developers and other API users are advised to migrate to the new API.
+  - Introducing the `version` and its shorthand `v` parameter of each API request payload (integer).
+    - When the parameter is ommitted, the API falls back to v1 (previous behaviour and responses).
+    - When the parameter is set to `2`, the new request payload is expected and the API responds differently.
+  - Main differences of v2:
+    - For `update` and `getStatus` commands `pin` parameter is renamed to `subject`.
+    - For `listAllStatus` command `active` property renamed to `status`.
+    - For `getStatus` command on disabled relay the API responds with an HTTP code `400` instead of `status: false`.
+    - For `update` and `cancelTask` commands there is no more `status: "ok" | "error"`:
+      - The `status` now always means the relay state (boolean), while errors are reported via HTTP codes.
+  - Check out the updated Readme for new examples.
+
+| Command       | v1 request parameters    | v2 request parameter     |
+|---------------|--------------------------|--------------------------|
+| update        | `pin, target`            | `subject, target`        |
+| getStatus     | `pin`                    | `subject`                |
+| listAllStatus | None                     | None                     |
+| cancelTask    | `subject, target, owner` | `subject, target, owner` |
+
+| Command       | v1 response                | v2 response          |
+|---------------|----------------------------|----------------------|
+| update        | `result: bool, status: ok` | `status: bool`       |
+| getStatus     | `status`                   | `status`             |
+| listAllStatus | `[active, id, name]`       | `[status, id, name]` |
+| cancelTask    | `status: ok`               | `cancelled: bool`    |
+
 ### 3.12.0
 
 - Feature: the API command `update` now accepts the optional `target` parameter.

MANIFEST.in

@@ -4,4 +4,5 @@ recursive-include octoprint_octorelay/templates *
 recursive-include octoprint_octorelay/translations *
 recursive-include octoprint_octorelay/static *
 exclude octoprint_octorelay/static/js/.gitkeep
+exclude octoprint_octorelay/static/css/.gitkeep
 prune tests

README.md

@@ -85,6 +85,7 @@ You can toggle the relays ON and OFF the following ways:
 ## OctoRelay API
 
 Relays can be queried and updated through the [OctoPrint API](https://docs.octoprint.org/en/master/api/). Read that documentation on how to get an API Key.
+Each API request payload is required to have `version` or `v` entry, meaning the API version as described below.
 
 ### Change the relay state
 
@@ -95,16 +96,15 @@ curl 'http://octopi.local/api/plugin/octorelay' \
   -H 'X-Api-Key: YOUR_API_KEY' \
   -H 'Content-Type: application/json' \
   -X POST \
-  -d '{ "command": "update", "pin": "r1", "target": false }'
+  -d '{ "v": 2, "command": "update", "subject": "r1", "target": false }'
 
 # Sample response:
 # {
-#   "result": false,
-#   "status": "ok"
+#   "status": false
 # }
 ```
 
-The `target` entry in request payload is an optional boolean parameter. When it's `null` or omitted the relay will toggle. The `result` entry in the response payload reflects the relay state as the outcome of the request.
+The `target` entry in request payload is an optional boolean parameter. When it's `null` or omitted the relay will toggle. The `status` entry in the response payload reflects the relay state as the outcome of the request.
 
 ### Request the relay state
 
@@ -115,7 +115,7 @@ curl 'http://octopi.local/api/plugin/octorelay' \
   -H 'X-Api-Key: YOUR_API_KEY' \
   -H 'Content-Type: application/json' \
   -X POST \
-  -d '{ "command": "getStatus", "pin": "r1" }'
+  -d '{ "v": 2, "command": "getStatus", "subject": "r1" }'
 
 # Sample response:
 # {
@@ -132,24 +132,24 @@ curl 'http://octopi.local/api/plugin/octorelay' \
   -H 'X-Api-Key: YOUR_API_KEY' \
   -H 'Content-Type: application/json' \
   -X POST \
-  -d '{ "command": "listAllStatus" }'
+  -d '{ "v": 2, "command": "listAllStatus" }'
 
 # Sample response:
 # [
 #   {
-#     "active": true,
+#     "status": true,
 #     "id": "r1",
 #     "name": "Light"
 #   },
 #   {
-#     "active": false,
+#     "status": false,
 #     "id": "r2",
 #     "name": "Printer"
 #   }
 # ]
 ```
 
-The `active` entry reflects the actual state of the relay.
+The `status` entry reflects the actual state of the relay.
 
 ## Updates
 

mypy.ini

@@ -0,0 +1,14 @@
+[mypy]
+check_untyped_defs = True
+exclude = (?x)(
+        _version\.py$
+    )
+
+[mypy-octoprint.*]
+ignore_missing_imports = True
+
+[mypy-RPi.*]
+ignore_missing_imports = True
+
+[mypy-flask.*]
+ignore_missing_imports = True