Run the published surface check, and pin the core that publishes it #3

New issue

Closed

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

tiagoagueda commented

2026-09-21 15:20:19 +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 — DestinationRefused,
FieldSpec, TestResult and check_destination — so there is nothing to move.

What it has is its own copy of the AST walk in tests/test_surface.py. So do
postulo-paperless, postulo-helloworld and postulo-imap, and postulo-dav had a fourth
inside test_dav.py: five near-identical checks, each subtly different about relative
imports and about what counts as reaching past. That is the drift the published one exists
to stop.

Run the published check

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_apprise",
        package="postulo_apprise",
    )

Keep what is particular to this plugin — that the four names it asks of the surface are on
__all__ rather than merely reachable, since __all__ is what the promise is made about.

Also

Pin the core to 1d6cdd7e0 or later, so postulo.plugins.testing is there to import.

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` — `DestinationRefused`, `FieldSpec`, `TestResult` and `check_destination` — so there is nothing to move. What it has is its own copy of the AST walk in `tests/test_surface.py`. So do postulo-paperless, postulo-helloworld and postulo-imap, and postulo-dav had a fourth inside `test_dav.py`: five near-identical checks, each subtly different about relative imports and about what counts as reaching past. That is the drift the published one exists to stop. ## Run the published check ```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_apprise", package="postulo_apprise", ) ``` Keep what is particular to this plugin — that the four names it asks of the surface are on `__all__` rather than merely reachable, since `__all__` is what the promise is made about. ## Also - Pin the core to `1d6cdd7e0` or later, so `postulo.plugins.testing` is there to import.

tiagoagueda added the

enhancement

label

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

tiagoagueda referenced this issue from a commit

2026-09-21 15:26:55 +00:00

Run Postulo's surface check instead of a copy of it

tiagoagueda closed this issue

2026-09-21 15:26:55 +00:00