Run the published surface check, so the reference plugin shows the right way to do it #3

New issue

Closed

opened 2026-09-21 15:20:21 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-09-21 15:20:21 +00:00

Owner

The surface it was waiting for landed in the core (postulo/postulo#229, 1d6cdd7e0):
postulo.plugins.api now carries the notifier contract, the records a sync works on, the
calls that write to a timeline, the details that hang off a contact, and the calendar text.
The core also publishes the check itself as postulo.plugins.testing, so a plugin can
assert the same thing about its own source that Postulo asserts about the ones it ships.

This plugin already imports nothing but postulo.plugins.api, so there is nothing to
move. Its tests/test_surface.py says "Copy this file into your own plugin; the only line
to change is PACKAGE" — and that advice is now wrong. The check is published; copying it
is what this issue exists to stop.

This is the plugin people are told to copy, so the check it shows should be the one the
core maintains.

Also

The core dev dependency has no ref at all. Pin it to 1d6cdd7e0 or later.

Run the published check

Replace this repository's hand-written copy of the AST check with the core's:

from pathlib import Path

from postulo.plugins.testing import assert_imports_only_the_surface


def test_the_plugin_imports_only_the_surface():
    assert_imports_only_the_surface(
        Path(__file__).resolve().parents[1] / "src" / "postulo_helloworld", package="postulo_helloworld"
    )

One check rather than several near-copies that can drift apart, and it resolves relative
imports, which the copy here does not.

The surface it was waiting for landed in the core (postulo/postulo#229, `1d6cdd7e0`): `postulo.plugins.api` now carries the notifier contract, the records a sync works on, the calls that write to a timeline, the details that hang off a contact, and the calendar text. The core also publishes the check itself as `postulo.plugins.testing`, so a plugin can assert the same thing about its own source that Postulo asserts about the ones it ships. This plugin already imports nothing but `postulo.plugins.api`, so there is nothing to move. Its `tests/test_surface.py` says *"Copy this file into your own plugin; the only line to change is `PACKAGE`"* — and that advice is now wrong. The check is published; copying it is what this issue exists to stop. This is the plugin people are told to copy, so the check it shows should be the one the core maintains. ## Also - The core dev dependency has no ref at all. Pin it to `1d6cdd7e0` or later. ## Run the published check Replace this repository's hand-written copy of the AST check with the core's: ```python from pathlib import Path from postulo.plugins.testing import assert_imports_only_the_surface def test_the_plugin_imports_only_the_surface(): assert_imports_only_the_surface( Path(__file__).resolve().parents[1] / "src" / "postulo_helloworld", package="postulo_helloworld" ) ``` One check rather than several near-copies that can drift apart, and it resolves relative imports, which the copy here does not.

tiagoagueda added the

enhancement

label

2026-09-21 15:20:21 +00:00

tiagoagueda referenced this issue from a commit

2026-09-21 15:29:11 +00:00

Stop telling people to copy the surface check

tiagoagueda closed this issue

2026-09-21 15:29:12 +00:00