feat(content): a rewrite_link hook and document image helpers for the reader (0.6.3)

[baraline]

Why

A caller that mirrors bodies into another system has to recognise the documents a body embeds or links, and decide what they become, without parsing HTML or Markdown itself. GLPI's editor embeds a pasted image from front/document.send.php?docid=N, inside a link to the same URL. The reader wrote that as a linked image, which displays nowhere but in GLPI.

This is the twin of baraline/easyvista_python_client#10 (0.4.3): the same hook, with each ITSM's own embedded form.

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. A Link whose URL names a document carries its document_id; in GLPI that covers links as well as images. 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. That is how the editor's link around an image collapses.
• 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, so threads, tasks and nested reads each have their own.
• What the callback raises reaches the caller unchanged, carried past the ValueError text fallback. The raise-site audit allows the private carrier and that re-raise, since the exception is the caller's own.
• document_id_of(url) accepts a relative, rooted or absolute URL, under any path, with exactly one docid of ASCII digits greater than zero.
• document_image(document_id, alt=..., itemtype=..., items_id=...) writes the editor's link-wrapped image, spelled by the reader itself. A bad argument raises GlpiValidationError.
• Link and RewriteLink are now exported.
• User guide and CHANGELOG updated; the version is 0.6.3 (pyproject, __version__, skills).

Verification

• test_rewrite_link.py: 219 tests.
• 33 mutants of the new guards, all caught after one URL case was added.
• Full suite: 1989 passed, coverage 97.93%.
• mypy (strict), ruff, 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 97.92%. Comparing base (3d3b707) to head (7b88c33).
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #42      +/-   ##
==========================================
+ Coverage   97.86%   97.92%   +0.05%     
==========================================
  Files          90       90              
  Lines        3380     3476      +96     
==========================================
+ Hits         3308     3404      +96     
  Misses         72       72              

☔ 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.