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

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

@@ -4,6 +4,58 @@ 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.5 — 2026-10-14
+
+A patch release that lets a caller find the Document behind an image GLPI left
+as a raw `data:` URI. GLPI may keep a large pasted image in the stored body as
+`<img id="..." src="data:image/png;base64,...">` instead of rewriting it into
+a document link, while still creating its Document, whose tag equals the
+image's `id`. Existing methods are unchanged.
+
+### Added
+
+- **`Link.image_id`**, a new last field of the `Link` the `rewrite_link`
+  callback receives: for an `<img>`, the value of its `id` attribute (trimmed;
+  `None` when absent or blank); always `None` for a link.
+- **`GlpiContentConverter.data_image_ids(html)`** returns, in document order
+  and without duplicates, the `id` of every `<img>` whose `src` is a `data:`
+  URI, so a caller can tell whether it needs to read any Document at all. It
+  does not decode the base64, and leaves out an image inside `<pre>`, `<code>`,
+  `<kbd>` or `<samp>`, which the reader never offers to `rewrite_link`.
+- **`GetDocument.tag`**, a read-only property: the Document's tag from
+  `extra_payload`, or `None` when absent or not a non-empty string. GLPI sets a
+  tag on the Documents it creates from an upload or an editor paste, images or
+  not.
+
+## 0.6.4 — 2026-10-12
+
+A patch release that reads the documents GLPI links to a followup. GLPI's
+editor links an image pasted into a followup to the followup and not to the
+ticket, so the ticket-level listing never returned it. Existing methods are
+unchanged.
+
+### Added
+
+- **`list_item_documents(itemtype, items_id)`** lists the v1 `Document_Item`
+  links of one item as `GetDocumentItem` rows. It needs the v1 session
+  (`v1_base_url` and `v1_user_token`) and raises `RuntimeError` without one.
+  An invalid `itemtype` or id, a non-list answer, or a full page of 1000 rows
+  or more raises `GlpiValidationError`; a partial list is never returned.
+- **`GetDocumentItem`**, exported from the package root, models a link row:
+  `id`, `documents_id`, `itemtype`, `items_id`, `entities_id`, the dates and
+  `timeline_position`. Other keys stay in `extra_payload`.
+- **`list_ticket_followup_documents(ticket_id, *, include_private=False)`**
+  returns one `FollowupDocuments` (the followup and its `GetDocumentItem`
+  links) per followup, in ascending followup id, empty ones included. Private
+  followups, and followups with no `is_private` flag, are dropped by default;
+  `include_private=True` keeps every followup.
+- **`FollowupDocuments`**, exported from the package root.
+- **`GlpiTimelinePosition.NO_TIMELINE`** (-1) is an alias of `INVALID`, so
+  existing uses of `INVALID` are unaffected.
+- The followup route was measured live. The primitive `list_item_documents`
+  does not filter private followups; the convenience filters them by default.
+  Tasks and solutions are not measured, and no helper walks them.
+
 ## 0.6.3 — 2026-10-08
 
 A patch release of the converter's reading: a caller can recognise the

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: glpi-python-client
-Version: 0.6.3
+Version: 0.6.5
 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.3 → glpi_python_client-0.6.5}/docs/api_reference.rst

@@ -315,6 +315,16 @@ Documents
    :undoc-members:
    :show-inheritance:
 
+.. autoclass:: GetDocumentItem
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: FollowupDocuments
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 .. autoclass:: PostDocument
    :members:
    :undoc-members:

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

@@ -380,7 +380,8 @@ The full set is re-exported from the package root, including
 ``GetEntity`` / ``PostEntity`` / ``PatchEntity`` / ``DeleteEntity``,
 ``GetFollowup``, ``GetTicketTask``, ``GetSolution``, ``GetTimelineDocument``,
 ``GetTeamMember``, and ``GetDocument`` together with their post / patch /
-delete variants.
+delete variants. The read-only ``GetDocumentItem`` and ``FollowupDocuments``
+have no post / patch / delete variants.
 
 All models inherit from a permissive base: the GLPI server is the
 authoritative validator, so any extra keys returned by the live server
@@ -580,6 +581,43 @@ Example output::
 the client (``v1_base_url`` and ``v1_user_token``) because the GLPI v2
 contract does not advertise a binary upload endpoint.
 
+Documents linked to a followup
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+GLPI's editor links an image pasted into a followup to the followup, not to
+the ticket, so ``list_ticket_timeline_documents`` never returns it. Two
+helpers read those links through the legacy v1 session (``v1_base_url`` and
+``v1_user_token``); without one they raise ``RuntimeError``.
+
+``list_item_documents(itemtype, items_id)`` returns the document links of any
+item as :class:`~glpi_python_client.GetDocumentItem` rows: the link ``id``, the
+``documents_id``, the ``itemtype`` and ``items_id`` it names, and a
+``timeline_position``. It does not filter anything, private followups
+included. A page of 1000 rows or more raises ``GlpiValidationError`` rather
+than return a possibly truncated list.
+
+``list_ticket_followup_documents(ticket_id, *, include_private=False)`` walks
+the ticket's followups and returns one
+:class:`~glpi_python_client.FollowupDocuments` per followup, in ascending
+followup id, holding the followup and its links (an empty list for a followup
+without any). By default private followups, and followups whose ``is_private``
+flag is missing, are dropped and not queried; pass ``include_private=True`` to
+keep them all.
+
+.. code-block:: python
+
+   for entry in client.list_ticket_followup_documents(ticket_id):
+       for link in entry.documents:
+           print(entry.followup.id, link.documents_id, link.timeline_position)
+
+``timeline_position`` is a :class:`~glpi_python_client.GlpiTimelinePosition`.
+``GlpiTimelinePosition.NO_TIMELINE`` (-1) names the value GLPI gives a link
+that sits outside the ticket timeline, such as an image pasted into a
+followup. It is an alias of ``INVALID``, which keeps its meaning.
+
+The followup route was measured against a live server. Tasks and solutions
+were not measured, so no helper walks them.
+
 Assets
 ~~~~~~
 
@@ -1969,6 +2007,25 @@ 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.
 
+GLPI does not always rewrite a pasted image into a document link. A large one
+can stay in the stored body as ``<img id="tag-1" src="data:image/png;base64,...">``
+while GLPI still creates its Document, whose tag is the image's ``id``. For
+such an image ``Link.image_id`` is that ``id`` and ``href`` is the data URI;
+``GlpiContentConverter.data_image_ids(html)`` lists those ids without
+converting, so a caller reads Documents only when a body needs it. A
+:class:`~glpi_python_client.models.GetDocument` exposes its tag as ``tag``:
+
+.. code-block:: python
+
+    ids = GlpiContentConverter.data_image_ids(body)
+    if ids:
+        by_tag = {d.tag: d for d in documents if d.tag}
+        matched = [by_tag[i] for i in ids if i in by_tag]
+
+The ``id`` is body text, and anyone who can write the body can forge it. Match
+it only against Documents the caller already trusts, such as the same
+ticket's own, never against every Document the instance holds.
+
 It is not a sanitiser
 ^^^^^^^^^^^^^^^^^^^^^
 

{glpi_python_client-0.6.3 → glpi_python_client-0.6.5}/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.3"
+__version__ = "0.6.5"
 
 __all__ = [
     "AsyncGlpiClient",
@@ -153,12 +155,14 @@ __all__ = [
     "DeleteTicketTask",
     "DeleteTimelineDocument",
     "DeleteUser",
+    "FollowupDocuments",
     "GetComputer",
     "GetContract",
     "GetContractCost",
     "GetContractItem",
     "GetContractType",
     "GetDocument",
+    "GetDocumentItem",
     "GetEntity",
     "GetFollowup",
     "GetKBArticle",

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

@@ -0,0 +1,410 @@
+"""GLPI ``/Assistance/Ticket/{id}/Timeline/Document`` mixin.
+
+The mixin exposes list, fetch, link, and unlink helpers for the timeline
+document endpoint that links existing GLPI documents to a ticket.
+
+Notes
+-----
+The live GLPI v2 server returns each entry of the list endpoint wrapped
+in a ``{"type": "Document_Item", "item": {...}}`` envelope, even though
+the OpenAPI contract documents a flat array of ``Document_Item``.  The
+``item`` value is a full ``Document`` record (matching :class:`GetDocument`),
+not a ``Document_Item`` link record — real behaviour wins over the contract.
+:func:`list_ticket_timeline_documents` unwraps the envelope through the shared
+``TransportMixin._resource_list`` helper and deserialises each inner object
+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):
+    """CRUD helpers for the ticket document timeline endpoint."""
+
+    async def list_ticket_timeline_documents(
+        self, ticket_id: GlpiId
+    ) -> list[GetDocument]:
+        """List all documents linked to one ticket timeline.
+
+        Parameters
+        ----------
+        ticket_id : GlpiId
+            Numeric identifier of the parent ticket.
+
+        Returns
+        -------
+        list[GetDocument]
+            Document records returned by the GLPI server.  The live API
+            wraps each entry in a ``{"type": "Document_Item", "item": {...}}``
+            envelope whose ``item`` value is a full ``Document`` record; the
+            envelope is unwrapped automatically.
+        """
+
+        return await self._resource_list(
+            f"{TICKET_ENDPOINT}/{ticket_id}/{TIMELINE_DOCUMENT_SUFFIX}",
+            GetDocument,
+            failure_message=(
+                f"Failed to list timeline documents for ticket {ticket_id}"
+            ),
+            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:
+        """Fetch one document linked to the ticket timeline by its document ID.
+
+        Parameters
+        ----------
+        ticket_id : GlpiId
+            Numeric identifier of the parent ticket.
+        document_link_id : GlpiId
+            Numeric identifier of the linked document to retrieve.
+
+        Returns
+        -------
+        GetDocument
+            Validated document payload.
+
+        Raises
+        ------
+        GlpiStatusError
+            If the GLPI server returns a non-success HTTP status.
+        """
+
+        return await self._resource_get(
+            f"{TICKET_ENDPOINT}/{ticket_id}/"
+            f"{TIMELINE_DOCUMENT_SUFFIX}/{document_link_id}",
+            GetDocument,
+            failure_message=(
+                f"Failed to get timeline document {document_link_id} on "
+                f"ticket {ticket_id}"
+            ),
+        )
+
+    async def link_ticket_timeline_document(
+        self, ticket_id: GlpiId, document_link: PostTimelineDocument
+    ) -> int:
+        """Link an existing GLPI document to one ticket timeline.
+
+        Parameters
+        ----------
+        ticket_id : GlpiId
+            Numeric identifier of the parent ticket.
+        document_link : PostTimelineDocument
+            Request body describing the link (typically the timeline
+            position; document and ticket identifiers are inferred from
+            the URL).
+
+        Returns
+        -------
+        int
+            Identifier assigned by the GLPI server to the new link.
+
+        Raises
+        ------
+        GlpiStatusError
+            If the GLPI server returns a non-success HTTP status.
+        GlpiProtocolError
+            If the create response is missing the ``id`` field.
+        """
+
+        return await self._resource_create(
+            f"{TICKET_ENDPOINT}/{ticket_id}/{TIMELINE_DOCUMENT_SUFFIX}",
+            document_link,
+            failure_message=(f"Failed to link timeline document on ticket {ticket_id}"),
+            missing_message=(
+                "GLPI timeline document link response did not include an ID"
+            ),
+            log_message_factory=(
+                lambda new_id: (
+                    f"GLPI API linked timeline document {new_id} on ticket {ticket_id}"
+                )
+            ),
+        )
+
+    async def update_ticket_timeline_document(
+        self,
+        ticket_id: GlpiId,
+        document_link_id: GlpiId,
+        document_link: PatchTimelineDocument,
+    ) -> None:
+        """Update one timeline document link with a partial body.
+
+        Parameters
+        ----------
+        ticket_id : GlpiId
+            Numeric identifier of the parent ticket.
+        document_link_id : GlpiId
+            Numeric identifier of the timeline document link to update.
+        document_link : PatchTimelineDocument
+            Partial request body.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        GlpiStatusError
+            If the GLPI server returns a non-success HTTP status.
+        """
+
+        await self._resource_update(
+            f"{TICKET_ENDPOINT}/{ticket_id}/"
+            f"{TIMELINE_DOCUMENT_SUFFIX}/{document_link_id}",
+            document_link,
+            failure_message=(
+                f"Failed to update timeline document {document_link_id} on "
+                f"ticket {ticket_id}"
+            ),
+            log_message=(
+                f"GLPI API updated timeline document {document_link_id} on "
+                f"ticket {ticket_id}"
+            ),
+        )
+
+    async def unlink_ticket_timeline_document(
+        self,
+        ticket_id: GlpiId,
+        document_link_id: GlpiId,
+        *,
+        force: bool | None = None,
+    ) -> None:
+        """Unlink one timeline document from a ticket.
+
+        Parameters
+        ----------
+        ticket_id : GlpiId
+            Numeric identifier of the parent ticket.
+        document_link_id : GlpiId
+            Numeric identifier of the timeline document link to remove.
+        force : bool | None, optional
+            When ``True`` the link is permanently deleted instead of
+            being moved to the trash.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        GlpiStatusError
+            If the GLPI server returns a non-success HTTP status.
+        """
+
+        await self._resource_delete(
+            f"{TICKET_ENDPOINT}/{ticket_id}/"
+            f"{TIMELINE_DOCUMENT_SUFFIX}/{document_link_id}",
+            failure_message=(
+                f"Failed to unlink timeline document {document_link_id} on "
+                f"ticket {ticket_id}"
+            ),
+            log_message=(
+                f"GLPI API unlinked timeline document {document_link_id} on "
+                f"ticket {ticket_id}"
+            ),
+            force=force,
+            delete_model_cls=DeleteTimelineDocument,
+        )
+
+
+__all__ = ["TimelineDocumentMixin"]