fix(content): port easyvista-python-client's reader fixes, and keep blocks inside u/mark/ins (0.6.1)

[baraline]

Why

easyvista-python-client carries this package's 0.6.0 converter plus fifteen reader fixes, so the same HTML could read as different Markdown through the two packages. Some of those differences change what a body shows:

• image alt text lost its escapes;
• a "!" before a link turned it into an image;
• , and were dropped;
• a line opening with ~~~ became a code fence;
• some shapes read in quadratic time.

A colspan or start the converter could not read as a number failed the whole body.

A review of the port found one more problem, which this branch also fixes. Fix 11 kept , and raw even around blocks, so a table inside one read as pipe text, a list or a heading read as Markdown source, and

...

left a fence open over the rest of the body. Separately, a lone surrogate in a write model's Markdown failed the whole create or update.

What

• Reader (content/conversion.py): the fifteen fixes, plus a correction to fix 11. A , or holding a block is dropped and its blocks kept, as 0.6.0 read them; inside a table cell or a heading it stays. The module now differs from easyvista-python-client 0.4.1's only in names, error messages, docstrings and that package's optional-dependency import guard. The converter's writing is unchanged.
• Write models: a lone surrogate is sent as U+FFFD, as CommonMark replaces a NUL; the rest of the body keeps its Markdown. GlpiContentConverter.to_transport called directly still raises.
• Tests:
  • one regression section per fix;
  • the fix-11 correction, for every block kind, the stray fence, nested tags and the one-line controls;
  • one test each for four guards no test caught (a second "<" before a space, a header cell, an anchor without href, an item numbered 10 or more);
  • a count of the block walk's checks;
  • growth tests replacing the 20-second budgets;
  • seeded property tests;
  • the surrogate write path.
• Dependency bounds aligned with easyvista-python-client[content].
• Docs:
  • the user guide's rich-text section: what each element becomes, what survives a round trip, the known holes;
  • corrected claims: start values, any ValueError degrading to text, the write-model rule (stripped, not verbatim), the skills' depth notes, and the text shown after a body's last ">".

Verification

• Every fix's tests fail on the converter before it, and reverting any one guard fails at least one test (mutation runs in disposable copies). The fix-11 correction's tests fail 40 of 42 on easyvista-python-client 0.4.0's converter.
• Parity:
  • The two conversion modules' ASTs are identical once names, messages, docstrings and the import guard are set aside.
  • Differential: 22,623 inputs (both packages' recorded test bodies plus a seeded fuzz corpus) through both converters with the same libraries, 6 operations each: 135,738 comparisons, 0 mismatches.
  • Against the previous head, only reads of bodies holding , or change. None that displayed the same and was a fixed point stopped being either, and 200 that were wrong became right.
• Gates:
  • pytest -m "not integration" with coverage: 1761 passed, 97.87%;
  • ruff check, ruff format --check, mypy strict, unasync_build.py --check;
  • sphinx -E -W, built offline.
• Every documented behaviour was re-checked on CPython 3.12 and 3.13.

Known follow-ups (from the review; all Minor)

• , and round blocks remain a documented hole, unchanged since 0.6.0.
• The converter reads start with isdecimal; a browser reads " 3", "+3" or "3abc" as 3. This is documented.
• A lone surrogate in a non-content field still fails in the HTTP library's JSON encoding.
• The cmarkgfm floor differs from easyvista-python-client's (writer only).
• An inline wrapper (<span>, <font>, and now a dropped <u>/<mark>/<ins>) round a list, followed by inline text, reads that text into the list's last item. This is markdownify's general behaviour, the same on every tree; the fix belongs in the list converter's next-sibling handling.
• A data-glpi-block / data-ev-block attribute already present in stored HTML is trusted by the block walk. Only hand-made or sanitiser-kept HTML carries one; clear it on read.
• No test pins that the block walk runs after nested tables are flattened (formatting-only effect on a rare shape).
• The documented exceptions to the second-cycle fixed point are still too narrow: two adjacent lists separated by anything that reads as nothing (a comment, an empty <div>) also change on the second cycle.
• The start-value docs omit a negative start, a full-width digit, and a start of 10 or more digits, which reads as a paragraph.

Twin PR: baraline/easyvista_python_client#8

🤖 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.86%. Comparing base (8cb46fc) to head (655d153).
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #40      +/-   ##
==========================================
+ Coverage   97.64%   97.86%   +0.22%     
==========================================
  Files          90       90              
  Lines        3313     3377      +64     
==========================================
+ Hits         3235     3305      +70     
+ Misses         78       72       -6     

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