glpi-python-client 0.6.2__py3-none-any.whl → 0.6.4__py3-none-any.whl

glpi_python_client/__init__.py

@@ -50,12 +50,14 @@ from glpi_python_client.models import (
     DeleteTicketTask,
     DeleteTimelineDocument,
     DeleteUser,
+    FollowupDocuments,
     GetComputer,
     GetContract,
     GetContractCost,
     GetContractItem,
     GetContractType,
     GetDocument,
+    GetDocumentItem,
     GetEntity,
     GetFollowup,
     GetKBArticle,
@@ -131,7 +133,7 @@ from glpi_python_client.rsql import (
     date_window,
 )
 
-__version__ = "0.6.2"
+__version__ = "0.6.4"
 
 __all__ = [
     "AsyncGlpiClient",
@@ -153,12 +155,14 @@ __all__ = [
     "DeleteTicketTask",
     "DeleteTimelineDocument",
     "DeleteUser",
+    "FollowupDocuments",
     "GetComputer",
     "GetContract",
     "GetContractCost",
     "GetContractItem",
     "GetContractType",
     "GetDocument",
+    "GetDocumentItem",
     "GetEntity",
     "GetFollowup",
     "GetKBArticle",

glpi_python_client/_async/clients/api/assistance/timeline/_document.py

@@ -17,18 +17,36 @@ as :class:`GetDocument`.
 
 from __future__ import annotations
 
+import re
+
+from glpi_python_client._async._concurrency import gather
 from glpi_python_client._async.clients.commons._constants import (
     TICKET_ENDPOINT,
     TIMELINE_DOCUMENT_SUFFIX,
     GlpiId,
 )
+from glpi_python_client._async.clients.commons._payloads import model_from_payload
 from glpi_python_client._async.clients.commons._transport import TransportMixin
+from glpi_python_client._errors import GlpiValidationError
 from glpi_python_client.models.api_schema.assistance.timeline._document import (
     DeleteTimelineDocument,
     PatchTimelineDocument,
     PostTimelineDocument,
 )
+from glpi_python_client.models.api_schema.assistance.timeline._followup import (
+    GetFollowup,
+)
 from glpi_python_client.models.api_schema.management._document import GetDocument
+from glpi_python_client.models.api_schema.management._document_item import (
+    FollowupDocuments,
+    GetDocumentItem,
+)
+
+_ITEM_DOCUMENT_RANGE = "0-999"
+_ITEM_DOCUMENT_PAGE_SIZE = 1000
+_ITEMTYPE_PATTERN = re.compile(r"^[A-Za-z][A-Za-z0-9_]*$")
+_V1_FEATURE_LABEL = "item document link listing"
+_FOLLOWUP_ITEMTYPE = "ITILFollowup"
 
 
 class TimelineDocumentMixin(TransportMixin):
@@ -62,6 +80,173 @@ class TimelineDocumentMixin(TransportMixin):
             unwrap_envelope=True,
         )
 
+    async def list_item_documents(
+        self, itemtype: str, items_id: GlpiId
+    ) -> list[GetDocumentItem]:
+        """List the document links of one item, over the legacy v1 API.
+
+        Only the followup route (``itemtype="ITILFollowup"``) has been
+        checked against a live server.  Other itemtypes are sent to the same
+        v1 sub-route unchanged.
+
+        Unlike :meth:`list_ticket_timeline_documents`, this call needs the
+        legacy v1 session (``v1_base_url`` and ``v1_user_token``).  Without
+        one it raises ``RuntimeError``.
+
+        It returns link rows, not documents.  A caller resolves each
+        ``documents_id`` with ``get_document``.
+
+        The library does not filter private followups, tasks or solutions
+        for the caller: every link the authenticated user can read is
+        returned.
+
+        GLPI's editor links an image pasted into a followup to the followup,
+        not to the ticket.  A caller that wants such images therefore walks
+        the ticket's followups and lists each one.
+
+        Parameters
+        ----------
+        itemtype : str
+            GLPI itemtype owning the links, for example ``"ITILFollowup"``.
+            It must start with a letter and contain only letters, digits and
+            underscores, because it is placed in the URL path.
+        items_id : GlpiId
+            Positive numeric identifier of the item.
+
+        Returns
+        -------
+        list[GetDocumentItem]
+            Link rows, with naive timestamps localised to the server
+            timezone.  An empty answer gives an empty list.
+
+        Raises
+        ------
+        RuntimeError
+            If the client was built without a v1 session.
+        GlpiValidationError
+            If ``itemtype`` or ``items_id`` is invalid, if GLPI answers
+            something other than a list or an empty body, or if it answers a
+            full page of 1000 rows or more, which may be truncated.  A
+            partial list is never returned.
+        GlpiStatusError
+            If the GLPI server returns a non-success HTTP status.
+        """
+
+        v1 = self._require_v1_session(_V1_FEATURE_LABEL)
+        if not _ITEMTYPE_PATTERN.fullmatch(itemtype):
+            raise GlpiValidationError(
+                f"itemtype must match {_ITEMTYPE_PATTERN.pattern!r}, got {itemtype!r}"
+            )
+        if items_id <= 0:
+            raise GlpiValidationError(
+                f"items_id must be a positive integer, got {items_id!r}"
+            )
+        payload = await v1.request_json(
+            "GET",
+            f"{itemtype}/{items_id}/Document_Item",
+            params={"range": _ITEM_DOCUMENT_RANGE},
+            failure_message=(f"Failed to list document links of {itemtype} {items_id}"),
+        )
+        if isinstance(payload, dict) and not payload:
+            return []
+        if not isinstance(payload, list):
+            raise GlpiValidationError(
+                f"Unexpected document link answer for {itemtype} {items_id}: "
+                f"{type(payload).__name__}"
+            )
+        if len(payload) >= _ITEM_DOCUMENT_PAGE_SIZE:
+            raise GlpiValidationError(
+                f"{itemtype} {items_id} returned {len(payload)} document links, "
+                "a full page that may be truncated"
+            )
+        return [
+            model_from_payload(
+                GetDocumentItem, row, server_timezone=self.server_timezone
+            )
+            for row in payload
+        ]
+
+    async def list_ticket_followup_documents(
+        self, ticket_id: GlpiId, *, include_private: bool = False
+    ) -> list[FollowupDocuments]:
+        """List the document links of each followup of one ticket.
+
+        GLPI's editor links an image pasted into a followup to the followup,
+        not to the ticket. :meth:`list_ticket_timeline_documents` therefore
+        never returns such an image, and this method does.
+
+        Each entry holds the followup and its links, so a caller reads
+        ``followup.is_private`` to classify every link without a second
+        read. Only followups are walked: tasks and solutions are not.
+
+        This call needs the legacy v1 session (``v1_base_url`` and
+        ``v1_user_token``). Without one it raises ``RuntimeError``. It issues
+        one v1 request per kept followup, all at once on the asynchronous
+        surface and one after the other on the synchronous one.
+
+        Parameters
+        ----------
+        ticket_id : GlpiId
+            Numeric identifier of the parent ticket.
+        include_private : bool, optional
+            When false (the default), private followups and followups whose
+            ``is_private`` flag is missing are dropped and not queried, so
+            only what a requester can see is returned. A missing flag counts
+            as private. When true, every followup is kept.
+
+        Returns
+        -------
+        list[FollowupDocuments]
+            One entry per kept followup, in ascending followup id, including
+            a followup with no link (an empty ``documents`` list). A link row
+            that does not name that followup as its item is dropped.
+
+        Raises
+        ------
+        RuntimeError
+            If the client was built without a v1 session.
+        GlpiValidationError
+            If a kept followup has no identifier, or if reading the links of
+            a followup fails validation. A partial list is never returned.
+        GlpiStatusError
+            If the GLPI server returns a non-success HTTP status.
+        """
+
+        self._require_v1_session(_V1_FEATURE_LABEL)
+        followups = await self.list_ticket_followups(ticket_id)  # type: ignore[attr-defined]
+        kept = [
+            followup
+            for followup in followups
+            if include_private or followup.is_private is False
+        ]
+        keyed: list[tuple[int, GetFollowup]] = []
+        for followup in kept:
+            if followup.id is None:
+                raise GlpiValidationError(
+                    f"A followup of ticket {ticket_id} has no id, "
+                    "so its document links cannot be read"
+                )
+            keyed.append((followup.id, followup))
+        keyed.sort(key=lambda pair: pair[0])
+        link_lists = await gather(
+            *(
+                self.list_item_documents(_FOLLOWUP_ITEMTYPE, followup_id)
+                for followup_id, _ in keyed
+            )
+        )
+        return [
+            FollowupDocuments(
+                followup=followup,
+                documents=[
+                    row
+                    for row in rows
+                    if row.itemtype == _FOLLOWUP_ITEMTYPE
+                    and row.items_id == followup_id
+                ],
+            )
+            for (followup_id, followup), rows in zip(keyed, link_lists, strict=True)
+        ]
+
     async def get_ticket_timeline_document(
         self, ticket_id: GlpiId, document_link_id: GlpiId
     ) -> GetDocument:

glpi_python_client/_sync/clients/api/assistance/timeline/_document.py

@@ -17,18 +17,36 @@ as :class:`GetDocument`.
 
 from __future__ import annotations
 
+import re
+
+from glpi_python_client._sync._concurrency import gather
 from glpi_python_client._sync.clients.commons._constants import (
     TICKET_ENDPOINT,
     TIMELINE_DOCUMENT_SUFFIX,
     GlpiId,
 )
+from glpi_python_client._sync.clients.commons._payloads import model_from_payload
 from glpi_python_client._sync.clients.commons._transport import TransportMixin
+from glpi_python_client._errors import GlpiValidationError
 from glpi_python_client.models.api_schema.assistance.timeline._document import (
     DeleteTimelineDocument,
     PatchTimelineDocument,
     PostTimelineDocument,
 )
+from glpi_python_client.models.api_schema.assistance.timeline._followup import (
+    GetFollowup,
+)
 from glpi_python_client.models.api_schema.management._document import GetDocument
+from glpi_python_client.models.api_schema.management._document_item import (
+    FollowupDocuments,
+    GetDocumentItem,
+)
+
+_ITEM_DOCUMENT_RANGE = "0-999"
+_ITEM_DOCUMENT_PAGE_SIZE = 1000
+_ITEMTYPE_PATTERN = re.compile(r"^[A-Za-z][A-Za-z0-9_]*$")
+_V1_FEATURE_LABEL = "item document link listing"
+_FOLLOWUP_ITEMTYPE = "ITILFollowup"
 
 
 class TimelineDocumentMixin(TransportMixin):
@@ -62,6 +80,173 @@ class TimelineDocumentMixin(TransportMixin):
             unwrap_envelope=True,
         )
 
+    def list_item_documents(
+        self, itemtype: str, items_id: GlpiId
+    ) -> list[GetDocumentItem]:
+        """List the document links of one item, over the legacy v1 API.
+
+        Only the followup route (``itemtype="ITILFollowup"``) has been
+        checked against a live server.  Other itemtypes are sent to the same
+        v1 sub-route unchanged.
+
+        Unlike :meth:`list_ticket_timeline_documents`, this call needs the
+        legacy v1 session (``v1_base_url`` and ``v1_user_token``).  Without
+        one it raises ``RuntimeError``.
+
+        It returns link rows, not documents.  A caller resolves each
+        ``documents_id`` with ``get_document``.
+
+        The library does not filter private followups, tasks or solutions
+        for the caller: every link the authenticated user can read is
+        returned.
+
+        GLPI's editor links an image pasted into a followup to the followup,
+        not to the ticket.  A caller that wants such images therefore walks
+        the ticket's followups and lists each one.
+
+        Parameters
+        ----------
+        itemtype : str
+            GLPI itemtype owning the links, for example ``"ITILFollowup"``.
+            It must start with a letter and contain only letters, digits and
+            underscores, because it is placed in the URL path.
+        items_id : GlpiId
+            Positive numeric identifier of the item.
+
+        Returns
+        -------
+        list[GetDocumentItem]
+            Link rows, with naive timestamps localised to the server
+            timezone.  An empty answer gives an empty list.
+
+        Raises
+        ------
+        RuntimeError
+            If the client was built without a v1 session.
+        GlpiValidationError
+            If ``itemtype`` or ``items_id`` is invalid, if GLPI answers
+            something other than a list or an empty body, or if it answers a
+            full page of 1000 rows or more, which may be truncated.  A
+            partial list is never returned.
+        GlpiStatusError
+            If the GLPI server returns a non-success HTTP status.
+        """
+
+        v1 = self._require_v1_session(_V1_FEATURE_LABEL)
+        if not _ITEMTYPE_PATTERN.fullmatch(itemtype):
+            raise GlpiValidationError(
+                f"itemtype must match {_ITEMTYPE_PATTERN.pattern!r}, got {itemtype!r}"
+            )
+        if items_id <= 0:
+            raise GlpiValidationError(
+                f"items_id must be a positive integer, got {items_id!r}"
+            )
+        payload = v1.request_json(
+            "GET",
+            f"{itemtype}/{items_id}/Document_Item",
+            params={"range": _ITEM_DOCUMENT_RANGE},
+            failure_message=(f"Failed to list document links of {itemtype} {items_id}"),
+        )
+        if isinstance(payload, dict) and not payload:
+            return []
+        if not isinstance(payload, list):
+            raise GlpiValidationError(
+                f"Unexpected document link answer for {itemtype} {items_id}: "
+                f"{type(payload).__name__}"
+            )
+        if len(payload) >= _ITEM_DOCUMENT_PAGE_SIZE:
+            raise GlpiValidationError(
+                f"{itemtype} {items_id} returned {len(payload)} document links, "
+                "a full page that may be truncated"
+            )
+        return [
+            model_from_payload(
+                GetDocumentItem, row, server_timezone=self.server_timezone
+            )
+            for row in payload
+        ]
+
+    def list_ticket_followup_documents(
+        self, ticket_id: GlpiId, *, include_private: bool = False
+    ) -> list[FollowupDocuments]:
+        """List the document links of each followup of one ticket.
+
+        GLPI's editor links an image pasted into a followup to the followup,
+        not to the ticket. :meth:`list_ticket_timeline_documents` therefore
+        never returns such an image, and this method does.
+
+        Each entry holds the followup and its links, so a caller reads
+        ``followup.is_private`` to classify every link without a second
+        read. Only followups are walked: tasks and solutions are not.
+
+        This call needs the legacy v1 session (``v1_base_url`` and
+        ``v1_user_token``). Without one it raises ``RuntimeError``. It issues
+        one v1 request per kept followup, all at once on the asynchronous
+        surface and one after the other on the synchronous one.
+
+        Parameters
+        ----------
+        ticket_id : GlpiId
+            Numeric identifier of the parent ticket.
+        include_private : bool, optional
+            When false (the default), private followups and followups whose
+            ``is_private`` flag is missing are dropped and not queried, so
+            only what a requester can see is returned. A missing flag counts
+            as private. When true, every followup is kept.
+
+        Returns
+        -------
+        list[FollowupDocuments]
+            One entry per kept followup, in ascending followup id, including
+            a followup with no link (an empty ``documents`` list). A link row
+            that does not name that followup as its item is dropped.
+
+        Raises
+        ------
+        RuntimeError
+            If the client was built without a v1 session.
+        GlpiValidationError
+            If a kept followup has no identifier, or if reading the links of
+            a followup fails validation. A partial list is never returned.
+        GlpiStatusError
+            If the GLPI server returns a non-success HTTP status.
+        """
+
+        self._require_v1_session(_V1_FEATURE_LABEL)
+        followups = self.list_ticket_followups(ticket_id)  # type: ignore[attr-defined]
+        kept = [
+            followup
+            for followup in followups
+            if include_private or followup.is_private is False
+        ]
+        keyed: list[tuple[int, GetFollowup]] = []
+        for followup in kept:
+            if followup.id is None:
+                raise GlpiValidationError(
+                    f"A followup of ticket {ticket_id} has no id, "
+                    "so its document links cannot be read"
+                )
+            keyed.append((followup.id, followup))
+        keyed.sort(key=lambda pair: pair[0])
+        link_lists = gather(
+            *(
+                self.list_item_documents(_FOLLOWUP_ITEMTYPE, followup_id)
+                for followup_id, _ in keyed
+            )
+        )
+        return [
+            FollowupDocuments(
+                followup=followup,
+                documents=[
+                    row
+                    for row in rows
+                    if row.itemtype == _FOLLOWUP_ITEMTYPE
+                    and row.items_id == followup_id
+                ],
+            )
+            for (followup_id, followup), rows in zip(keyed, link_lists, strict=True)
+        ]
+
     def get_ticket_timeline_document(
         self, ticket_id: GlpiId, document_link_id: GlpiId
     ) -> GetDocument:

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/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):
@@ -752,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
@@ -774,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
         -------
@@ -793,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()
@@ -808,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/models/__init__.py

@@ -109,9 +109,11 @@ from glpi_python_client.models.api_schema.management import (
     DeleteContract,
     DeleteContractCost,
     DeleteDocument,
+    FollowupDocuments,
     GetContract,
     GetContractCost,
     GetDocument,
+    GetDocumentItem,
     PatchContract,
     PatchContractCost,
     PatchDocument,
@@ -149,12 +151,14 @@ __all__ = [
     "DeleteTicketTask",
     "DeleteTimelineDocument",
     "DeleteUser",
+    "FollowupDocuments",
     "GetComputer",
     "GetContract",
     "GetContractCost",
     "GetContractItem",
     "GetContractType",
     "GetDocument",
+    "GetDocumentItem",
     "GetEntity",
     "GetFollowup",
     "GetKBArticle",

glpi_python_client/models/api_schema/enums.py

@@ -135,9 +135,14 @@ class GlpiTimelinePosition(GlpiEnum):
     The contract advertises ``[-1, 0, 1, 2, 3, 4]`` on
     ``timeline_position``. ``LEFT`` and ``RIGHT`` follow the GLPI UI
     conventions.
+
+    ``NO_TIMELINE`` is GLPI's own name for ``-1`` and an alias of
+    ``INVALID``. GLPI's editor writes it on the link of an image it embeds
+    in a text, and such a link is hidden from the ticket's Documents tab.
     """
 
     INVALID = -1
+    NO_TIMELINE = -1
     NONE = 0
     LEFT = 1
     RIGHT = 2

glpi_python_client/models/api_schema/management/__init__.py

@@ -18,14 +18,20 @@ from glpi_python_client.models.api_schema.management._document import (
     PatchDocument,
     PostDocument,
 )
+from glpi_python_client.models.api_schema.management._document_item import (
+    FollowupDocuments,
+    GetDocumentItem,
+)
 
 __all__ = [
     "DeleteContract",
     "DeleteContractCost",
     "DeleteDocument",
+    "FollowupDocuments",
     "GetContract",
     "GetContractCost",
     "GetDocument",
+    "GetDocumentItem",
     "PatchContract",
     "PatchContractCost",
     "PatchDocument",

glpi_python_client/models/api_schema/management/_document_item.py

@@ -0,0 +1,88 @@
+"""GLPI ``Document_Item`` link rows, as the legacy v1 API returns them.
+
+A ``Document_Item`` row links one document to one item: a ticket, a followup,
+a task or a solution. The v1 sub-item route ``<Itemtype>/<id>/Document_Item``
+answers a list of these rows. They are not the ``GetTimelineDocument`` shape
+of the v2 timeline, which carries no entity and no dates.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import ConfigDict
+
+from glpi_python_client.models._base import GlpiModel
+from glpi_python_client.models.api_schema.assistance.timeline._followup import (
+    GetFollowup,
+)
+from glpi_python_client.models.api_schema.enums import GlpiTimelinePosition
+
+
+class GetDocumentItem(GlpiModel):
+    """One ``Document_Item`` row linking a document to an item.
+
+    Keys the model does not declare (``users_id``, ``is_recursive``,
+    ``links`` and any plugin column) are kept in ``extra_payload``.
+
+    Parameters
+    ----------
+    id : int
+        Native identifier of the link row.
+    documents_id : int
+        Identifier of the linked document.
+    itemtype : str | None, optional
+        GLPI type of the item the document is linked to, for example
+        ``"Ticket"`` or ``"ITILFollowup"``.
+    items_id : int | None, optional
+        Identifier of the item the document is linked to.
+    entities_id : int | None, optional
+        Identifier of the entity owning the link.
+    date_creation : datetime | None, optional
+        Creation timestamp of the link row.
+    date_mod : datetime | None, optional
+        Last modification timestamp of the link row.
+    date : datetime | None, optional
+        Timestamp GLPI records on the link.
+    timeline_position : GlpiTimelinePosition | None, optional
+        Position of the link in the ticket timeline. A link at
+        :attr:`GlpiTimelinePosition.NO_TIMELINE` (``-1``) is written by
+        GLPI's editor for an image it embeds in a text. Such a link is
+        hidden from the ticket's Documents tab. A document uploaded as an
+        attachment is linked at ``1``.
+    """
+
+    id: int
+    documents_id: int
+    itemtype: str | None = None
+    items_id: int | None = None
+    entities_id: int | None = None
+    date_creation: datetime | None = None
+    date_mod: datetime | None = None
+    date: datetime | None = None
+    timeline_position: GlpiTimelinePosition | None = None
+
+
+class FollowupDocuments(GlpiModel):
+    """One ticket followup together with its document links.
+
+    Returned by ``list_ticket_followup_documents``. The followup is kept
+    whole, so a caller reads ``followup.is_private`` to classify every link
+    without a second read.
+
+    Parameters
+    ----------
+    followup : GetFollowup
+        The followup, as the ticket's followup listing returned it.
+    documents : list[GetDocumentItem]
+        The ``Document_Item`` rows linked to this followup. Empty when the
+        followup has no document.
+    """
+
+    model_config = ConfigDict(extra="allow", frozen=True)
+
+    followup: GetFollowup
+    documents: list[GetDocumentItem]
+
+
+__all__ = ["FollowupDocuments", "GetDocumentItem"]

{glpi_python_client-0.6.2.dist-info → glpi_python_client-0.6.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: glpi-python-client
-Version: 0.6.2
+Version: 0.6.4
 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.2.dist-info → glpi_python_client-0.6.4.dist-info}/RECORD

@@ -1,4 +1,4 @@
-glpi_python_client/__init__.py,sha256=DGjWsC96c-1sfryxVwHThPASrR5sy0IpNiooeAVx5Wk,5538
+glpi_python_client/__init__.py,sha256=IjuloET5lqy2KL5c3sgXRYxppjxcVAv7mZUK-DERRNA,5630
 glpi_python_client/_errors.py,sha256=Bc9UvlxulbdcGvzZIKXnJCTL78sW78R6EFg50P-1dpY,7151
 glpi_python_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 glpi_python_client/rsql.py,sha256=3u3lH3_-F1bvHbVzxALXTDPoHyoMATP1f4QPTar_sEU,8974
@@ -21,7 +21,7 @@ glpi_python_client/_async/clients/api/assistance/__init__.py,sha256=nL77QpQ4Yzfd
 glpi_python_client/_async/clients/api/assistance/_team.py,sha256=QEwFTXE8W_MURi_zgfDTLoqYP__NF1SwBd_7dLJZg5U,3824
 glpi_python_client/_async/clients/api/assistance/_ticket.py,sha256=z1-kKjkSwvePZl65CXpDay50uJpirjlA1ww4_3eVyJU,7990
 glpi_python_client/_async/clients/api/assistance/timeline/__init__.py,sha256=AqB_UpcRMHjfvZyLBjkwfsnEBwz77xBbGJzXzWmS7os,619
-glpi_python_client/_async/clients/api/assistance/timeline/_document.py,sha256=3vTbAxh8ZoVmx45xId5jjcapm4124dVnhXoF84Du_8w,7334
+glpi_python_client/_async/clients/api/assistance/timeline/_document.py,sha256=BYCScaSyfrPzAh-znObYh1yEeL4dwYLYV8F0hKn6YcE,14803
 glpi_python_client/_async/clients/api/assistance/timeline/_followup.py,sha256=jgE_kpJxMa3v1Tt4Jm2PahiRNX7v3vKh6xjbX27sp7w,6221
 glpi_python_client/_async/clients/api/assistance/timeline/_solution.py,sha256=3DpbDeHDQ7FJdevhcpAcgXyB9FZu7_S2kVblFXsZUq0,6156
 glpi_python_client/_async/clients/api/assistance/timeline/_task.py,sha256=EdkrRJnkHWaZdxgyqwL1rhUygGSJScR2jIS6CFJL4S4,5869
@@ -67,7 +67,7 @@ glpi_python_client/_sync/clients/api/assistance/__init__.py,sha256=dAXVQPgCmPhCL
 glpi_python_client/_sync/clients/api/assistance/_team.py,sha256=Nk0FXUHyZZOkg62Os4FBee3Jv4YzMJoOqsvsWM0yqI0,3785
 glpi_python_client/_sync/clients/api/assistance/_ticket.py,sha256=Xuk0-8geUdII-uFdgIbkhG_QMEfOytcHp5n-Hq2D-U8,7906
 glpi_python_client/_sync/clients/api/assistance/timeline/__init__.py,sha256=d_YAwgv3r1sNrRVlPC5r1yEhbUZQKzLtuNzHD9eBF8Y,615
-glpi_python_client/_sync/clients/api/assistance/timeline/_document.py,sha256=Tqy4HCzZiZ5keXQEHt8gbA8OGAkdMqlvJ9yX0tVnknA,7272
+glpi_python_client/_sync/clients/api/assistance/timeline/_document.py,sha256=0T7wEyVNoECI8c0LUZ1WQtXgvpRBKyl-GTsB4jdJ2xA,14709
 glpi_python_client/_sync/clients/api/assistance/timeline/_followup.py,sha256=trQJJThA8jk2jVK-jTW8uPZyYEvR5Zi18mqGT6436VM,6158
 glpi_python_client/_sync/clients/api/assistance/timeline/_solution.py,sha256=KVyrjKFS35lJzvjwEromOEL2Q2OfvLP7MvhV7QirtVs,6093
 glpi_python_client/_sync/clients/api/assistance/timeline/_task.py,sha256=peSQmKYoHc9IVdQltBaDqFFHZKdBzWJwt_0GXng2odU,5806
@@ -94,14 +94,14 @@ glpi_python_client/_sync/clients/commons/_transport.py,sha256=x9xRFSUrJLPyp1DrVh
 glpi_python_client/_sync/clients/custom/__init__.py,sha256=sxfGlHVulucP7bacWhUMi9qGJZaiZm8lXceY0OGqWio,882
 glpi_python_client/_sync/clients/custom/_statistics.py,sha256=xrD5C99ieROJx60iUomBHacQ_49HpgQL4XjnfREUQvs,38616
 glpi_python_client/_sync/clients/custom/_ticket_context.py,sha256=LDUvKNr8VpZonF5bDo8QYYwMEsWmayVU28Ra3GonNmE,3004
-glpi_python_client/content/__init__.py,sha256=3H4IbrNhgFO0BJrc0xLoeXrFHUE1nqOaDlNgi2MtK9k,365
-glpi_python_client/content/conversion.py,sha256=0IjZ-36WlGMGwo4sHk92bZ3DDsZxVK0YKGCwrFlnRpo,33158
-glpi_python_client/models/__init__.py,sha256=b6DPZtH0CxyBUnVB0x9vP9AMBIjgubDFm_1TOQuCiVA,5362
+glpi_python_client/content/__init__.py,sha256=TaZPo8WSvVj4U-hSnxhUcqU8JnCKNZYpfQf4pH45aN4,424
+glpi_python_client/content/conversion.py,sha256=bglYY5IgoTv2SdS0Gton7WgsyzwwQ5GdU_2dLloL2l0,42860
+glpi_python_client/models/__init__.py,sha256=CLvk-1A-88114X7HaS9P6KyfovQjCPRX08J56rJaGls,5454
 glpi_python_client/models/_base.py,sha256=pYg69KHuR5TDED5utr4Knr7HncBnLTxXHJZYf6vEUKA,12183
 glpi_python_client/models/api_schema/__init__.py,sha256=yTxUYih1Xy7NUogzD7UKp2b8HyE4wdeC_FCKS6ZRVVM,1176
 glpi_python_client/models/api_schema/_common.py,sha256=wVtaIkUM9iS3jyDb0bpFopEkP_3vP1ax7D8rwHe9QkI,2004
 glpi_python_client/models/api_schema/_content.py,sha256=DlsEmlXIK_0jyXh3j5PgU6vkwch2o0I8UpUkLq2fqYw,12826
-glpi_python_client/models/api_schema/enums.py,sha256=WDdEhnB_-ZggvY0RTnAX6C6bN8extGzpE9An-Nk5QuQ,4834
+glpi_python_client/models/api_schema/enums.py,sha256=bHNCuumOXIZm80n5RqIhCzFqizII-3er41mn2aktF5s,5071
 glpi_python_client/models/api_schema/administration/__init__.py,sha256=uTr2rEMYq47T5foUMHm1rtsBmEQvdD1EQw5CZOUN38Y,706
 glpi_python_client/models/api_schema/administration/_entity.py,sha256=KdbxMyPXumGZKmmabDIciF3nFS61pLRp5SBOTFa8slk,3297
 glpi_python_client/models/api_schema/administration/_user.py,sha256=MQ6cHKdni98sjm-Whf0GKdGpNjPgGGJpUBgVjlGa19Q,15872
@@ -124,10 +124,11 @@ glpi_python_client/models/api_schema/knowledgebase/_article.py,sha256=zNLnkkdfGj
 glpi_python_client/models/api_schema/knowledgebase/_category.py,sha256=bokNV56PTULFCAzV8dxLOAl8Nk2yCI5Lmb3RLGm0zTM,2260
 glpi_python_client/models/api_schema/knowledgebase/_comment.py,sha256=mouYQE2AigGpJY0jTu9KoqOa4xT0_ckj0h6XDfY7mqc,2325
 glpi_python_client/models/api_schema/knowledgebase/_revision.py,sha256=KuTb_F85mc63RHpQ1VFsmM-eDBjUrxAEdLM48-WmWYs,1985
-glpi_python_client/models/api_schema/management/__init__.py,sha256=mI39635e4_IgpaYNOXZotZ_xIXPH8oE1FXno6cvr-pY,816
+glpi_python_client/models/api_schema/management/__init__.py,sha256=z5ntUAXiXXhZCEIsTVaTgJdXbg0ZW24TZctarfAqjr0,987
 glpi_python_client/models/api_schema/management/_contract.py,sha256=m6g__AKWvDQ09xKyUe8RhRS8xE1d1pOBjqOOG-8u6Ck,14045
 glpi_python_client/models/api_schema/management/_contract_cost.py,sha256=Bp2B3bA5u8CE_oBYY70QIUot8jFLCrX_icXZ4kpYqSE,4966
 glpi_python_client/models/api_schema/management/_document.py,sha256=RzKF-rNlz8CsAMa2BAaiqHNEE3-m1mci7vtdARls4uw,4607
+glpi_python_client/models/api_schema/management/_document_item.py,sha256=Bu9c9YdhSs5hGZ8dRfRxqS4g7VZ1A3EJtNbDLulKpWA,3113
 glpi_python_client/models/api_schema/plugins/__init__.py,sha256=GA0pr0PeoPOqwjUilrBujh0OqjUfZhzPWgIlgDJcZog,544
 glpi_python_client/models/api_schema/plugins/_fields.py,sha256=Se-12ZDqk_-on_37YF_hRD5S0e0H6zyha3SXI9xb_9Y,6576
 glpi_python_client/models/custom_schema/__init__.py,sha256=Usp592x9OWws30vU1rEXbkkRBhcgytM5nxRPTB1gqhY,500
@@ -135,7 +136,7 @@ glpi_python_client/models/custom_schema/_ticket_context.py,sha256=jnlfgho-aDbmA9
 glpi_python_client/testing/__init__.py,sha256=iLtUyJjyv3fEhy3PN25NxNTbtqDl3SoHLbNium0Z80U,568
 glpi_python_client/testing/fixtures.py,sha256=HKt6MXHgcmLn4L98pSwp-oGlc9C--_vrABNe5G_iBeg,1286
 glpi_python_client/testing/utils.py,sha256=JyO3w2d-0kYdtC1hEZ2Tu_YjnCz8nUQ_Ck05-1EhsX4,4404
-glpi_python_client-0.6.2.dist-info/METADATA,sha256=9wihyUuKVM3_SjCpxgML5kJfV09itUlO6VTUoMwxzgw,8234
-glpi_python_client-0.6.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-glpi_python_client-0.6.2.dist-info/licenses/LICENSE,sha256=nL8re-TIKkxCoL7OkSBja6EB4NsQR1HoOJgxv_MEhtc,1088
-glpi_python_client-0.6.2.dist-info/RECORD,,
+glpi_python_client-0.6.4.dist-info/METADATA,sha256=EFNn15U6Eqjua7bVLPM22W9N48EEMza3gq3f0--MsJs,8234
+glpi_python_client-0.6.4.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+glpi_python_client-0.6.4.dist-info/licenses/LICENSE,sha256=nL8re-TIKkxCoL7OkSBja6EB4NsQR1HoOJgxv_MEhtc,1088
+glpi_python_client-0.6.4.dist-info/RECORD,,