feat(content): a rewrite_link hook and embedded image helpers for the reader (0.4.3)

[baraline]

Why

A caller that mirrors memos into another system has to recognise the images a memo embeds and decide what they become, without parsing HTML or Markdown itself. EasyVista's editor keeps a pasted image as an attachment of the request and embeds it as <img src="@@EMBEDDED_IMAGE_PATH@@<DOCUMENT_ID>">. The reader wrote that as an ordinary image, which displays nowhere but in EasyVista.

What

• from_transport(..., rewrite_link=callback) calls the callback with a Link for each link and image met outside code. An image is offered before the link around it, which it names as enclosing_href, and an embedded image carries its document_id. The answer is written:
  • None: the reader's own output;
  • a str: literal text, escaped as a text node, so it cannot become markup;
  • a Link: replaces the target;
  • a Link with an empty href: drops a link (its content is kept), or writes an image as its text.
• Without the argument a read is unchanged, byte for byte. A test checks that across the whole round-trip corpus.
• The callback is held in a ContextVar. Threads and tasks each read with their own, and a read inside a callback has its own too.
• What the callback raises reaches the caller unchanged. It is carried past the reader's ValueError text fallback, which would otherwise take a callback's ValueError for markdownify's and quietly drop the body's formatting. An answer of another type raises TypeError.
• document_id_of(src) and document_image(document_id, alt=...). The second is spelled by the reader itself, so from_transport(to_transport(x)) == x.
• Link, RewriteLink and EasyvistaContentConverter.EMBEDDED_IMAGE_PREFIX are now exported.
• Docs (docs/content.rst) and CHANGELOG updated; the version is 0.4.3.

Measured on one instance on 2026-10-07: an image written that way through the API displays, both for an attachment pasted in the editor and for one uploaded with add_document. An upload's DOCUMENT_ID has a different shape from a pasted image's, and the accepted id characters cover both.

The GLPI twin is baraline/glpi_python_client#42 (0.6.3).

Verification

• test_rewrite_link.py: 208 tests.
• 21 mutants of the new guards, all caught.
• Full suite: 2304 passed, coverage 98.96%.
• mypy, ruff, the sync lint, the unasync check and sphinx -W all clean.

🤖 Generated with Claude Code

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.96%. Comparing base (071e867) to head (dc6ca7e).
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #10      +/-   ##
==========================================
+ Coverage   98.93%   98.96%   +0.03%     
==========================================
  Files          40       40              
  Lines        2617     2694      +77     
==========================================
+ Hits         2589     2666      +77     
  Misses         28       28              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.