readerboard 0.1.4__tar.gz → 0.2.0__tar.gz

{readerboard-0.1.4/readerboard.egg-info → readerboard-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: readerboard
-Version: 0.1.4
+Version: 0.2.0
 Summary: An HTTP service for BetaBrite and Alpha protocol LED signs: several sources share one sign, with alerts, scheduling and clock sync
 Author: mjaksn
 License-Expression: MIT
@@ -106,6 +106,20 @@ docker run --rm -p 5001:5001 \
 
 Then open <http://127.0.0.1:5001/docs>.
 
+`loop://` swallows everything written to it, so the service runs but there is
+nothing to see. To watch what it would have sent, run it against the sign
+simulator in `tools/signsim/` instead:
+
+```
+pip install --require-hashes -r tools/signsim/requirements.lock
+python scripts/run_with_simulator.py
+```
+
+That starts the simulator and the service together, already pointed at each
+other, and stops both on Ctrl+C. The simulator decodes each transmission, says
+what every byte of it means, and shows what the sign would be holding as a
+result. `tools/signsim/README.md` has the details.
+
 ## Installing it properly
 
 Two ways, which do the same job. Pick whichever suits the machine.
@@ -161,7 +175,8 @@ docker run ... --device /dev/ttyUSB0 --group-add 20 \
 
 ## Using it
 
-Every write needs an `X-API-Key` header. `GET /health` does not.
+Every write needs an `X-API-Key` header. Reads and `GET /health` do not. In the
+Swagger UI at `/docs`, the **Authorize** button puts it in once for the whole page.
 
 Register a message:
 
@@ -212,9 +227,11 @@ outcome in the body:
 ```
 
 That suits a client which finds branching on status codes awkward, such as a Home
-Assistant `rest_command` or a shell one-liner in a cron job. The single exception is a
-missing or wrong API key, which is a 401: a caller the service will not talk to is not the
-same as a request that failed.
+Assistant `rest_command` or a shell one-liner in a cron job. The exceptions are the
+requests that never reach the endpoint at all: a missing or wrong API key is a 401, a
+service with no API key configured is a 503, and a body that is not the shape the endpoint
+declares gets FastAPI's own 422. A caller the service will not talk to, and a body it
+cannot read, are not the same as a request that failed.
 
 `POST /Write/Message` writes to one reserved slot, named `default`. It deliberately does
 not touch the sign's **priority** file, which by protocol suppresses every other message on
@@ -242,6 +259,19 @@ the log, but they are not settings to fiddle with.
 ## Security
 
 An API key is required on every write, compared in constant time, and never logged.
+Reads and `GET /health` need none, so a monitor can watch the sign without holding a key
+that could write to it.
+
+The key is declared to the API description as a security scheme, so the Swagger UI at
+`/docs` has an **Authorize** button: enter the key once and every write on the page
+carries it. It is the same `X-API-Key` header a client sends, so nothing about a script
+or a Home Assistant `rest_command` changes.
+
+That page is configured to remember the key, so it survives a reload or a browser
+restart rather than needing to be pasted in again. Convenient on your own machine, and
+worth knowing before you use **Authorize** on a shared or kiosk browser, where the next
+person to open `/docs` inherits it. Use the browser's Logout in the Authorize dialog, or
+just do not authorize there.
 
 **Message content reaches the sign as protocol bytes**, so it is worth knowing what a
 client holding the key can do. The markup renderer emits bytes only for tokens it
@@ -291,6 +321,15 @@ claim. Read it before changing anything in `readerboard/protocol/`.
 `scripts/protocol_spike.py` settles the few questions the document cannot answer about
 this particular sign. It is destructive and refuses to run without `--confirm-erase`.
 
+`tools/signsim/` is a PySide6 stand-in for the sign, described above. Its own tests
+are collected by the `pytest` run here and need no Qt installed; the application does,
+and it is pinned separately so that nothing the service installs ever pulls Qt in.
+
+`scripts/run_with_simulator.py` starts the service and the simulator together. Both
+editors have it as a launch configuration, "API and sign simulator" in
+`.vscode/launch.json` and "API and simulator" in `.idea/runConfigurations/`, along with
+configurations for each half on its own.
+
 ## Licence
 
 MIT. See [LICENSE](https://github.com/mjaksn/readerboard/blob/main/LICENSE).

{readerboard-0.1.4 → readerboard-0.2.0}/README.md

@@ -64,6 +64,20 @@ docker run --rm -p 5001:5001 \
 
 Then open <http://127.0.0.1:5001/docs>.
 
+`loop://` swallows everything written to it, so the service runs but there is
+nothing to see. To watch what it would have sent, run it against the sign
+simulator in `tools/signsim/` instead:
+
+```
+pip install --require-hashes -r tools/signsim/requirements.lock
+python scripts/run_with_simulator.py
+```
+
+That starts the simulator and the service together, already pointed at each
+other, and stops both on Ctrl+C. The simulator decodes each transmission, says
+what every byte of it means, and shows what the sign would be holding as a
+result. `tools/signsim/README.md` has the details.
+
 ## Installing it properly
 
 Two ways, which do the same job. Pick whichever suits the machine.
@@ -119,7 +133,8 @@ docker run ... --device /dev/ttyUSB0 --group-add 20 \
 
 ## Using it
 
-Every write needs an `X-API-Key` header. `GET /health` does not.
+Every write needs an `X-API-Key` header. Reads and `GET /health` do not. In the
+Swagger UI at `/docs`, the **Authorize** button puts it in once for the whole page.
 
 Register a message:
 
@@ -170,9 +185,11 @@ outcome in the body:
 ```
 
 That suits a client which finds branching on status codes awkward, such as a Home
-Assistant `rest_command` or a shell one-liner in a cron job. The single exception is a
-missing or wrong API key, which is a 401: a caller the service will not talk to is not the
-same as a request that failed.
+Assistant `rest_command` or a shell one-liner in a cron job. The exceptions are the
+requests that never reach the endpoint at all: a missing or wrong API key is a 401, a
+service with no API key configured is a 503, and a body that is not the shape the endpoint
+declares gets FastAPI's own 422. A caller the service will not talk to, and a body it
+cannot read, are not the same as a request that failed.
 
 `POST /Write/Message` writes to one reserved slot, named `default`. It deliberately does
 not touch the sign's **priority** file, which by protocol suppresses every other message on
@@ -200,6 +217,19 @@ the log, but they are not settings to fiddle with.
 ## Security
 
 An API key is required on every write, compared in constant time, and never logged.
+Reads and `GET /health` need none, so a monitor can watch the sign without holding a key
+that could write to it.
+
+The key is declared to the API description as a security scheme, so the Swagger UI at
+`/docs` has an **Authorize** button: enter the key once and every write on the page
+carries it. It is the same `X-API-Key` header a client sends, so nothing about a script
+or a Home Assistant `rest_command` changes.
+
+That page is configured to remember the key, so it survives a reload or a browser
+restart rather than needing to be pasted in again. Convenient on your own machine, and
+worth knowing before you use **Authorize** on a shared or kiosk browser, where the next
+person to open `/docs` inherits it. Use the browser's Logout in the Authorize dialog, or
+just do not authorize there.
 
 **Message content reaches the sign as protocol bytes**, so it is worth knowing what a
 client holding the key can do. The markup renderer emits bytes only for tokens it
@@ -249,6 +279,15 @@ claim. Read it before changing anything in `readerboard/protocol/`.
 `scripts/protocol_spike.py` settles the few questions the document cannot answer about
 this particular sign. It is destructive and refuses to run without `--confirm-erase`.
 
+`tools/signsim/` is a PySide6 stand-in for the sign, described above. Its own tests
+are collected by the `pytest` run here and need no Qt installed; the application does,
+and it is pinned separately so that nothing the service installs ever pulls Qt in.
+
+`scripts/run_with_simulator.py` starts the service and the simulator together. Both
+editors have it as a launch configuration, "API and sign simulator" in
+`.vscode/launch.json` and "API and simulator" in `.idea/runConfigurations/`, along with
+configurations for each half on its own.
+
 ## Licence
 
 MIT. See [LICENSE](https://github.com/mjaksn/readerboard/blob/main/LICENSE).

{readerboard-0.1.4 → readerboard-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "readerboard"
-version = "0.1.4"
+version = "0.2.0"
 description = "An HTTP service for BetaBrite and Alpha protocol LED signs: several sources share one sign, with alerts, scheduling and clock sync"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -97,7 +97,10 @@ packages = [
 readerboard = ["py.typed"]
 
 [tool.pytest.ini_options]
-testpaths = ["tests"]
+# The simulator under tools/ is collected too. Its tests import only the pure
+# half of it, never PySide6, so they run in CI where Qt is not installed, and
+# the round trip they check is against the frame builders in this package.
+testpaths = ["tests", "tools/signsim/tests"]
 addopts = "-q --strict-markers --strict-config"
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
@@ -136,8 +139,16 @@ ignore = [
 # and rewriting it into docstring-bearing prose would only obscure its origin.
 "readerboard/protocol/constants.py" = ["E501", "RUF001", "RUF003"]
 # A test's name is its documentation, and a docstring repeating it would be
-# worse than none. Tests that need explaining have one anyway.
+# worse than none. Tests that need explaining have one anyway. The simulator's
+# tests are named separately because this glob is anchored at the project root
+# and does not reach into tools/.
 "tests/*" = ["D100", "D101", "D102", "D103", "D105", "D107"]
+"tools/signsim/tests/*" = ["D100", "D101", "D102", "D103", "D105", "D107"]
+
+[tool.ruff.lint.isort]
+# The simulator is not under the project root, so import sorting would put it
+# in the third party block and then complain that it is in the wrong one.
+known-first-party = ["readerboard", "signsim"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "pep257"

{readerboard-0.1.4 → readerboard-0.2.0}/readerboard/__init__.py

@@ -7,4 +7,4 @@ and against the release tag, before anything is published. See
 
 __all__ = ["__version__"]
 
-__version__ = "0.1.4"
+__version__ = "0.2.0"

{readerboard-0.1.4 → readerboard-0.2.0}/readerboard/api/app.py

@@ -52,11 +52,15 @@ Several sources can share the sign at once. Each registers a named **slot**, and
 the sign rotates through the registered slots by itself. An **alert** takes the
 whole display over until it is released, then the rotation resumes.
 
-Every write needs an `X-API-Key` header. `GET /health` does not.
+Every write needs an `X-API-Key` header. Reads and `GET /health` do not. On this
+page, put the key in once with the **Authorize** button and every write below
+carries it.
 
 The `/Write` and `/Enumerations` paths are a smaller surface for clients that
 would rather not read status codes: every response there is a 200 with the
-outcome in the body.
+outcome in the body, unless the request never reaches the route at all. A missing
+or wrong `X-API-Key` is a 401, a service with no API key configured is a 503, and
+a body that is not the shape the endpoint declares is a 422.
 """
 
 
@@ -196,6 +200,10 @@ def create_app(settings: Settings | None = None, transport: Transport | None = N
         description=DESCRIPTION,
         version=__version__,
         lifespan=lifespan,
+        # Keep the key entered in the Swagger UI's Authorize dialog across a page
+        # reload. Without it every reload is another trip to the config file for
+        # somebody trying things out, which is most of what /docs is for.
+        swagger_ui_parameters={"persistAuthorization": True},
     )
     app.state.settings = settings
 

{readerboard-0.1.4 → readerboard-0.2.0}/readerboard/api/deps.py

@@ -11,7 +11,8 @@ from __future__ import annotations
 import hmac
 from typing import Annotated
 
-from fastapi import Depends, Header, HTTPException, Request, status
+from fastapi import Depends, HTTPException, Request, Security, status
+from fastapi.security import APIKeyHeader
 
 from readerboard.config import Settings
 from readerboard.services.alerts import AlertService
@@ -21,6 +22,34 @@ from readerboard.sign.controller import SignController
 
 API_KEY_HEADER = "X-API-Key"
 
+# Declaring the key as a security scheme rather than as a plain header parameter
+# is what puts the Authorize button in the Swagger UI, and what makes a generated
+# client treat it as a credential rather than as one more header to fill in per
+# call. The header and the value are exactly what they always were.
+#
+# `auto_error=False` is load bearing. Left at its default the scheme rejects a
+# missing key itself, with its own wording and with no way to tell "you sent no
+# key" apart from "this service has no key configured at all". Those are
+# different answers, 401 and 503, and the simple endpoints document the
+# difference, so the checking stays in `require_api_key` below and this declares
+# the scheme and nothing else.
+# The scheme name becomes a key under `components.securitySchemes`, and the
+# OpenAPI specification requires those to match `^[a-zA-Z0-9\.\-_]+$` (section
+# 4.8.7.1). So it cannot be the prettier "API key", however much better that
+# reads in the Authorize dialog: a space there makes the whole document invalid
+# and trips validators and client generators. The human wording lives in the
+# description below, which is what the dialog shows underneath the name.
+api_key_scheme = APIKeyHeader(
+    name=API_KEY_HEADER,
+    auto_error=False,
+    scheme_name="ApiKeyAuth",
+    description=(
+        "The shared key every write carries. Set it with `api_key` in the config "
+        "file or `READERBOARD_API_KEY` in the environment; `scripts/install.sh` "
+        "generates one."
+    ),
+)
+
 
 def get_settings(request: Request) -> Settings:
     """Return the service's configuration."""
@@ -54,7 +83,7 @@ def get_clock(request: Request) -> ClockService:
 
 def require_api_key(
     request: Request,
-    x_api_key: Annotated[str | None, Header(alias=API_KEY_HEADER)] = None,
+    x_api_key: Annotated[str | None, Security(api_key_scheme)] = None,
 ) -> None:
     """Reject a write that does not carry the configured API key.
 

{readerboard-0.1.4 → readerboard-0.2.0}/readerboard/api/routes_simple.py

@@ -4,9 +4,11 @@ Fixed paths, one message, and **every response is HTTP 200** with the outcome in
 the body. That suits a Home Assistant ``rest_command`` or a shell one-liner in a
 cron job, neither of which branches gracefully on a status code.
 
-There is one exception to always-200, and it is deliberate: a request without a
-valid API key gets a 401 like any other, because a caller the service will not
-talk to is not the same as a request that failed.
+The exceptions to always-200 are all requests that never reach the code below,
+and they are deliberate. A missing or wrong API key is a 401, and a service with
+no API key configured at all is a 503, because a caller the service will not talk
+to is not the same as a request that failed. A body that is not the shape the
+endpoint declares gets FastAPI's own 422 before any of this runs.
 
 ``POST /Write/Message`` writes to a reserved slot rather than to the sign's
 priority file. That distinction matters more than it looks. By protocol a

{readerboard-0.1.4 → readerboard-0.2.0}/readerboard/protocol/constants.py

@@ -398,7 +398,7 @@ o_TILDE = b"\xc1"  # lowecase 'o' with tilde
 
 # ===========================================================================
 # Constants added for this service, sourced from the Alpha Sign Communications
-# Protocol (Adaptive Micro Systems, form 9708-8061F). See docs/protocol-notes.md
+# Protocol (Adaptive Micro Systems, form 9708-8061E). See docs/protocol-notes.md
 # for where each of these came from and what is still unconfirmed on hardware.
 # ===========================================================================
 

{readerboard-0.1.4 → readerboard-0.2.0}/readerboard/protocol/tokens.py

@@ -162,5 +162,5 @@ POSITION_BY_NAME: dict[str, Token] = {token.text: token for token in TEXT_POSITI
 
 
 def describe(tokens: tuple[Token, ...], key: str) -> list[dict[str, str]]:
-    """Render a token table as the list of dicts the enumeration endpoints return."""
+    """Render a token table as a list of dicts keyed by ``key`` and "description"."""
     return [{key: token.text, "description": token.description} for token in tokens]

{readerboard-0.1.4 → readerboard-0.2.0}/readerboard/services/registry.py

@@ -149,9 +149,9 @@ class MessageRegistry:
         Refreshing drops what the controller believes about the sign's contents
         and writes it all again. It runs on a timer, and on every reconnect.
 
-        If the Phase 0 spike shows the sign answers read commands through the
-        adapter, this can become a read-back comparison that only writes on a
-        real mismatch. The frame builders for those reads already exist; what is
+        If the spike shows the sign answers read commands through the adapter,
+        this can become a read-back comparison that only writes on a real
+        mismatch. The frame builders for those reads already exist; what is
         unproven is whether two-way traffic works over that path at all.
         """
         async with self._lock:

{readerboard-0.1.4 → readerboard-0.2.0/readerboard.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: readerboard
-Version: 0.1.4
+Version: 0.2.0
 Summary: An HTTP service for BetaBrite and Alpha protocol LED signs: several sources share one sign, with alerts, scheduling and clock sync
 Author: mjaksn
 License-Expression: MIT
@@ -106,6 +106,20 @@ docker run --rm -p 5001:5001 \
 
 Then open <http://127.0.0.1:5001/docs>.
 
+`loop://` swallows everything written to it, so the service runs but there is
+nothing to see. To watch what it would have sent, run it against the sign
+simulator in `tools/signsim/` instead:
+
+```
+pip install --require-hashes -r tools/signsim/requirements.lock
+python scripts/run_with_simulator.py
+```
+
+That starts the simulator and the service together, already pointed at each
+other, and stops both on Ctrl+C. The simulator decodes each transmission, says
+what every byte of it means, and shows what the sign would be holding as a
+result. `tools/signsim/README.md` has the details.
+
 ## Installing it properly
 
 Two ways, which do the same job. Pick whichever suits the machine.
@@ -161,7 +175,8 @@ docker run ... --device /dev/ttyUSB0 --group-add 20 \
 
 ## Using it
 
-Every write needs an `X-API-Key` header. `GET /health` does not.
+Every write needs an `X-API-Key` header. Reads and `GET /health` do not. In the
+Swagger UI at `/docs`, the **Authorize** button puts it in once for the whole page.
 
 Register a message:
 
@@ -212,9 +227,11 @@ outcome in the body:
 ```
 
 That suits a client which finds branching on status codes awkward, such as a Home
-Assistant `rest_command` or a shell one-liner in a cron job. The single exception is a
-missing or wrong API key, which is a 401: a caller the service will not talk to is not the
-same as a request that failed.
+Assistant `rest_command` or a shell one-liner in a cron job. The exceptions are the
+requests that never reach the endpoint at all: a missing or wrong API key is a 401, a
+service with no API key configured is a 503, and a body that is not the shape the endpoint
+declares gets FastAPI's own 422. A caller the service will not talk to, and a body it
+cannot read, are not the same as a request that failed.
 
 `POST /Write/Message` writes to one reserved slot, named `default`. It deliberately does
 not touch the sign's **priority** file, which by protocol suppresses every other message on
@@ -242,6 +259,19 @@ the log, but they are not settings to fiddle with.
 ## Security
 
 An API key is required on every write, compared in constant time, and never logged.
+Reads and `GET /health` need none, so a monitor can watch the sign without holding a key
+that could write to it.
+
+The key is declared to the API description as a security scheme, so the Swagger UI at
+`/docs` has an **Authorize** button: enter the key once and every write on the page
+carries it. It is the same `X-API-Key` header a client sends, so nothing about a script
+or a Home Assistant `rest_command` changes.
+
+That page is configured to remember the key, so it survives a reload or a browser
+restart rather than needing to be pasted in again. Convenient on your own machine, and
+worth knowing before you use **Authorize** on a shared or kiosk browser, where the next
+person to open `/docs` inherits it. Use the browser's Logout in the Authorize dialog, or
+just do not authorize there.
 
 **Message content reaches the sign as protocol bytes**, so it is worth knowing what a
 client holding the key can do. The markup renderer emits bytes only for tokens it
@@ -291,6 +321,15 @@ claim. Read it before changing anything in `readerboard/protocol/`.
 `scripts/protocol_spike.py` settles the few questions the document cannot answer about
 this particular sign. It is destructive and refuses to run without `--confirm-erase`.
 
+`tools/signsim/` is a PySide6 stand-in for the sign, described above. Its own tests
+are collected by the `pytest` run here and need no Qt installed; the application does,
+and it is pinned separately so that nothing the service installs ever pulls Qt in.
+
+`scripts/run_with_simulator.py` starts the service and the simulator together. Both
+editors have it as a launch configuration, "API and sign simulator" in
+`.vscode/launch.json` and "API and simulator" in `.idea/runConfigurations/`, along with
+configurations for each half on its own.
+
 ## Licence
 
 MIT. See [LICENSE](https://github.com/mjaksn/readerboard/blob/main/LICENSE).

{readerboard-0.1.4 → readerboard-0.2.0}/tests/test_api.py

@@ -1,5 +1,6 @@
 """Tests for the HTTP surface, including the exact payloads already in use."""
 
+import re
 from collections.abc import Iterator
 
 import pytest
@@ -57,6 +58,19 @@ class TestHealth:
         assert KEY not in client.get("/health").text
 
 
+class _AnyDescription:
+    """Matches any description that tells a reader where the key comes from."""
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, str) and "READERBOARD_API_KEY" in other
+
+    def __repr__(self) -> str:
+        return "<a description mentioning READERBOARD_API_KEY>"
+
+
+ANY_DESCRIPTION = _AnyDescription()
+
+
 class TestAuth:
     def test_a_write_without_a_key_is_refused(self, client):
         response = client.put("/v2/messages/temperature", json={"message": "HI"})
@@ -80,12 +94,95 @@ class TestAuth:
         assert client.get("/v2/messages").status_code == 200
 
     def test_the_simple_endpoints_also_need_it(self, client):
-        # The single exception to their always-200 rule.
+        # One of the three exceptions to their always-200 rule; the others are
+        # a service with no API key configured (503) and a malformed body (422).
         response = client.post(
             "/Write/Message", json={"display_mode": "HOLD", "message": "HI"}
         )
         assert response.status_code == 401
 
+    def test_the_refusal_says_which_header_is_wanted(self, client):
+        # The scheme is declared with auto_error=False precisely so this wording
+        # and the 503 below stay ours rather than becoming "Not authenticated".
+        response = client.put("/v2/messages/temperature", json={"message": "HI"})
+        assert response.json()["detail"] == "a valid X-API-Key header is required"
+        assert response.headers["WWW-Authenticate"] == "X-API-Key"
+
+
+class TestTheKeyIsDeclaredAsASecurityScheme:
+    """What puts the Authorize button in the Swagger UI.
+
+    The key was a plain header parameter once, which worked but told neither
+    the documentation page nor a generated client that it was a credential.
+    These pin the shape rather than the rendering, since the rendering is
+    Swagger's business.
+    """
+
+    def test_the_scheme_is_declared(self, settings, sign):
+        schema = create_app(settings, transport=sign).openapi()
+        assert schema["components"]["securitySchemes"] == {
+            "ApiKeyAuth": {
+                "type": "apiKey",
+                "in": "header",
+                "name": "X-API-Key",
+                "description": ANY_DESCRIPTION,
+            }
+        }
+
+    def test_every_write_requires_it(self, settings, sign):
+        schema = create_app(settings, transport=sign).openapi()
+        for path, method in [
+            ("/v2/messages/{key}", "put"),
+            ("/v2/messages/{key}", "delete"),
+            ("/v2/messages", "delete"),
+            ("/v2/alerts", "post"),
+            ("/v2/alerts", "delete"),
+            ("/v2/sign/sync-clock", "post"),
+            ("/v2/sign/command", "post"),
+            ("/Write/Message", "post"),
+            ("/Write/ControlCommand", "post"),
+        ]:
+            assert schema["paths"][path][method]["security"] == [{"ApiKeyAuth": []}], (
+                "%s %s should be marked as needing the key" % (method.upper(), path)
+            )
+
+    def test_the_open_endpoints_are_not_marked_as_needing_it(self, settings, sign):
+        # Health is deliberately unauthenticated so a monitor can watch the sign
+        # without holding a key that could write to it, and the reads are open
+        # too. The document should say so rather than leave it to be guessed.
+        schema = create_app(settings, transport=sign).openapi()
+        for path, method in [
+            ("/health", "get"),
+            ("/v2/messages", "get"),
+            ("/v2/alerts", "get"),
+            ("/v2/enumerations/display-modes", "get"),
+        ]:
+            assert "security" not in schema["paths"][path][method]
+
+    def test_every_component_key_is_one_the_specification_allows(self, settings, sign):
+        # OpenAPI 3.1 section 4.8.7.1: "All the fixed fields declared above are
+        # objects that MUST use keys that match the regular expression:
+        # ^[a-zA-Z0-9\.\-_]+$". The scheme name became one of those keys, and a
+        # readable "API key" with a space in it made the whole document invalid
+        # for anything stricter than the Swagger UI. Nothing here catches that by
+        # itself: the CI check only diffs the generated document against the
+        # committed one, so both sides would be equally wrong.
+        schema = create_app(settings, transport=sign).openapi()
+        allowed = re.compile(r"^[a-zA-Z0-9._-]+$")
+        for section, entries in schema.get("components", {}).items():
+            for key in entries:
+                assert allowed.match(key), "components.%s has the key %r" % (section, key)
+
+    def test_the_header_is_no_longer_a_parameter_on_every_operation(self, settings, sign):
+        # The old shape put an optional X-API-Key parameter on each protected
+        # operation, which is what a reader had to fill in one endpoint at a
+        # time. One scheme replaces all of them.
+        schema = create_app(settings, transport=sign).openapi()
+        for path, operations in schema["paths"].items():
+            for method, operation in operations.items():
+                names = [one["name"] for one in operation.get("parameters", [])]
+                assert "X-API-Key" not in names, "%s %s" % (method.upper(), path)
+
 
 class TestMessages:
     def test_registering_and_reading_back(self, client):

{readerboard-0.1.4 → readerboard-0.2.0}/tests/test_markup.py

@@ -39,8 +39,8 @@ class TestUnterminatedTag:
     The obvious implementation searches for the closing bracket and advances the
     cursor only when it finds one, so an unterminated tag leaves the cursor
     where it was and the loop spins forever, taking the thread with it. Both
-    behaviours below are
-    deliberate: reject it where we can, pass it through where we must.
+    behaviours below are deliberate: reject it where we can, pass it through
+    where we must.
     """
 
     def test_strict_rejects(self):