diff --git a/.coderabbit.yaml b/.coderabbit.yaml new file mode 100644 index 0000000..68220b7 --- /dev/null +++ b/.coderabbit.yaml @@ -0,0 +1,30 @@ +# yaml-language-server: $schema=https://storage.googleapis.com/coderabbit_public_assets/schema.v2.json +reviews: + pre_merge_checks: + docstrings: + # Docstring Coverage is scored over the whole diff against a single + # percentage threshold, and the schema gives it no per-path option: + # `mode` and `threshold` are all it takes. What it cannot see is that + # pyproject.toml's own ruff config *deliberately* ignores D100-D104 + # and D107 (missing docstrings) under tests/*, matching the two + # sibling repos: every test here is named for what it asserts rather + # than carrying a docstring that restates that name. Leaving this + # check on therefore fights that convention on every PR that adds + # tests -- which is most of them -- for no gain, since coverage of + # src/ is already enforced by ruff's pydocstyle rules in the gate + # (./scripts/pre-commit-test.sh), which IS path-aware. + mode: "off" + # The exclusion the check above cannot express, stated where it *is* + # path-scoped: the reviewer. This holds whether or not that check is ever + # switched back on. + path_instructions: + - path: "tests/**" + instructions: >- + Do not ask for docstrings on test functions, methods or classes. + `[tool.ruff.lint.per-file-ignores]` in pyproject.toml ignores + D100-D104 and D107 under tests/* on purpose: each test is named for + the behaviour it pins, and a docstring restating that name is noise. + The test modules do carry a docstring, and a comment explaining what + a test is proving is welcome where the name alone does not carry it. + Docstrings ARE required in src/, where ruff's pydocstyle rules + enforce them. diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c6c436..d1588b3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -90,6 +90,30 @@ All notable changes to python-libei are recorded here. The format follows ### Fixed +- **The README's link to the developer pages landed on a file listing.** + `docs/developers/` holds `architecture.md` and `verification.md` and has no + README of its own, so the last entry of the documentation index sent a + reader to a directory listing rather than to anything written -- the same + defect the sibling recorder repo fixed in its own README, found by holding + this one to that fix. The entry now names both pages, and + `tests/test_documentation_shape.py` requires a linked directory to *have* a + README rather than merely to exist, which is the distinction `exists()` + cannot draw. + +- **Three public names were documented nowhere.** `eis.Flag`, + `eis.ConfigureRegion` and `portal.Activation` are in their modules' `__all__` + -- the declared surface, the thing `from libei.eis import *`, `pydoc` and an + IDE's completion read -- and appeared on no page of the README or `docs/`: + the only way to learn they existed was to open the source that defines them. + Each is now named where its subject is described: `Flag` and + `ConfigureRegion` beside `Eis.set_flag()` and `Device.configure()` in the + README's tour of the modules, with the region argument written out in the + own-EIS-server recipe, and `Activation` in the sentence saying what `portal` + is smaller than `ei` by. The guard runs the direction the existing checks + never did -- every one of them went from a page to the source, and none from + the declared surface back to the pages -- so a public name that ships with + prose nowhere is a failing test rather than a discovery. + - **`scripts/pre-commit-test.sh` failed its `tests` check on any interpreter without the package installed.** The script runs `python -m pytest -q -rs` with no `PYTHONPATH`, deliberately: CI's install step is one of the two diff --git a/README.md b/README.md index 646b6ad..d73e7b3 100644 --- a/README.md +++ b/README.md @@ -74,9 +74,10 @@ Each module has `is_available()`. `ei` and `eis` share the shapes around them: an `Error` exception, an `EventType` and `DeviceCapability` enum, and `Device`, `Seat`, `Region`, `Keymap`, `Touch`, `Ping`, `Event` with the frozen dataclasses its accessors return. `oeffis` and `portal` are smaller — `DeviceType`, no -`EventType` or `DeviceCapability`, and their own exception classes rather than -an `Error`. [docs/troubleshooting.md](docs/troubleshooting.md) names every class -they raise. The package ships `py.typed`, so callers type-check against real +`EventType` or `DeviceCapability`, `Activation` as the one frozen result a +portal wait hands back, and their own exception classes rather than an `Error`. +[docs/troubleshooting.md](docs/troubleshooting.md) names every class they raise. +The package ships `py.typed`, so callers type-check against real annotations rather than `Any`. ## What's implemented @@ -119,7 +120,9 @@ Beyond sending input, the wrapper also covers ping/pong round trips (`Device.keymap`), region mapping ids and coordinate conversion, `Context.disconnect()`, `Context.peek_event_type()`, and `Seat.request_device()`. On the server side, `libei.eis` mirrors all of it and -adds `Eis.set_flag()` and `Client.pid`. Underneath, the ctypes layer binds 250 +adds `Eis.set_flag()` (with the `Flag` values it takes), `Client.pid`, and +`Device.configure()` with the `ConfigureRegion` descriptions it accepts. +Underneath, the ctypes layer binds 250 of the 302 functions the three libraries export as of 1.6.0; what is left out, and why, is in [docs/developers/architecture.md](docs/developers/architecture.md#what-is-bound-and-what-is-deliberately-not). @@ -364,8 +367,10 @@ a list of error messages. Start there when nothing happens. happens" checklist - [docs/vs-snegg.md](docs/vs-snegg.md) — how this differs from the reference bindings, and two signature issues found by cross-checking the C source -- [docs/developers/](docs/developers/) — the four-layer architecture, and what - has actually been verified against which libei versions +- [docs/developers/architecture.md](docs/developers/architecture.md) and + [docs/developers/verification.md](docs/developers/verification.md) — the + four-layer architecture, and what has actually been verified against which + libei versions - [CONTRIBUTING.md](CONTRIBUTING.md) — setup, checks, testing against an old libei, releasing diff --git a/docs/recipes.md b/docs/recipes.md index d27e74e..ac6452f 100644 --- a/docs/recipes.md +++ b/docs/recipes.md @@ -317,7 +317,14 @@ while True: elif event.event_type is eis.EventType.SEAT_BIND: device = event.seat.new_device() device.configure( - name="my-pointer", capabilities=(eis.DeviceCapability.POINTER,) + name="my-pointer", + capabilities=(eis.DeviceCapability.POINTER,), + # A region is *described* rather than passed as a live + # eis.Region: configure() allocates, fills in and adds each + # one itself, so there is never a moment at which you hold + # one to set fields on. Omit it for a device whose space is + # unknown to you. + regions=(eis.ConfigureRegion(offset=(0, 0), size=(1920, 1080)),), ) device.add() device.resume() # until you resume it, the client may not send diff --git a/tests/test_documentation_shape.py b/tests/test_documentation_shape.py index 5ec725e..cc24794 100644 --- a/tests/test_documentation_shape.py +++ b/tests/test_documentation_shape.py @@ -16,7 +16,7 @@ import pytest -from libei import ei, eis +from libei import ei, eis, oeffis, portal _PROJECT_ROOT = Path(__file__).resolve().parent.parent _README = _PROJECT_ROOT / "README.md" @@ -311,8 +311,33 @@ def test_relative_links_point_at_something_that_exists() -> None: path = target.split("#", 1)[0] if not path: continue - assert (page.parent / path).exists(), ( - f"{page.name} links to {path}, which does not exist" + linked = page.parent / path + assert linked.exists(), f"{page.name} links to {path}, which does not exist" + if linked.is_dir(): + # A directory is a page only where it has a README. Without one + # the link lands the reader on a file listing, which is what + # the README's own links to `docs/developers/` did until they + # named the two pages in it -- and `exists()` alone cannot tell + # the two apart. + assert (linked / "README.md").exists(), ( + f"{page.name} links to the directory {path}, which has no " + "README to land on" + ) + + +def test_every_public_name_is_named_on_some_page() -> None: + # A name in a module's __all__ is its declared surface, and these pages are + # where a reader looks for it: three names were public and reached no page + # at all, so the only place to learn they existed was the source they are + # defined in. Read from __all__ rather than dir(), since what is being + # guarded is "declared public", not "happens to have an attribute". + text = "\n".join( + page.read_text(encoding="utf-8") for page in _documentation_pages() + ) + for module in (ei, eis, oeffis, portal): + for name in module.__all__: + assert name in text, ( + f"{module.__name__}.{name} is public but named on no page" )