README: tells authors to call postulo.plugins.http.client(), which the surface check refuses, and omits the distribution name from the rename steps #10

New issue

Closed

opened 2026-10-01 10:48:14 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-10-01 10:48:14 +00:00

Owner

Found on 2026-09-29 in a read-only review of postulo-helloworld at 19f0bcc29, reading the README against the code and tests it describes.

This is the repository people copy, and its README gives two instructions that the repository's own code contradicts. One names a module past the plugin surface in the sentence after the rule that forbids it. The other leaves a renamed copy unable to import.

1. `postulo.plugins.http.client()` is past the surface

Where: README.md:82-85, under "Rules worth keeping". Line 82 says "Import postulo.plugins.api and nothing else from Postulo."; line 84 says "Use postulo.plugins.http.client() for every request". The same sentence is in the wiki, Writing-a-plugin.md:332 (postulo.wiki at de1f52467).
What happens: client has been on postulo.plugins.api since postulo/postulo#229 (it is in api.__all__), and src/postulo_helloworld/notifier.py:11 already names it correctly as postulo.plugins.api.client(). An author who follows the README writes from postulo.plugins.http import client; tests/test_surface.py:39 then fails with "reaches past the plugin surface: ['postulo.plugins.http']" (checked by running assert_imports_only_the_surface from the core snapshot over a one-line package).
Why it matters: the two places an author reads, the README and the wiki, agree with each other and disagree with the check the same README tells them to keep. The likely outcomes are an allowed entry for a module that needs none, or a deleted test.
Fix: write postulo.plugins.api.client() in README.md:84, and in Writing-a-plugin.md:332 in the wiki.

#1 and #3 (both closed) moved the code and the test to the surface; this line of the README was left behind.

2. "Make it yours" does not mention the distribution name

Where: README.md:42-45 (steps 1 to 3); src/postulo_helloworld/__init__.py:27; pyproject.toml:2 and pyproject.toml:40; tests/test_surface.py:29.
What happens: step 1 says to "rename postulo_helloworld to your package" and step 3 to change the entry points. Nothing says to change [project] name, yet postulo-messages in step 4 requires it: core/messages_tool.py:83 (use) finds the package as the project's name with hyphens as underscores, under src/. Once the project is renamed, __version__ = version("postulo-helloworld") raises PackageNotFoundError on import, because that string is the old distribution's name and the line has no fallback (postulo-paperless, postulo-imap, postulo-dav and postulo-mcp each catch it). The comment above it, "the metadata is always there", holds only while the two names match. If the original postulo-helloworld happens to be installed beside the copy, nothing raises and the copy reports the wrong plugin's version instead.
Why it matters: the first thing a new author sees after following the steps is an import error from a line the steps never mention; on an instance the registry logs the plugin and skips it.
Fix: make step 1 list every place the name lives: [project] name and [tool.hatch.build.targets.wheel] packages in pyproject.toml, the string in __init__.py, and PACKAGE in tests/test_surface.py. Better, remove the string to forget: derive the version from the distribution that provides the package (importlib.metadata.packages_distributions()[__name__][0]), so a rename needs no edit there.

Done when

README.md and the wiki name postulo.plugins.api.client(), and a test in tests/test_surface.py fails if README.md mentions any postulo. module other than postulo.plugins.api and postulo.plugins.testing as something to import or call.
A test in tests/test_helloworld.py asserts that the name passed to version() in src/postulo_helloworld/__init__.py equals [project] name in pyproject.toml (or the string is gone), and step 1 of "Make it yours" names every file a rename touches.

Found on 2026-09-29 in a read-only review of postulo-helloworld at 19f0bcc29, reading the README against the code and tests it describes. This is the repository people copy, and its README gives two instructions that the repository's own code contradicts. One names a module past the plugin surface in the sentence after the rule that forbids it. The other leaves a renamed copy unable to import. ## 1. `postulo.plugins.http.client()` is past the surface - **Where:** `README.md:82-85`, under "Rules worth keeping". Line 82 says "**Import `postulo.plugins.api` and nothing else from Postulo.**"; line 84 says "**Use `postulo.plugins.http.client()` for every request**". The same sentence is in the wiki, `Writing-a-plugin.md:332` (postulo.wiki at de1f52467). - **What happens:** `client` has been on `postulo.plugins.api` since postulo/postulo#229 (it is in `api.__all__`), and `src/postulo_helloworld/notifier.py:11` already names it correctly as `postulo.plugins.api.client()`. An author who follows the README writes `from postulo.plugins.http import client`; `tests/test_surface.py:39` then fails with "reaches past the plugin surface: ['postulo.plugins.http']" (checked by running `assert_imports_only_the_surface` from the core snapshot over a one-line package). - **Why it matters:** the two places an author reads, the README and the wiki, agree with each other and disagree with the check the same README tells them to keep. The likely outcomes are an `allowed` entry for a module that needs none, or a deleted test. - **Fix:** write `postulo.plugins.api.client()` in `README.md:84`, and in `Writing-a-plugin.md:332` in the wiki. #1 and #3 (both closed) moved the code and the test to the surface; this line of the README was left behind. ## 2. "Make it yours" does not mention the distribution name - **Where:** `README.md:42-45` (steps 1 to 3); `src/postulo_helloworld/__init__.py:27`; `pyproject.toml:2` and `pyproject.toml:40`; `tests/test_surface.py:29`. - **What happens:** step 1 says to "rename `postulo_helloworld` to your package" and step 3 to change the entry points. Nothing says to change `[project] name`, yet `postulo-messages` in step 4 requires it: `core/messages_tool.py:83` (`use`) finds the package as the project's name with hyphens as underscores, under `src/`. Once the project is renamed, `__version__ = version("postulo-helloworld")` raises `PackageNotFoundError` on import, because that string is the old distribution's name and the line has no fallback (`postulo-paperless`, `postulo-imap`, `postulo-dav` and `postulo-mcp` each catch it). The comment above it, "the metadata is always there", holds only while the two names match. If the original `postulo-helloworld` happens to be installed beside the copy, nothing raises and the copy reports the wrong plugin's version instead. - **Why it matters:** the first thing a new author sees after following the steps is an import error from a line the steps never mention; on an instance the registry logs the plugin and skips it. - **Fix:** make step 1 list every place the name lives: `[project] name` and `[tool.hatch.build.targets.wheel] packages` in `pyproject.toml`, the string in `__init__.py`, and `PACKAGE` in `tests/test_surface.py`. Better, remove the string to forget: derive the version from the distribution that provides the package (`importlib.metadata.packages_distributions()[__name__][0]`), so a rename needs no edit there. ## Done when - `README.md` and the wiki name `postulo.plugins.api.client()`, and a test in `tests/test_surface.py` fails if `README.md` mentions any `postulo.` module other than `postulo.plugins.api` and `postulo.plugins.testing` as something to import or call. - A test in `tests/test_helloworld.py` asserts that the name passed to `version()` in `src/postulo_helloworld/__init__.py` equals `[project] name` in `pyproject.toml` (or the string is gone), and step 1 of "Make it yours" names every file a rename touches.

tiagoagueda added this to the 0.6.0 milestone

2026-10-01 10:48:14 +00:00

tiagoagueda added the

documentation

label

2026-10-01 10:48:14 +00:00

tiagoagueda referenced this issue

2026-10-19 07:09:04 +00:00

Fix the open bug and security issues: source parser, release gate, notifier path, lock and CI #15

tiagoagueda referenced this issue from a commit

2026-11-11 22:58:46 +00:00

Correct the README to the plugin surface, and list every place a rename touches