glpi-python-client 0.6.1__tar.gz → 0.6.3__tar.gz

{glpi_python_client-0.6.1 → glpi_python_client-0.6.3}/CHANGELOG.md

@@ -4,6 +4,49 @@ 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.6.3 — 2026-10-08
+
+A patch release of the converter's reading: a caller can recognise the
+documents a body embeds or links and decide, link by link, what a read
+writes. Without the new argument a read is unchanged, byte for byte; writing
+is unchanged. `easyvista-python-client` 0.4.3 adds the same hook.
+
+### Added
+
+- **`from_transport(..., rewrite_link=callback)`.** The callback is called with
+  a `Link` for each link and image the read meets outside code -- an image
+  before the link around it, with that link's `enclosing_href` -- and its
+  answer is written: `None` keeps the reader's output, a `str` is written as
+  literal text, a `Link` replaces the target (an empty `href` drops a link and
+  keeps its content, or writes an image as its text). The callback is held in
+  a context variable, so concurrent reads each use their own. What it raises
+  reaches the caller unchanged; a `ValueError` is not taken for markdownify's
+  and answered with the text fallback.
+- **`Link` and `RewriteLink`**, exported from `glpi_python_client.content`.
+- **`GlpiContentConverter.document_id_of(url)`** returns the document id a URL
+  to `front/document.send.php` names (relative, rooted or absolute, one
+  `docid` in any position), and **`document_image(document_id, alt=...,
+  itemtype=..., items_id=...)`** the Markdown of an embedded document image as
+  GLPI's editor writes one -- the image inside a link to the same URL --
+  spelled as the reader spells it. A `Link` whose URL names a document carries
+  its `document_id`.
+
+## 0.6.2 — 2026-10-07
+
+A patch release of the converter's writing: a link written into GLPI opens in
+a new window. Reading is unchanged. `easyvista-python-client` 0.4.2 makes the
+same change, so the two converters still write the same HTML.
+
+### Changed
+
+- **Every link `to_transport` writes carries `target="_blank"
+  rel="noopener noreferrer"`**, as a link written in GLPI's own editor carries
+  `target="_blank"`. Without it a link opens in place of the page showing it.
+  Write models render through the same function, so a followup, task,
+  solution or ticket body written through them carries it too. Reading
+  ignores both attributes, so `from_transport(to_transport(m))` is unchanged
+  for every link.
+
 ## 0.6.1 — 2026-10-02
 
 The reader now gives the same Markdown as `easyvista-python-client` 0.4.1,

{glpi_python_client-0.6.1 → glpi_python_client-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: glpi-python-client
-Version: 0.6.1
+Version: 0.6.3
 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/

{glpi_python_client-0.6.1 → glpi_python_client-0.6.3}/docs/user_guide.rst

@@ -1838,7 +1838,9 @@ becomes:
 
 Writing, your Markdown is rendered by cmark-gfm. A newline is a line break,
 GFM tables work, and raw HTML passes through, so put a placeholder such as
-``<login>`` in backticks. A write model keeps your Markdown as written,
+``<login>`` in backticks. A link opens in a new window, as a link written in
+GLPI's editor does: each ``<a href>`` the renderer writes carries
+``target="_blank" rel="noopener noreferrer"``, which reading ignores. A write model keeps your Markdown as written,
 stripped at both ends, unless it starts with ``<`` and holds an HTML
 element anywhere, in which case it is read as HTML. Stripping unindents the
 first line of a body that opens with an indented code block, which then
@@ -1910,6 +1912,63 @@ text.
 Prefer a patched interpreter anyway: the guard covers the converter's input,
 and the CPython fix covers the parser itself.
 
+Document images, and rewriting links as they are read
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+GLPI's editor keeps an image pasted into a body as a document and embeds it
+from the page that serves documents, inside a link to the same URL:
+``<a href="/front/document.send.php?docid=N&itemtype=Ticket&items_id=T">``
+around ``<img src="...same URL...">``. Without a callback the reader writes
+that as any linked image, ``[![alt](url)](url)``, which displays nowhere but in
+GLPI. Three helpers let a caller do better.
+
+``GlpiContentConverter.document_id_of(url)`` returns the document id a URL
+names -- ``front/document.send.php`` with one ``docid``, relative, rooted or
+absolute, under any path -- or ``None``. ``document_image(document_id,
+alt=..., itemtype=..., items_id=...)`` returns the Markdown of the editor's
+form, spelled exactly as the reader spells it, so ``to_transport`` writes it
+and ``from_transport`` reads it back unchanged. Its URL is rooted, as the
+editor wrote it on the instance measured.
+
+``from_transport(..., rewrite_link=callback)`` calls ``callback`` with a
+:class:`~glpi_python_client.content.Link` for each link and each image it
+meets outside code, an image before the link around it. A ``Link`` carries the
+``href`` (an image's ``src``), the ``text`` (an image's ``alt``), the
+``title``, whether it is an ``image``, the ``document_id`` its URL names, and
+for an image inside a link that link's ``enclosing_href``. What the callback
+answers is written:
+
+* ``None``: what the reader writes without a callback;
+* a ``str``: that text, literally -- escaped as any text the body displays, so
+  it cannot become markup;
+* a ``Link``: a link's ``href`` and ``title`` around the link's content as
+  read, or an image's ``href`` as its ``src``, ``text`` as its ``alt`` and
+  ``title``;
+* a ``Link`` with an empty ``href``: a link is dropped and its content kept, an
+  image is written as its ``text``.
+
+.. code-block:: python
+
+    from glpi_python_client.content import GlpiContentConverter, Link
+
+    def name_documents(link: Link) -> Link | str | None:
+        if link.document_id is None:
+            return None
+        if link.image:
+            return f"[document {link.document_id}]"
+        return Link("")  # the editor's link around it: keep only its content
+
+    GlpiContentConverter.from_transport(body, rewrite_link=name_documents)
+
+The callback is held for the duration of one read, per thread and per task,
+so concurrent reads each use their own, and a read inside a callback has its
+own too. What the callback raises reaches the caller unchanged -- a
+``ValueError`` included, which the reader would otherwise take for one of
+markdownify's and answer by reading the body as its text. An answer of any
+other type raises ``TypeError``. It is not called for a value passed through
+as Markdown (``plain_text_is_markdown=True``), nor for a body read as its text.
+``easyvista-python-client`` 0.4.3 carries the same hook.
+
 It is not a sanitiser
 ^^^^^^^^^^^^^^^^^^^^^
 

{glpi_python_client-0.6.1 → glpi_python_client-0.6.3}/glpi_python_client/__init__.py

@@ -131,7 +131,7 @@ from glpi_python_client.rsql import (
     date_window,
 )
 
-__version__ = "0.6.1"
+__version__ = "0.6.3"
 
 __all__ = [
     "AsyncGlpiClient",

{glpi_python_client-0.6.1 → glpi_python_client-0.6.3}/glpi_python_client/_async/_testing.py

@@ -127,10 +127,10 @@ class TransportRecorder:
             )
             return FakeResponse(status_code=self._delete_status, payload={})
 
-        client._get_request = _get  # type: ignore[method-assign, assignment]
-        client._post_request = _post  # type: ignore[method-assign, assignment]
-        client._update_request = _patch  # type: ignore[method-assign, assignment]
-        client._delete_request = _delete  # type: ignore[method-assign, assignment]
+        client._get_request = _get  # type: ignore[method-assign, assignment, unused-ignore]
+        client._post_request = _post  # type: ignore[method-assign, assignment, unused-ignore]
+        client._update_request = _patch  # type: ignore[method-assign, assignment, unused-ignore]
+        client._delete_request = _delete  # type: ignore[method-assign, assignment, unused-ignore]
 
 
 class FailingTransportRecorder(TransportRecorder):

{glpi_python_client-0.6.1 → glpi_python_client-0.6.3}/glpi_python_client/_sync/_testing.py

@@ -127,10 +127,10 @@ class TransportRecorder:
             )
             return FakeResponse(status_code=self._delete_status, payload={})
 
-        client._get_request = _get  # type: ignore[method-assign, assignment]
-        client._post_request = _post  # type: ignore[method-assign, assignment]
-        client._update_request = _patch  # type: ignore[method-assign, assignment]
-        client._delete_request = _delete  # type: ignore[method-assign, assignment]
+        client._get_request = _get  # type: ignore[method-assign, assignment, unused-ignore]
+        client._post_request = _post  # type: ignore[method-assign, assignment, unused-ignore]
+        client._update_request = _patch  # type: ignore[method-assign, assignment, unused-ignore]
+        client._delete_request = _delete  # type: ignore[method-assign, assignment, unused-ignore]
 
 
 class FailingTransportRecorder(TransportRecorder):

{glpi_python_client-0.6.1 → glpi_python_client-0.6.3}/glpi_python_client/content/__init__.py

@@ -6,6 +6,10 @@ payloads and the package's canonical Markdown and typed-record representations.
 
 from __future__ import annotations
 
-from glpi_python_client.content.conversion import GlpiContentConverter
+from glpi_python_client.content.conversion import (
+    GlpiContentConverter,
+    Link,
+    RewriteLink,
+)
 
-__all__ = ["GlpiContentConverter"]
+__all__ = ["GlpiContentConverter", "Link", "RewriteLink"]

{glpi_python_client-0.6.1 → glpi_python_client-0.6.3}/glpi_python_client/content/conversion.py

@@ -40,9 +40,12 @@ import re
 import string
 import unicodedata
 from collections.abc import Callable, Iterator, Mapping, MutableMapping, Sequence
+from contextvars import ContextVar
+from dataclasses import dataclass
 from functools import cached_property
 from html import escape, unescape
 from typing import Any, cast
+from urllib.parse import parse_qs, urlsplit
 
 import cmarkgfm
 import mdformat_tables
@@ -59,7 +62,7 @@ from mdformat.renderer import (
 )
 from mdformat.renderer.typing import Postprocess
 
-from glpi_python_client._errors import GlpiContentError
+from glpi_python_client._errors import GlpiContentError, GlpiValidationError
 
 #: Element names that make a ``<...>`` sequence markup rather than text: the
 #: HTML5 elements, then the obsolete ones old editors and mail clients write.
@@ -363,6 +366,97 @@ def _title(title: str) -> str:
     return ' "' + re.sub(r'[\\"]', r"\\\g<0>", title) + '"' if title else ""
 
 
+#: The page GLPI serves a document from. Its editor embeds a pasted image as
+#: ``<img src=".../front/document.send.php?docid=N&itemtype=Ticket&items_id=T">``
+#: inside a link to the same URL, and links an attachment the same way.
+_DOCUMENT_PAGE = "front/document.send.php"
+
+#: A document id, as the ``docid`` parameter carries one: ASCII digits only,
+#: since ``int`` also reads other scripts' digits.
+_DOCUMENT_ID = re.compile(r"[0-9]{1,18}")
+
+#: An item type, as ``itemtype`` names one: a PHP class name.
+_ITEMTYPE = re.compile(r"[A-Za-z_][A-Za-z0-9_\\]{0,99}")
+
+
+@dataclass(frozen=True, slots=True)
+class Link:
+    """A link or an image the reader meets, as a ``rewrite_link`` callback sees it.
+
+    Attributes
+    ----------
+    href : str
+        An ``<a>``'s ``href`` or an ``<img>``'s ``src``, character references
+        decoded.
+    text : str
+        An ``<a>``'s displayed text or an ``<img>``'s ``alt``, whitespace
+        collapsed.
+    title : str
+        The ``title``, or ``""``.
+    image : bool
+        ``True`` for an ``<img>``.
+    document_id : int or None
+        For a link or an image whose URL is GLPI's document page with a
+        ``docid`` (:meth:`GlpiContentConverter.document_id_of`), that id;
+        ``None`` otherwise.
+    enclosing_href : str or None
+        For an ``<img>`` inside a link, that link's ``href``; ``None``
+        otherwise. The image is read before the link around it.
+    """
+
+    href: str
+    text: str = ""
+    title: str = ""
+    image: bool = False
+    document_id: int | None = None
+    enclosing_href: str | None = None
+
+
+#: A ``rewrite_link`` callback: called with each link and image a read meets,
+#: outside code. ``None`` keeps what the reader writes without one. A ``str`` is
+#: written instead, as literal text. A :class:`Link` is written in the reader's
+#: own spelling: a link's ``href`` and ``title``, around the link's content as
+#: read; an image's ``href`` as its ``src``, ``text`` as its ``alt`` and
+#: ``title``. An empty ``href`` drops a link and keeps its content, and writes an
+#: image as its ``text``.
+RewriteLink = Callable[[Link], "Link | str | None"]
+
+_REWRITE: ContextVar[RewriteLink | None] = ContextVar("rewrite_link", default=None)
+"""The callback of the read in progress. A context variable rather than state
+on the shared converter: each thread and each task reads with its own."""
+
+
+class _CallbackRaised(Exception):
+    """What a ``rewrite_link`` callback raised, carried past the reader's fallbacks.
+
+    The reader answers a ``ValueError`` by reading the body as its text; a
+    callback's own ``ValueError`` must not pass for markdownify's and quietly
+    cost the body its formatting.
+    """
+
+    def __init__(self, error: Exception) -> None:
+        super().__init__(error)
+        self.error = error
+
+
+def _rewritten(link: Link) -> Link | str | None:
+    """Ask the read's callback about ``link``; ``None`` when there is none."""
+
+    rewrite = _REWRITE.get()
+    if rewrite is None:
+        return None
+    try:
+        answer: object = rewrite(link)  # typed as what it is, not what it should be
+    except Exception as exc:
+        raise _CallbackRaised(exc) from exc
+    if answer is None or isinstance(answer, (Link, str)):
+        return answer
+    error = TypeError(
+        f"rewrite_link returned {type(answer).__name__}; expected Link, str or None"
+    )
+    raise _CallbackRaised(error)
+
+
 class _Converter(MarkdownConverter):
     """``markdownify``, with what CommonMark and the reader's glue need on top.
 
@@ -520,15 +614,34 @@ class _Converter(MarkdownConverter):
         body, _, tail = rest.rpartition("```")
         return f"{head}{fence}{body}{fence}{tail}"
 
+    def _literal(self, text: str, parent_tags: set[str]) -> str:
+        """``text`` escaped as the reader escapes a text node: displayed as it is."""
+
+        return self.escape(" ".join(text.split()), parent_tags)
+
     def convert_a(self, el: Tag, text: str, parent_tags: set[str]) -> str:
         """A link; ``<url>`` when its text is its URL and reads back unchanged."""
 
+        if "_noformat" in parent_tags:
+            return text
         href = str(el.get("href") or "")
+        title = str(el.get("title") or "")
+        answer = _rewritten(
+            Link(
+                href,
+                " ".join(el.get_text().split()),
+                title,
+                document_id=GlpiContentConverter.document_id_of(href),
+            )
+        )
+        if isinstance(answer, str):
+            return self._literal(answer, parent_tags)
+        if answer is not None:
+            href, title = answer.href, answer.title
         edges = _EDGES.fullmatch(text)
-        if "_noformat" in parent_tags or not href or edges is None or not edges[2]:
+        if not href or edges is None or not edges[2]:
             return text
         before, inner, after = edges.groups()
-        title = str(el.get("title") or "")
         if not title and el.get_text() == href and _AUTOLINK.fullmatch(href):
             return f"{before}<{href}>{after}"
         return f"{before}[{inner}]({_destination(href)}{_title(title)}){after}"
@@ -536,12 +649,37 @@ class _Converter(MarkdownConverter):
     def convert_img(self, el: Tag, text: str, parent_tags: set[str]) -> str:
         """An image, wherever it is: a cell or a heading holds one too."""
 
+        src = str(el.get("src") or "")
         alt = " ".join(str(el.get("alt") or "").split())
+        title = str(el.get("title") or "")
+        if "_noformat" not in parent_tags:
+            around = el.find_parent("a")
+            answer = _rewritten(
+                Link(
+                    src,
+                    alt,
+                    title,
+                    image=True,
+                    document_id=GlpiContentConverter.document_id_of(src),
+                    enclosing_href=(
+                        None if around is None else str(around.get("href") or "")
+                    ),
+                )
+            )
+            if isinstance(answer, str):
+                return self._literal(answer, parent_tags)
+            if answer is not None and not answer.href:
+                return self._literal(answer.text, parent_tags)
+            if answer is not None:
+                src, alt, title = (
+                    answer.href,
+                    " ".join(answer.text.split()),
+                    answer.title,
+                )
         alt = str(self._inherited("escape")(alt, parent_tags))
         if alt.startswith("^") and "_noformat" not in parent_tags:
             alt = "\\" + alt  # cmark-gfm reads "![^" as "!" and a link
-        src = _destination(str(el.get("src") or ""))
-        return f"![{alt}]({src}{_title(str(el.get('title') or ''))})"
+        return f"![{alt}]({_destination(src)}{_title(title)})"
 
 
 class _Node(RenderTreeNode):
@@ -715,12 +853,27 @@ def html_to_markdown(html: str) -> str:
     return str(_FORMATTER.render(_CONVERTER.convert_soup(soup))).strip()
 
 
+#: A link as cmark-gfm writes one: an ``href``, an optional ``title``, nothing else.
+_RENDERED_LINK = re.compile(r'<a href="[^"]*"(?: title="[^"]*")?>')
+
+#: What GLPI's own editor writes on a link, so that it opens in a new window
+#: rather than in place of the page showing it. ``noreferrer`` too, as
+#: ``easyvista-python-client``'s twin writes, so the two render alike.
+_NEW_WINDOW = ' target="_blank" rel="noopener noreferrer"'
+
+
 def markdown_to_html(markdown: str) -> str:
-    """Render Markdown as HTML: CommonMark with GFM tables, through cmark-gfm."""
+    """Render Markdown as HTML: CommonMark with GFM tables, through cmark-gfm.
+
+    Every link opens in a new window, the way a link written in GLPI's editor
+    does: ``target="_blank" rel="noopener noreferrer"`` is added to each link
+    cmark-gfm writes. Reading ignores both attributes.
+    """
 
     html: str = cmarkgfm.markdown_to_html_with_extensions(
         markdown, options=_RENDER_OPTIONS, extensions=["table"]
     )
+    html = _RENDERED_LINK.sub(lambda link: link.group(0)[:-1] + _NEW_WINDOW + ">", html)
     return html.strip()
 
 
@@ -737,11 +890,45 @@ def _text_of(html: str) -> str:
     return "\n".join(line for line in lines if line)
 
 
+def _converted(content: str) -> str:
+    """Read HTML, falling back to its text where the conversion cannot."""
+
+    try:
+        try:
+            return html_to_markdown(content)
+        except (RecursionError, ValueError):  # ValueError: markdownify's
+            # int() of a colspan or start such as "²" or 5,000 digits
+            return html_to_markdown(_plain_text_html(_text_of(content)))
+        except ParserRejectedMarkup:
+            # html.parser gives up on a few malformed declarations; the
+            # body's words are still worth more than an exception.
+            text = unescape(_ANY_TAG.sub(" ", content))
+            return html_to_markdown(_plain_text_html(" ".join(text.split())))
+    except _CallbackRaised:
+        raise
+    except Exception as exc:
+        raise GlpiContentError(
+            "Could not convert GLPI HTML content to Markdown "
+            f"({type(exc).__name__}: {exc})."
+        ) from exc
+
+
+def _positive(value: object) -> bool:
+    """Whether ``value`` is a positive ``int`` and not a ``bool``."""
+
+    return isinstance(value, int) and not isinstance(value, bool) and value > 0
+
+
 class GlpiContentConverter:
     """Convert content between GLPI HTML payloads and canonical Markdown."""
 
     @staticmethod
-    def from_transport(value: object, *, plain_text_is_markdown: bool = False) -> str:
+    def from_transport(
+        value: object,
+        *,
+        plain_text_is_markdown: bool = False,
+        rewrite_link: RewriteLink | None = None,
+    ) -> str:
         """Convert one GLPI transport value into Markdown.
 
         Parameters
@@ -759,6 +946,12 @@ class GlpiContentConverter:
             Markdown, but Markdown that opens with an autolink or other
             angle-bracketed text and carries inline HTML further on is read
             as HTML, and loses that autolink.
+        rewrite_link : callable, optional
+            Called with a :class:`Link` for each link and image the read
+            meets outside code, an image before the link around it; its
+            answer decides what is written (:data:`RewriteLink`). Not called
+            for a value passed through as Markdown, nor for a body read as
+            its text. Without one, the read is what it always was.
 
         Returns
         -------
@@ -778,6 +971,10 @@ class GlpiContentConverter:
             limit, where no stack is left even to report the failure as
             ``GlpiContentError`` (the user guide gives the measured
             depths).
+        Exception
+            Whatever ``rewrite_link`` raised, unchanged; ``TypeError`` when it
+            answered something other than a :class:`Link`, a ``str`` or
+            ``None``.
         """
 
         content = str(value or "").strip()
@@ -793,22 +990,96 @@ class GlpiContentConverter:
         # 3.11.14/3.12.12/3.13.6 rescans to the end for each (quadratic).
         head, end, tail = content.rpartition(">")
         content = head + end + tail.replace("<", "&lt;")
+        token = _REWRITE.set(rewrite_link)
         try:
-            try:
-                return html_to_markdown(content)
-            except (RecursionError, ValueError):  # ValueError: markdownify's
-                # int() of a colspan or start such as "²" or 5,000 digits
-                return html_to_markdown(_plain_text_html(_text_of(content)))
-            except ParserRejectedMarkup:
-                # html.parser gives up on a few malformed declarations; the
-                # body's words are still worth more than an exception.
-                text = unescape(_ANY_TAG.sub(" ", content))
-                return html_to_markdown(_plain_text_html(" ".join(text.split())))
-        except Exception as exc:
-            raise GlpiContentError(
-                "Could not convert GLPI HTML content to Markdown "
-                f"({type(exc).__name__}: {exc})."
-            ) from exc
+            return _converted(content)
+        except _CallbackRaised as raised:
+            callback_error = raised.error
+        finally:
+            _REWRITE.reset(token)
+        raise callback_error  # outside the handler: the callback's, as it raised it
+
+    @staticmethod
+    def document_id_of(url: str) -> int | None:
+        """Return the document id a URL to GLPI's document page names.
+
+        ``None`` unless ``url`` -- relative, rooted or absolute, with any
+        path in front -- is ``front/document.send.php`` with exactly one
+        ``docid`` parameter, in any position, made of digits.
+        """
+
+        try:
+            parts = urlsplit(url)
+        except ValueError:  # an unclosed "[" in a host, among others
+            return None
+        path = parts.path
+        if path != _DOCUMENT_PAGE and not path.endswith("/" + _DOCUMENT_PAGE):
+            return None
+        values = parse_qs(parts.query).get("docid", [])
+        if len(values) != 1 or not _DOCUMENT_ID.fullmatch(values[0]):
+            return None
+        document_id = int(values[0])
+        return document_id if document_id > 0 else None
+
+    @staticmethod
+    def document_image(
+        document_id: int,
+        *,
+        alt: str = "",
+        itemtype: str | None = None,
+        items_id: int | None = None,
+    ) -> str:
+        """Return the Markdown of an image embedding one of GLPI's documents.
+
+        :meth:`to_transport` renders it as GLPI's editor writes a pasted image
+        -- the ``<img>`` inside a link to the same URL,
+        ``/front/document.send.php?docid=<document_id>``, then
+        ``&itemtype=...&items_id=...`` when given -- and :meth:`from_transport`
+        reads that back as this same Markdown: it is spelled by the reader
+        itself. The URL is rooted, as the editor wrote it on the instance
+        measured; GLPI checks the reader's right to the document when it
+        serves it.
+
+        Parameters
+        ----------
+        document_id : int
+            The document's id.
+        alt : str, optional
+            The image's alternative text.
+        itemtype, items_id : str and int, optional
+            The item the document is attached to, such as ``"Ticket"`` and
+            its id. Both or neither.
+
+        Raises
+        ------
+        GlpiValidationError
+            ``document_id`` or ``items_id`` is not a positive ``int``,
+            ``itemtype`` is not a class name, or only one of the two was
+            given.
+        """
+
+        if not _positive(document_id):
+            raise GlpiValidationError(f"not a GLPI document id: {document_id!r}")
+        url = f"/{_DOCUMENT_PAGE}?docid={document_id}"
+        if (itemtype is None) != (items_id is None):
+            raise GlpiValidationError(
+                "itemtype and items_id go together: give both or neither"
+            )
+        if itemtype is not None:
+            if not _ITEMTYPE.fullmatch(itemtype):
+                raise GlpiValidationError(f"not a GLPI item type: {itemtype!r}")
+            if not _positive(items_id):
+                raise GlpiValidationError(f"not a GLPI item id: {items_id!r}")
+            url += f"&itemtype={itemtype}&items_id={items_id}"
+        native = (
+            f'<p><a href="{escape(url)}" target="_blank">'
+            f'<img src="{escape(url)}" alt="{escape(" ".join(alt.split()))}" /></a></p>'
+        )
+        token = _REWRITE.set(None)  # a callback in force for an enclosing read
+        try:
+            return html_to_markdown(native)
+        finally:
+            _REWRITE.reset(token)
 
     @staticmethod
     def to_transport(value: object) -> str:

{glpi_python_client-0.6.1 → glpi_python_client-0.6.3}/pyproject.toml

@@ -35,7 +35,7 @@ exclude = [
 
 [project]
 name = "glpi-python-client"
-version = "0.6.1"
+version = "0.6.3"
 description = "A typed Python client for GLPI ITSM APIs."
 readme = "README.md"
 requires-python = ">=3.11"

{glpi_python_client-0.6.1 → glpi_python_client-0.6.3}/skills/glpi-asset-workflow/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "Requires Python 3.11+, glpi-python-client, network access to the GLPI v2 API, and credentials allowed to read or write assets."
 metadata:
   package: glpi-python-client
-  version: "0.6.1"
+  version: "0.6.3"
 ---
 
 # GLPI Asset Workflow

{glpi_python_client-0.6.1 → glpi_python_client-0.6.3}/skills/glpi-client-setup/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "Requires Python 3.11+, glpi-python-client, network access to a GLPI v2 API, and valid GLPI credentials."
 metadata:
   package: glpi-python-client
-  version: "0.6.1"
+  version: "0.6.3"
 ---
 
 # GLPI Client Setup

{glpi_python_client-0.6.1 → glpi_python_client-0.6.3}/skills/glpi-contract-workflow/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "Requires Python 3.11+, glpi-python-client, network access to the GLPI v2 API, and credentials allowed to read or write contracts."
 metadata:
   package: glpi-python-client
-  version: "0.6.1"
+  version: "0.6.3"
 ---
 
 # GLPI Contract Workflow

{glpi_python_client-0.6.1 → glpi_python_client-0.6.3}/skills/glpi-document-workflow/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "Requires Python 3.11+, glpi-python-client, network access to the GLPI v2 API, and v1 credentials configured on the client for binary uploads."
 metadata:
   package: glpi-python-client
-  version: "0.6.1"
+  version: "0.6.3"
 ---
 
 # GLPI Document Workflow

{glpi_python_client-0.6.1 → glpi_python_client-0.6.3}/skills/glpi-knowledge-base/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "Requires Python 3.11+, glpi-python-client, network access to the GLPI v2 API, and — for category writes only — a legacy v1 session (v1_base_url + v1_user_token)."
 metadata:
   package: glpi-python-client
-  version: "0.6.1"
+  version: "0.6.3"
 ---
 
 # GLPI Knowledge Base

{glpi_python_client-0.6.1 → glpi_python_client-0.6.3}/skills/glpi-plugin-fields/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "Requires Python 3.11+, glpi-python-client, the GLPI Fields plugin installed server-side, and a legacy v1 session (v1_base_url + v1_user_token) — every method in this family goes over the v1 API."
 metadata:
   package: glpi-python-client
-  version: "0.6.1"
+  version: "0.6.3"
 ---
 
 # GLPI Plugin Fields