glpi-python-client 0.4.3__tar.gz → 0.5.0__tar.gz

{glpi_python_client-0.4.3 → glpi_python_client-0.5.0}/.gitignore

@@ -37,3 +37,8 @@ docs/glpi_api_contract.json
 # Coverage data: rewritten by every test run (and by the venv .pth hook).
 .coverage
 .coverage.*
+
+# One-shot live-instance probe scripts. They are standalone investigations
+# (a main() run by hand against preprod), not collected tests -- the findings
+# get written up in CHANGELOG.md, the scripts stay local.
+integration_tests/probe_*.py

{glpi_python_client-0.4.3 → glpi_python_client-0.5.0}/CHANGELOG.md

@@ -4,6 +4,361 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.5.0 — 2026-09-08
+
+### Fixed
+
+- **Deeply nested HTML raised `RecursionError` while a model was being
+  validated.** `markdownify` walks the parsed document recursively and
+  spends about two CPython frames per nesting level, so roughly 494 levels
+  exhausted the default 1000-frame limit — measured, and the same 494 for
+  `<div>`, `<p>`, `<blockquote>` and `<table><tr><td>`, 495 for
+  `<ul><li>`, which is what identifies the cost as per-level. An
+  unclosed tag counts too: `html.parser` does not auto-close `<p>` or
+  `<li>`, so `"<p>" * 5000` really is 5000 levels.
+
+  Because the converter was wired as a Pydantic `BeforeValidator`, the
+  failure landed inside `model_validate` — that is, inside `get_ticket` —
+  as a bare builtin from a library whose whole error surface is supposed
+  to derive from `GlpiError`.
+
+  `from_transport` now *attempts* the conversion and answers the
+  `RecursionError` by stripping the document to its text instead.
+  **It degrades, it never truncates, and it does not raise for depth**:
+  every character of prose the converting path would have produced also
+  appears in the degraded rendering.
+
+  Attempting it rather than predicting it is the whole design, and it
+  replaced a fixed `MAX_HTML_DEPTH = 200` bound that was wrong in both
+  directions. Too low, because the budget is not 1000 frames but whatever
+  is left of the stack when the conversion starts, and that belongs to
+  the caller — so the bound had to assume the worst and flattened every
+  body between 200 and the real cliff of about 494. Measured, a
+  300-level and a 400-level body now come back as **Markdown with their
+  links, emphasis and lists intact** where they used to come back as
+  plain text, with no error to notice and no way to ask for better. And
+  too fragile, because predicting the depth meant reproducing the
+  parser's idea of the tree: three rounds of adversarial review found
+  seven ways for that estimate to land *under* the real depth, each of
+  which sent a document to `markdownify` and into the very
+  `RecursionError` the bound existed to prevent.
+
+  Trying the conversion cannot be wrong about whether the conversion
+  fits. `MAX_HTML_DEPTH` and the scan behind it are gone; the constant
+  was introduced in this same unreleased cycle and never shipped.
+
+  Two consequences worth knowing. The outcome now depends on the caller's
+  remaining stack, so the same body can convert from one call site and
+  degrade from a deeper one — nothing is lost either way, but a caller
+  comparing two renderings of one body should know which knob moved it.
+  And a body too deep to convert now pays the failed attempt before it
+  degrades: measured, 2.0x to 2.6x the old cost at 600 and 5000 levels.
+  Ordinary bodies got *faster*, at 0.87x to 0.90x, because the scan they
+  used to pay for on every read is gone.
+
+  A document `html.parser` refuses outright — `<![FOO[`, an unknown
+  marked-section keyword, which `bs4` re-raises as
+  `ParserRejectedMarkup` — takes the same degraded path, where it used
+  to raise and give the caller none of their text.
+
+  Both halves were fuzzed against the real parser over 15000 documents,
+  with zero under-counts, zero over-counts and zero text losses. Getting
+  there took several rules that are not the obvious ones:
+
+  - A closing tag pops by name or is ignored — `bs4` pops nothing when no
+    element of that name is open, so `"<div></p>" * 600` really is 600
+    deep where a naive counter says 1.
+  - An attribute value may contain `<` and `>`, so
+    `'<div title="</div>">' * 600` also measured 0 against a real 600
+    until the scan learned to skip quoted values.
+  - A quote opens a value only as the first character after the `=`,
+    which is the parser's own rule, so `<p title=don't>` carries the
+    value `don't`. Reading that apostrophe as a quote printed the opening
+    tag verbatim at the reader — and an apostrophe needs no malice to
+    reach a French ticket body.
+  - `tagfind_tolerant` runs a tag *name* to whitespace, `/` or `>`, so
+    `<style=>` is an element named `style=` and never enters raw-text
+    mode; a self-closed `<script/>` does not either, because
+    `parse_starttag` enters it only on the branch that is not
+    self-closing. Reading either as raw text swallowed the rest of the
+    document: `"<style=>" + "<div>" * 600` measured 1 level against a
+    real 601 and raised.
+  - A declaration is text on neither path only when it is closed. A
+    `<!weird` left unterminated at end of input is flushed as character
+    data when the parser closes, so dropping it lost the tail of a body.
+  - An unclosed tag counts, a childless node still occupies a level, and
+    a bogus comment swallows the tags inside it.
+  - The degraded path had to be measured against the converting path
+    construct by construct rather than reasoned about. Three answers came
+    back the opposite way round: a `<script>`/`<style>` body is *kept*
+    (`markdownify`'s `strip=` removes an element's markup and still walks
+    its children), so is a `CDATA` body, and so is the inside of any
+    `<!`/`<?` construct the parser could not resolve.
+
+  What the degraded rendering does not reproduce, none of it prose: link
+  targets and image alt text, fenced-block and `<pre>` indentation,
+  `&nbsp;`-padded alignment, and a processing instruction's `<?`/`>`
+  delimiters, which survive as literal text.
+
+  Character references are resolved by the parser's rule rather than by
+  `html.unescape`, which implements HTML5's longest-known-*prefix* rule
+  and would rewrite a pasted URL: `?a=1&copyright=2` becomes
+  `?a=1©right=2` under `unescape` and is left alone by the parser. A
+  semicolon-less reference resolves only when its whole name is known.
+
+  The ceiling is 200 rather than 494 because the budget is not 1000
+  frames, it is whatever is left of the stack when conversion starts, and
+  that belongs to the caller. The package's own contribution is small,
+  and since conversion moved to the attribute it no longer depends on how
+  the record was fetched: measured, 5 frames below the caller when
+  `.content` is read — the same 5 whether the model came from
+  `model_validate` or from `client.get_ticket` — and 9 on the write path,
+  where the renderer runs inside `model_dump`. What is not small is an
+  application reading `.content` from inside a request handler or a
+  recursive walk. Converting a 200-level document peaks at a measured 412
+  frames, so it stays safe until the caller's own stack passes about
+  588 — and no document a human wrote nests 200 elements deep.
+
+  **`sys.setrecursionlimit` was considered and rejected.** It is
+  process-global state belonging to the application, not to a library the
+  application imported; and past what the C stack can hold it converts a
+  catchable `RecursionError` into a hard interpreter crash — on Windows,
+  an access violation with no traceback. It moves the cliff and makes
+  falling off it worse. The prohibition is asserted by
+  `testing/tests/test_raise_site_audit.py` rather than left as a comment
+  for the next person to weigh up again.
+
+- **Where a tag *ends* was read with start-tag rules, twice.** Both were
+  unbounded depth under-counts, which is the one direction the ceiling
+  exists to prevent, and both also deleted prose from the degraded path at
+  any depth.
+
+  `parse_endtag` falls back to `rawdata.find(">")`, so an end tag skips
+  nothing — CPython's own comment concedes the case: "this is not 100%
+  correct, since we might have things like `</tag attr=">">`". Reading one
+  with attribute rules made `'</x a="><div>">' * 600` measure **0**
+  against a real 600.
+
+  `locatestarttagend_tolerant` reaches a quoted value only through an
+  attribute *name*, and a name may itself begin with `=`. So in
+  `<div ="<p><p>">` the parser reads the name `="<p` and ends the tag at
+  the first `>`, where treating any `=` before a quote as a value
+  indicator swallowed the rest: `'<div ="' + "<p>" * 600` measured **1**
+  against a real 600.
+
+  The attribute pattern is now a sequence of attributes rather than a run
+  of permitted characters, and end tags have their own branch. The
+  attribute name carries the parser's own "starts after a quote,
+  whitespace or `/`" rule, which is load-bearing twice over: without it
+  `<div ="` reads as a value, *and* the pattern backtracks
+  catastrophically — a 400-byte `'<div a="' * 50` did not finish.
+
+- **A body of nothing but `<div a="` cost O(n²).** 32 KB took 6.6 s. `re`
+  restarts at every `<` where `html.parser` buffers an incomplete tag and
+  never looks back. No `>` anywhere means no element anywhere, so that is
+  now answered in constant time. The pattern's remaining non-linear
+  shapes turned out to be exponential rather than quadratic, and are gone
+  with the pattern itself — see the entry below.
+
+- **The markup scan imitated `html.parser` instead of using it, and was
+  wrong in five unbounded ways at once.** A third adversarial round found
+  that the pattern reproducing the parser's dispatch disagreed with the
+  parser on: a comment closing on `--\s*>` rather than only `-->`; `</
+  script>` ending raw text; `<![IGNORE[` opening a marked section; `</ div
+  foo>` being a bogus comment rather than an end tag; and `<a href=/>` —
+  an ordinary root-relative link — leaving the element *open*, because the
+  unquoted value swallows the `/`. Each made a document measure one level
+  deep where the real tree was hundreds, so `'<a href=/>' * 494` cleared
+  the ceiling and raised. Two further findings were cost: a run of
+  whitespace inside a failing tag made the attribute pattern backtrack as
+  `(a+)*`, and a 39-byte body took 20.8 s.
+
+  The pattern is gone. Depth, void-tag canonicalisation and the degraded
+  rendering now come from one pass of an `html.parser` subclass — the same
+  parser `bs4` uses, so this cannot be wrong about the parser and is not a
+  new dependency or a new risk. Every pathology `html.parser` has was
+  already in the pipeline: measured on the shapes that made the pattern
+  backtrack, the `markdownify` call costs what the scan costs, to within a
+  few per cent.
+
+  Three consequences beyond the five defects:
+
+  - **A derailed scan silently reinstated the `<br>` data loss fixed
+    below**, because the void-tag workaround read the same pattern.
+    Measured, `"<p>one<br>two</p><script>x</ script><p>three<br
+    />TAIL</p>"` lost `TAIL` outright, and `<img>` and `<hr>` lost their
+    tails the same way.
+  - **A document the parser rejects now degrades instead of raising.**
+    `<![FOO[` makes `_markupbase` raise `AssertionError` on the
+    interpreters where that keyword is unknown — 3.10 through 3.12.11 as
+    measured, no longer 3.12.14 — and `bs4` re-raises it as
+    `ParserRejectedMarkup`. Where it happens, the caller used to get a
+    `GlpiContentError` and none of their text, and now gets their words.
+
+  Note that `html.parser`'s reading of a *malformed* construct is not
+  stable across CPython patch releases: the same three builds disagree
+  about an unterminated `<script>`, a comment with no `-->` and an end
+  tag carrying a quoted `>`. The scan tracks the parser rather than a
+  snapshot of it, so the depth decision stays correct on every version,
+  but the exact text a broken construct contributes to a degraded body is
+  the interpreter's. Well-formed content is unaffected.
+  - **A processing instruction no longer leaves `<?` and `>` in the
+    degraded text.** The converting path prints the body alone, so this
+    does too.
+
+  Cost, end to end and on identical output: 0.77x to 1.52x of the previous
+  implementation on realistic bodies. The exponential shapes are flat: 39
+  bytes of the whitespace bomb went from 20.8 s to 0.12 ms, and 20 KB of
+  it costs 0.67 ms. The depth scan those defects were found in has since
+  been removed altogether — see the entry above — but the same parser now
+  backs the void-tag rewrite and the degraded renderer, which inherited
+  every one of the misreadings and the backtracking too.
+
+  The one shape where `html.parser` is worse than linear is a document
+  carrying no `>` at all, where `close()` advances a character at a time
+  and rescans the tail: 32 KB costs it 13 s. That is answered in constant
+  time by the guard already present for the pattern's own O(n²) on the
+  same input, and is unreachable from `from_transport`, which needs a `>`
+  to find an element at all.
+
+  Re-fuzzed against a ground-truth walk of the tree `bs4` really builds,
+  over an alphabet carrying every construct all three rounds raised —
+  including the four whose absence is why the previous 10.5M-document
+  corpus could not have found these: `-- >`, `</ script>`, `<![IGNORE[`
+  and runs of whitespace and quotes inside a tag. **470000 documents, 0
+  depth under-counts, 0 prose losses, 0 crashes**, plus 60000 hostile
+  documents through `from_transport` with nothing but `GlpiError`
+  escaping.
+
+- **`GlpiContentError` did not survive the write path.** Outbound
+  conversion runs in a `PlainSerializer`, and pydantic-core catches
+  everything a serializer raises and re-raises `PydanticSerializationError`
+  — a `ValueError`, not a `GlpiError`, with `__cause__` and `__context__`
+  both `None`. So on every `create_*`/`update_*` carrying a body,
+  `except GlpiError` did not fire and the underlying fault was
+  unrecoverable. The fault is now stashed as it is raised and restored
+  around `model_dump`, with its own `__cause__` intact; a serialisation
+  failure that is *not* content becomes `GlpiValidationError` rather than
+  being mislabelled.
+
+- **One field spelled two ways shadowed itself in `model_dump`.** Pydantic
+  consumes the first alias and `extra="allow"` files the rest as model
+  extras — and an extra named after a field is emitted *instead of* that
+  field, so the attribute reported one body and the object's own dump
+  reported the other. The redundant spelling is now dropped before
+  Pydantic resolves anything, and `content_html` is the first choice, so a
+  dump carrying both round-trips back to the raw body.
+
+  Worth knowing about the read models: `model_copy(update={"content": ...})`
+  — the 0.4.x spelling — updates **nothing**, because `content` is now a
+  `cached_property`. A caller redacting a body that way gets an object
+  whose `.content` still holds the original. Rewrite `content_html`, or
+  rebuild through `model_validate`.
+
+- **A body that used both spellings of `<br>` lost everything after the
+  second one.** `<p>line1<br>line2</p><p>para2<br />line4</p>` converted
+  to `line1  \nline2\n\npara2` — `line4` silently gone, no error, on the
+  ordinary conversion path.
+
+  The cause is in `beautifulsoup4` (measured on 4.14.3), not in
+  `markdownify`. Its `html.parser` builder auto-closes a bare `<br>` and
+  records the name in `already_closed_empty_element` so a later `</br>`
+  can be ignored as redundant; when no `</br>` arrives the entry just
+  stays. The next `<br />` reaches the builder as `handle_startendtag`,
+  opens a real element and closes it itself — and that close finds the
+  stale entry, treats the element as already closed, and leaves it open,
+  so every following sibling becomes a child of the `<br>`.
+  `markdownify`'s `convert_br` ignores an element's children, and the
+  text is gone. `get_text` walks children, which is why the tree looks
+  intact.
+
+  Note the paragraph in the example: the two spellings need not be near
+  each other, since a name once recorded poisons the rest of the
+  document. `<img>` and `<hr>` are the other two converters that discard
+  children and lost text the same way.
+
+  `from_transport` now writes self-closing void tags bare before
+  converting, which removes the `handle_startendtag` path where the
+  asymmetry lives. Both spellings already built the same node, so nothing
+  else moves: measured over 4000 fuzzed documents of each spelling alone,
+  not one output changed, and over 4000 mixing them, 102 recovered text
+  and none lost any. Only names in the void set are touched, and only in
+  real tag position — a `<div/>`, a `<br />` inside an attribute value, a
+  comment or a `<script>` body are all left alone.
+
+- **`GlpiModel` now recognises validation aliases when it captures unknown
+  keys.** `_capture_unknown_fields` runs before Pydantic resolves aliases
+  and compared incoming keys against field *names* only, so an aliased key
+  was diverted into `extra_payload` before its field could see it — HTTP
+  200, no warning, and the value silently `None`. Latent until this
+  release, which introduces the package's first alias.
+
+### Added
+
+- **`GlpiContentError`** — a new `GlpiError` leaf for a rich-text body
+  that could not be converted, in either direction, with the underlying
+  fault attached as `__cause__`. Exported from the package root and
+  documented in the API reference.
+
+  Content conversion previously sat outside the taxonomy altogether: a
+  parser fault escaped `except GlpiError` and reached the caller as a bare
+  builtin. The depth ceiling above means no ordinary input gets here, so
+  this is the backstop — including for the outbound direction, where
+  `markdown` has its own cliff at around 500 levels of list indentation.
+
+  Unlike `GlpiStatusError`, `GlpiValidationError` and `GlpiProtocolError`
+  it does **not** inherit `ValueError`. Those three carry it for
+  compatibility with releases that raised bare `ValueError` at the same
+  sites; there was never a `ValueError` at a conversion site, and a parser
+  exhausting the stack is not a value the caller got wrong. Same reasoning
+  as `GlpiTransportError`.
+
+- **`content_html` on the read models**, holding the wire value verbatim:
+  `GetTicket`, `GetFollowup`, `GetTicketTask`, `GetSolution`,
+  `GetKBArticleRevision`, and `GetKBArticle` (which also gains
+  `description_html`).
+
+### Changed (breaking)
+
+- **Read models convert to Markdown on first access instead of during
+  validation.** `content` is now a `functools.cached_property` over
+  `content_html`:
+
+  ```python
+  ticket = client.get_ticket(42)
+  ticket.content_html   # '<p>Printer is <strong>offline</strong></p>'
+  ticket.content        # 'Printer is **offline**'  (converted here, once)
+  ```
+
+  **Callers that read `.content` need no change.** The field carries the
+  validation alias `content`, so a GLPI payload and a hand-written
+  `GetTicket(content=...)` both still populate it, and `.content` still
+  returns Markdown. What changes is *when*.
+
+  Two things follow. A caller who wants only `id` and `date_mod` no longer
+  pays HTML-to-Markdown on every record of every page. And a body that
+  cannot be converted no longer takes its page-mates with it:
+  `TransportMixin._resource_list` builds every item of a page in one
+  comprehension, so one unconvertible record used to make the whole page
+  unreadable — the failure is now scoped to the record whose body is
+  actually read.
+
+  Write models (`Post*`, `Patch*`) are deliberately unchanged: they keep
+  the plain `content` field and convert eagerly, so a caller's own
+  Markdown is still checked where it was supplied, and there is no list
+  path on a write model to make lazy.
+
+  What does break: `content` is no longer in `GetTicket.model_fields`, and
+  `GetTicket(...).model_dump()` emits `content_html` holding HTML where it
+  used to emit `content` holding Markdown (`by_alias=True` gives a dump
+  keyed the way GLPI keys it).
+
+  One sharp edge comes with the cache. Assigning to `content_html` after
+  `.content` has been read leaves the stale Markdown in place, and so does
+  `model_copy(update={"content_html": ...})` — and neither equality,
+  `repr` nor any `model_dump` reveals it. Treat a read model as immutable
+  once validated, or rebuild it through `model_validate`.
+
 ## 0.4.3 — 2026-08-13
 
 ### Changed (breaking)
@@ -34,6 +389,31 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   database; without it `zoneinfo` resolves on Linux CI and raises on a
   developer machine.
 
+- **`changed_since` no longer assumes UTC.** An aware `datetime` now needs the
+  server's timezone and raises `GlpiValidationError` without it:
+
+  ```python
+  window = changed_since(last_run, tz=client.server_timezone)
+  ```
+
+  The bound this builds is compared against a naive server-local column, so
+  converting the caller's moment to UTC asked the server for a different one.
+  A 09:33 Paris timestamp became a `07:33` filter. East of UTC that only
+  re-reads a few hours on every sweep; west of it the bound moves *forward*
+  and modifications are skipped outright — four hours in New York, seven in
+  Los Angeles — and the size of the drift changes at each DST transition, so
+  a sync that looks correct in January starts losing rows in March.
+
+  The offset is now spent converting the value onto the server's clock and
+  then dropped, which is what the model serialiser already does on the way
+  out; the two halves had diverged by exactly the offset. Missing `tz` is
+  refused rather than defaulted for the same reason `server_timezone` has no
+  default: every guess is wrong somewhere, and being wrong here returns a
+  short result set rather than an error.
+
+  A `date`, an ISO string, or a naive `datetime` is unaffected and needs no
+  `tz` — a naive value already means the server's clock.
+
 - **Search endpoints now raise on a 4xx instead of returning `[]`.** The seven
   `search_*` helpers passed no `failure_message` to `_resource_list`, which
   skipped the status check entirely, so a 400, 401, 403 or 404 came back as an

{glpi_python_client-0.4.3 → glpi_python_client-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: glpi-python-client
-Version: 0.4.3
+Version: 0.5.0
 Summary: A typed Python client for GLPI ITSM APIs.
 Project-URL: Homepage, https://github.com/baraline/glpi_python_client
 Project-URL: Documentation, https://glpi-python-client.readthedocs.io/en/latest/
@@ -70,7 +70,11 @@ The goal is to let GLPI integrations work with domain objects instead of raw
 JSON payloads. The package exposes Pydantic models for tickets, users,
 followups, documents, locations, and related records, while converting GLPI
 HTML content into Markdown for Python-side workflows and rendering Markdown
-back to HTML for outgoing payloads.
+back to HTML for outgoing payloads. On a response model that conversion is
+lazy — `.content` converts on first read and caches, so listing records
+costs nothing per body — and it degrades to plain text rather than failing
+on pathologically nested HTML. See
+[Rich-text content](https://glpi-python-client.readthedocs.io/en/latest/user_guide.html#content-conversion).
 
 It currently focuses on ticket-centric workflows and exposes two high-level
 clients built on top of the GLPI v2 REST API:

{glpi_python_client-0.4.3 → glpi_python_client-0.5.0}/README.md

@@ -12,7 +12,11 @@ The goal is to let GLPI integrations work with domain objects instead of raw
 JSON payloads. The package exposes Pydantic models for tickets, users,
 followups, documents, locations, and related records, while converting GLPI
 HTML content into Markdown for Python-side workflows and rendering Markdown
-back to HTML for outgoing payloads.
+back to HTML for outgoing payloads. On a response model that conversion is
+lazy — `.content` converts on first read and caches, so listing records
+costs nothing per body — and it degrades to plain text rather than failing
+on pathologically nested HTML. See
+[Rich-text content](https://glpi-python-client.readthedocs.io/en/latest/user_guide.html#content-conversion).
 
 It currently focuses on ticket-centric workflows and exposes two high-level
 clients built on top of the GLPI v2 REST API:

{glpi_python_client-0.4.3 → glpi_python_client-0.5.0}/docs/api_reference.rst

@@ -27,11 +27,13 @@ from it, so neither wraps the other and the two cannot drift apart.
 Exceptions
 ----------
 
-Exceptions raised for a bad argument, an unexpected HTTP status, or an
-unusable response body derive from :class:`GlpiError`.
-:class:`GlpiStatusError`, :class:`GlpiValidationError` and
-:class:`GlpiProtocolError` also inherit :class:`ValueError` for backwards
-compatibility with releases that raised bare ``ValueError``.
+Exceptions raised for a bad argument, an unexpected HTTP status, an
+unusable response body, or content that cannot be converted derive from
+:class:`GlpiError`. :class:`GlpiStatusError`, :class:`GlpiValidationError`
+and :class:`GlpiProtocolError` also inherit :class:`ValueError` for
+backwards compatibility with releases that raised bare ``ValueError``;
+:class:`GlpiContentError` and :class:`GlpiTransportError` do not, because
+nothing was passed in wrongly in either case.
 
 Network-level faults (connection failures, DNS errors, timeouts) are
 raised as :class:`GlpiTransportError`, or its :class:`GlpiTimeoutError`
@@ -80,6 +82,55 @@ guide for the full picture, including which methods raise which type.
    :members:
    :show-inheritance:
 
+.. autoexception:: GlpiContentError
+   :members:
+   :show-inheritance:
+
+Rich-text content
+-----------------
+
+GLPI exchanges ticket, followup, task, solution and knowledge-base bodies
+as HTML. The package's surface is Markdown in both directions, but the two
+directions work differently, and the difference is visible.
+
+A **write** model (``Post*``, ``Patch*``) takes Markdown in ``content`` and
+renders it to HTML when the request is built. Nothing to think about.
+
+A **read** model (``Get*``) keeps two views of the same body:
+
+``content_html``
+   what GLPI sent, verbatim. Also accepts the wire spelling ``content`` on
+   construction.
+
+``content``
+   the same body as Markdown, converted on the first read and cached.
+   :class:`GetKBArticle` has ``description`` / ``description_html`` as
+   well.
+
+Reading ``.content`` is what a caller wants and what earlier releases
+returned, so no read-side code needs changing. What changed is *when* the
+conversion happens, which buys two things: listing records costs nothing
+per body, and a body that cannot be converted no longer stops the rest of
+its page being read.
+
+Very deeply nested HTML is the case worth knowing about.
+``markdownify`` walks the document recursively and runs out of stack at
+around 494 levels of nesting. The converter does not try to predict
+that: it attempts the conversion and, if the walk does not fit, strips
+tags instead. It degrades, it never truncates, and it does not raise:
+every character the normal rendering would have produced still appears.
+What is lost is structure rather than words — link targets and image alt
+text, code fencing and ``<pre>`` indentation, ``&nbsp;`` alignment.
+Because the budget is the stack left when the conversion starts, the
+same body can convert from one call site and degrade from a deeper one.
+Anything else that goes wrong in either direction raises
+:class:`GlpiContentError`.
+
+Because the conversion is cached on first read, a read model should be
+treated as immutable afterwards: assigning to ``content_html``, or
+``model_copy(update={"content_html": ...})``, leaves the cached Markdown
+in place. Rebuild through ``model_validate`` if you need to change it.
+
 Aggregated Models
 -----------------
 

{glpi_python_client-0.4.3 → glpi_python_client-0.5.0}/docs/development.md

@@ -82,7 +82,18 @@ python -m pytest
 - `glpi_python_client.models` contains typed request and response
   models.
 - `glpi_python_client.content` handles HTML/Markdown conversion for
-  ticket descriptions, followups, tasks, and solutions.
+  ticket descriptions, followups, tasks, solutions, knowledge-base
+  articles (`content` and `description`) and article revisions. It is
+  wired into the models by `models/api_schema/_content.py`, eagerly on
+  the write models and through a cached property on the read ones.
+  Inbound HTML too deep for `markdownify` to walk is tag-stripped
+  rather than parsed. The depth is not predicted: the conversion is
+  attempted and the `RecursionError` answered, because the budget is the
+  caller's remaining stack and no bound computed in advance can know it.
+  The module docstring carries the derivation and the rejected
+  alternatives (`sys.setrecursionlimit`, and a thread with a larger
+  stack, which needs the same global). The prohibition is enforced by
+  `testing/tests/test_raise_site_audit.py`, not just written down.
 - `glpi_python_client.testing` exposes `make_client` and
   `make_async_client` factories that produce in-memory clients with no
   real HTTP plumbing for downstream test suites, plus the shared

{glpi_python_client-0.4.3 → glpi_python_client-0.5.0}/docs/user_guide.rst

@@ -586,7 +586,11 @@ Knowledge base
 The knowledge base mixins map to ``/Knowledgebase``. Articles and
 categories expose the ``search_ / get_ / create_ / update_ / delete_``
 shape; comments are nested under an article; revisions are read-only.
-Article ``content`` and ``description`` accept and return Markdown. An
+Article ``content`` and ``description`` accept and return Markdown; on
+:class:`~glpi_python_client.GetKBArticle` they are properties over
+``content_html`` and ``description_html``, converted on first read -- see
+:ref:`content-conversion`, which matters here because searching the
+knowledge base returns whole article bodies. An
 article's ``categories`` association is read-only in the v2 GLPI contract,
 so the client sets it through a legacy fallback — see
 `Assigning categories`_.
@@ -1429,9 +1433,9 @@ Example output::
 -----------------
 
 Exceptions the client raises for a bad argument, an unexpected HTTP
-status, or an unusable response body derive from
-:class:`~glpi_python_client.GlpiError`, so one handler covers that part
-of the library surface:
+status, an unusable response body, or content it cannot convert derive
+from :class:`~glpi_python_client.GlpiError`, so one handler covers that
+part of the library surface:
 
 .. code-block:: python
 
@@ -1474,15 +1478,17 @@ The hierarchy lets you narrow as far as you need:
 .. code-block:: text
 
    GlpiError
-   ├── GlpiTransportError      reserved for the httpx transport swap;
-   │   └── GlpiTimeoutError    not raised yet -- see the note above
+   ├── GlpiTransportError      the request never produced a response
+   │   └── GlpiTimeoutError    GLPI was too slow
    ├── GlpiStatusError         GLPI answered with an unexpected status
    │   ├── GlpiAuthError       401 / 403
    │   ├── GlpiNotFoundError   404
    │   └── GlpiServerError     5xx (retried up to 3 attempts before it
    │                           reaches you)
    ├── GlpiValidationError     the client rejected your argument
-   └── GlpiProtocolError       GLPI answered 2xx with an unusable body
+   ├── GlpiProtocolError       GLPI answered 2xx with an unusable body
+   └── GlpiContentError        a rich-text body could not be converted
+                               between HTML and Markdown
 
 :class:`~glpi_python_client.GlpiStatusError` carries the diagnostics you
 usually want:
@@ -1505,6 +1511,73 @@ usually want:
    :class:`~glpi_python_client.GlpiProtocolError` also inherit
    :class:`ValueError`. Code written against earlier releases, which
    raised bare ``ValueError``, keeps working unchanged.
+   :class:`~glpi_python_client.GlpiContentError` and
+   :class:`~glpi_python_client.GlpiTransportError` do not inherit it:
+   there was never a bare ``ValueError`` at either kind of site, and
+   neither is a value the caller got wrong.
+
+.. _content-conversion:
+
+Rich-text content: Markdown in, Markdown out
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Ticket, followup, task, solution and knowledge-base bodies travel to GLPI
+as HTML. You work in Markdown in both directions and the package handles
+the translation, but the two directions are not symmetric and the
+difference shows up in the field names.
+
+Writing is the simple half: give ``content`` Markdown and it is rendered
+to HTML when the request is built.
+
+Reading gives you two views of the same body:
+
+.. code-block:: python
+
+   ticket = client.get_ticket(42)
+
+   ticket.content_html  # '<p>The printer is <strong>offline</strong>.</p>'
+   ticket.content       # 'The printer is **offline**.'
+
+``.content`` is what you want and what earlier releases gave you, so
+read-side code needs no change. What changed is *when* the conversion
+runs: on the first read of ``.content``, cached afterwards, rather than
+while the model is being built. Two things follow.
+
+Listing records is cheap. ``client.search_tickets()`` used to convert
+every body on the page whether or not you looked at one; now a search
+that only reads ``id`` and ``date_mod`` converts nothing at all.
+
+A body that cannot be converted no longer takes its page down with it.
+The whole page is built in one pass, so a single unconvertible record used
+to make its page-mates unreadable too. The failure is now scoped to the
+record whose body you actually read.
+
+.. note::
+
+   Deeply nested HTML is the case worth knowing about. The HTML-to-Markdown
+   converter walks the document recursively and exhausts the interpreter's
+   stack at around 494 levels of nesting. ``.content`` does not try to
+   predict that -- it attempts the conversion and, when the walk does not
+   fit, strips the tags instead. **It degrades, it never truncates, and it
+   does not raise**: every character the normal rendering would have
+   produced still appears, so a body never says less because of how deeply
+   it happened to nest. What you lose is structure,
+   not words — link targets and image alt text, code-block fencing and
+   ``<pre>`` indentation, and ``&nbsp;``-padded alignment. Anything else
+   that goes wrong raises
+   :class:`~glpi_python_client.GlpiContentError`.
+
+   Because the result is cached on first read, treat a read model as
+   immutable afterwards. Assigning to ``content_html`` -- or
+   ``model_copy(update={"content_html": ...})`` -- leaves the cached
+   Markdown in place, and nothing in ``repr``, ``==`` or ``model_dump``
+   will tell you. Rebuild through ``model_validate`` instead.
+
+Two smaller consequences, if you are upgrading from 0.4.x: ``content`` is
+no longer in ``GetTicket.model_fields``, and ``GetTicket(...).model_dump()``
+emits ``content_html`` holding HTML where it used to emit ``content``
+holding Markdown. Pass ``by_alias=True`` for a dump keyed the way GLPI
+keys it.
 
 Retry behaviour
 ~~~~~~~~~~~~~~~
@@ -1533,4 +1606,4 @@ most 2 POST requests.
 
 Search methods are deliberately tolerant: ``search_tickets`` and its
 siblings return an empty list rather than raising when GLPI rejects the
-query. Methods that fetch or mutate one specific record always raise.
+query. Methods that fetch or mutate one specific record always raise.