rewire markdown converters

Author: baraline

.coverage

@@ -57,7 +57,7 @@ async def main() -> None:
         ticket_id = await glpi.create_ticket(
             PostTicket(
                 name="Printer issue",
-                content="<p>The printer is not reachable from the office network.</p>",
+                content="The printer is not reachable from the office network.",
             )
         )
         ticket = await glpi.get_ticket(ticket_id)

README.md

@@ -151,7 +151,7 @@ coroutines to it from any synchronous thread:
        )
        try:
            ticket_id = glpi.create_ticket(
-               "Printer issue", "<p>The printer is offline.</p>"
+               "Printer issue", "The printer is offline."
            )
            print("created ticket", ticket_id)
        finally:
@@ -270,7 +270,7 @@ ambient extras when both are present.
 
    ticket = PostTicket(
        name="Printer offline",
-       content="<p>The third-floor printer cannot be reached.</p>",
+       content="The third-floor printer cannot be reached.",
        extra_payload={"_room_code": "PAR-3F-12"},
    )
    ticket_id = await client.create_ticket(ticket)
@@ -290,12 +290,12 @@ helpers under ``/Assistance/Ticket``.
    from glpi_python_client import PatchTicket, PostTicket
 
    ticket_id = await client.create_ticket(
-       PostTicket(name="Wi-Fi unreachable", content="<p>802.1X failure</p>")
+       PostTicket(name="Wi-Fi unreachable", content="802.1X failure")
    )
    try:
        await client.update_ticket(
            ticket_id,
-           PatchTicket(content="<p>Updated diagnosis</p>"),
+           PatchTicket(content="Updated diagnosis"),
        )
        ticket = await client.get_ticket(ticket_id)
        results = await client.search_tickets("status==1", limit=20)
@@ -326,15 +326,15 @@ delete_`` shape (``link_`` / ``unlink_`` for documents).
 
    followup_id = await client.create_ticket_followup(
        ticket_id,
-       PostFollowup(content="<p>Triaged: ongoing</p>"),
+       PostFollowup(content="Triaged: ongoing"),
    )
    task_id = await client.create_ticket_task(
        ticket_id,
-       PostTicketTask(content="<p>On-site visit</p>", duration=900),
+       PostTicketTask(content="On-site visit", duration=900),
    )
    solution_id = await client.create_ticket_solution(
        ticket_id,
-       PostSolution(content="<p>Replaced the access point</p>"),
+       PostSolution(content="Replaced the access point"),
    )
 
    followups = await client.list_ticket_followups(ticket_id)
@@ -507,24 +507,24 @@ The following example mirrors the integration test suite:
                )
            )
            ticket_id = await client.create_ticket(
-               PostTicket(name="VPN drops", content="<p>Daily VPN drops at 11:00</p>")
+               PostTicket(name="VPN drops", content="Daily VPN drops at 11:00")
            )
            try:
                await client.create_ticket_followup(
                    ticket_id,
-                   PostFollowup(content="<p>Reproduced on lab laptop</p>"),
+                   PostFollowup(content="Reproduced on lab laptop"),
                )
                await client.create_ticket_task(
                    ticket_id,
-                   PostTicketTask(content="<p>Capture VPN logs</p>", duration=1800),
+                   PostTicketTask(content="Capture VPN logs", duration=1800),
                )
                await client.add_ticket_team_member(
                    ticket_id,
                    PostTeamMember(type="User", id=user_id, role="assigned"),
                )
                await client.create_ticket_solution(
                    ticket_id,
-                   PostSolution(content="<p>Upgraded VPN client</p>"),
+                   PostSolution(content="Upgraded VPN client"),
                )
                context = await client.get_ticket_context(ticket_id)
                print(context.ticket.name, len(context.followups))

docs/user_guide.rst

@@ -165,7 +165,7 @@ async def test_create_ticket_task_uses_task_endpoint(
     await client.create_ticket_task(8, PostTicketTask(content="task", duration=120))
     call = recorder.calls[0]
     assert call["endpoint"] == "Assistance/Ticket/8/Timeline/Task"
-    assert call["json"] == {"content": "task", "duration": 120}
+    assert call["json"] == {"content": "<p>task</p>", "duration": 120}
 
 
 async def test_create_ticket_solution_uses_solution_endpoint(

glpi_python_client/clients/tests/test_smoke.py

@@ -0,0 +1,74 @@
+"""Annotated content types for transparent Markdown/HTML transport handling.
+
+GLPI exchanges rich-text fields (ticket ``content``, followup ``content``,
+task ``content``, solution ``content``, ...) over the wire as HTML
+(``format: html`` in the OpenAPI contract), but the public package surface
+is intentionally Markdown-only: callers should never need to author or read
+HTML. The annotated type defined here wires
+:class:`glpi_python_client.content.conversion.GlpiContentConverter` into
+Pydantic so the conversion happens transparently on every model boundary:
+
+* On validation (incoming HTML payloads from GLPI) the value is normalised
+  to canonical Markdown before being assigned to the field, so attribute
+  access always returns Markdown.
+* On serialisation (outgoing request bodies built via
+  :func:`glpi_python_client.clients.commons._payloads.model_to_payload`)
+  the Markdown value is rendered back to HTML so GLPI receives the format
+  it expects.
+
+Plain-text content (no ``<...>`` markup) is preserved verbatim on the
+inbound path and rendered as HTML paragraphs on the outbound path, matching
+the converter's default behaviour. ``None`` values are passed through
+unchanged so optional fields and ``exclude_none`` semantics keep working.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import BeforeValidator, PlainSerializer
+
+from glpi_python_client.content.conversion import GlpiContentConverter
+
+
+def _from_transport(value: object) -> str | None:
+    """Normalise an inbound GLPI content value into canonical Markdown.
+
+    Pydantic invokes this before validation, so the field type stays ``str``
+    while the caller-visible value is always Markdown. ``None`` is preserved
+    unchanged so optional content fields keep their tri-state semantics.
+    """
+
+    if value is None:
+        return None
+    return GlpiContentConverter.from_transport(value)
+
+
+def _to_transport(value: str | None) -> str | None:
+    """Render an outbound Markdown content value as the HTML GLPI expects.
+
+    ``None`` is preserved so ``model_dump(exclude_none=True)`` continues to
+    drop unset fields from request bodies. Empty Markdown is rendered as an
+    empty string to stay consistent with the inbound converter behaviour.
+    """
+
+    if value is None:
+        return None
+    return GlpiContentConverter.to_transport(value)
+
+
+GlpiMarkdownContent = Annotated[
+    str | None,
+    BeforeValidator(_from_transport),
+    PlainSerializer(_to_transport, return_type=str | None, when_used="always"),
+]
+"""Annotated ``str | None`` that round-trips Markdown through GLPI's HTML wire format.
+
+Use this annotation on every model field that maps to a GLPI ``format: html``
+content slot (ticket descriptions, followup bodies, task bodies, solution
+bodies). The conversion is invisible to package users: the field accepts
+Markdown on construction, exposes Markdown on attribute access, and emits
+HTML on serialisation.
+"""
+
+__all__ = ["GlpiMarkdownContent"]

glpi_python_client/models/api_schema/_content.py

@@ -23,6 +23,7 @@
     IdNameCompletenameRef,
     IdNameRef,
 )
+from glpi_python_client.models.api_schema._content import GlpiMarkdownContent
 from glpi_python_client.models.api_schema.enums import (
     GlpiGlobalValidation,
     GlpiPriority,
@@ -59,7 +60,7 @@ class GetTicket(GlpiModel):
 
     id: int | None = None
     name: str | None = None
-    content: str | None = None
+    content: GlpiMarkdownContent = None
     user_recipient: IdNameRef | None = None
     user_editor: IdNameRef | None = None
     is_deleted: bool | None = None
@@ -111,7 +112,7 @@ class PostTicket(GlpiModel):
     """
 
     name: str | None = None
-    content: str | None = None
+    content: GlpiMarkdownContent = None
     is_deleted: bool | None = None
     category: IdNameRef | None = None
     location: IdNameRef | None = None

glpi_python_client/models/api_schema/assistance/_ticket.py

@@ -0,0 +1,102 @@
+"""Tests for transparent Markdown <-> HTML transport on content fields.
+
+The package contract is that every ``content`` field accepts and returns
+canonical Markdown while GLPI continues to receive HTML over the wire.
+These tests cover both directions on every model that exposes a Markdown
+content field, plus the inert behaviours (``None``, plain text round trip)
+that keep ``exclude_none`` semantics and non-HTML payloads stable.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from glpi_python_client.clients.commons._payloads import model_to_payload
+from glpi_python_client.models.api_schema.assistance import (
+    GetTicket,
+    PatchTicket,
+    PostTicket,
+)
+from glpi_python_client.models.api_schema.assistance.timeline import (
+    GetFollowup,
+    GetSolution,
+    GetTicketTask,
+    PostFollowup,
+    PostSolution,
+    PostTicketTask,
+)
+
+
+@pytest.mark.parametrize(
+    "model_cls",
+    [PostTicket, PatchTicket, PostFollowup, PostSolution, PostTicketTask],
+)
+def test_outgoing_markdown_is_rendered_to_html(model_cls: type) -> None:
+    """Markdown supplied by callers becomes HTML in the request payload."""
+
+    instance = model_cls(content="The printer is **offline**.")
+
+    payload = model_to_payload(instance)
+
+    assert payload["content"] == "<p>The printer is <strong>offline</strong>.</p>"
+
+
+@pytest.mark.parametrize(
+    "model_cls",
+    [PostTicket, PatchTicket, PostFollowup, PostSolution, PostTicketTask],
+)
+def test_outgoing_none_content_is_dropped_from_payload(
+    model_cls: type,
+) -> None:
+    """``None`` content stays ``None`` so ``exclude_none`` removes it."""
+
+    instance = model_cls()
+
+    payload = model_to_payload(instance)
+
+    assert "content" not in payload
+
+
+@pytest.mark.parametrize(
+    "model_cls",
+    [GetTicket, GetFollowup, GetSolution, GetTicketTask],
+)
+def test_incoming_html_is_normalised_to_markdown(model_cls: type) -> None:
+    """HTML returned by GLPI is normalised to Markdown on attribute access."""
+
+    instance = model_cls.model_validate(
+        {"content": "<p>The printer is <strong>offline</strong>.</p>"}
+    )
+
+    assert instance.content == "The printer is **offline**."
+
+
+@pytest.mark.parametrize(
+    "model_cls",
+    [GetTicket, GetFollowup, GetSolution, GetTicketTask],
+)
+def test_incoming_plain_text_passes_through(model_cls: type) -> None:
+    """Plain-text content (no HTML tags) is preserved verbatim."""
+
+    instance = model_cls.model_validate({"content": "Plain text body"})
+
+    assert instance.content == "Plain text body"
+
+
+def test_round_trip_preserves_markdown_intent() -> None:
+    """Markdown in -> HTML on the wire -> Markdown back on read."""
+
+    outgoing = PostTicket(name="Round trip", content="A **bold** statement.")
+    payload = model_to_payload(outgoing)
+
+    incoming = GetTicket.model_validate({"name": "Round trip", **payload})
+
+    assert incoming.content == "A **bold** statement."
+
+
+def test_outgoing_empty_string_renders_empty() -> None:
+    """Empty Markdown serialises to an empty string, not to ``<p></p>``."""
+
+    payload = model_to_payload(PostTicket(content=""))
+
+    assert payload["content"] == ""

glpi_python_client/models/api_schema/assistance/tests/test_content_roundtrip.py

@@ -15,6 +15,7 @@
 
 from glpi_python_client.models._base import GlpiModel
 from glpi_python_client.models.api_schema._common import IdNameRef
+from glpi_python_client.models.api_schema._content import GlpiMarkdownContent
 from glpi_python_client.models.api_schema.enums import GlpiTimelinePosition
 
 
@@ -27,7 +28,7 @@ class GetFollowup(GlpiModel):
     id: int | None = None
     itemtype: str | None = None
     items_id: int | None = None
-    content: str | None = None
+    content: GlpiMarkdownContent = None
     is_private: bool | None = None
     user: IdNameRef | None = None
     user_editor: IdNameRef | None = None
@@ -45,7 +46,7 @@ class PostFollowup(GlpiModel):
 
     itemtype: str | None = None
     items_id: int | None = None
-    content: str | None = None
+    content: GlpiMarkdownContent = None
     is_private: bool | None = None
     user: IdNameRef | None = None
     user_editor: IdNameRef | None = None

glpi_python_client/models/api_schema/assistance/timeline/_followup.py

@@ -15,6 +15,7 @@
 
 from glpi_python_client.models._base import GlpiModel
 from glpi_python_client.models.api_schema._common import IdNameRef
+from glpi_python_client.models.api_schema._content import GlpiMarkdownContent
 from glpi_python_client.models.api_schema.enums import GlpiSolutionStatus
 
 
@@ -28,7 +29,7 @@ class GetSolution(GlpiModel):
     itemtype: str | None = None
     items_id: int | None = None
     type: IdNameRef | None = None
-    content: str | None = None
+    content: GlpiMarkdownContent = None
     user: IdNameRef | None = None
     user_editor: IdNameRef | None = None
     approver: IdNameRef | None = None
@@ -45,7 +46,7 @@ class PostSolution(GlpiModel):
     itemtype: str | None = None
     items_id: int | None = None
     type: IdNameRef | None = None
-    content: str | None = None
+    content: GlpiMarkdownContent = None
     user: IdNameRef | None = None
     user_editor: IdNameRef | None = None
     approver: IdNameRef | None = None

glpi_python_client/models/api_schema/assistance/timeline/_solution.py

@@ -15,6 +15,7 @@
 
 from glpi_python_client.models._base import GlpiModel
 from glpi_python_client.models.api_schema._common import IdNameRef
+from glpi_python_client.models.api_schema._content import GlpiMarkdownContent
 from glpi_python_client.models.api_schema.enums import (
     GlpiTaskState,
     GlpiTimelinePosition,
@@ -29,7 +30,7 @@ class GetTicketTask(GlpiModel):
 
     id: int | None = None
     uuid: str | None = None
-    content: str | None = None
+    content: GlpiMarkdownContent = None
     is_private: bool | None = None
     user: IdNameRef | None = None
     user_editor: IdNameRef | None = None
@@ -52,7 +53,7 @@ class GetTicketTask(GlpiModel):
 class PostTicketTask(GlpiModel):
     """Request body for ``POST`` on ticket timeline task endpoints."""
 
-    content: str | None = None
+    content: GlpiMarkdownContent = None
     is_private: bool | None = None
     user: IdNameRef | None = None
     user_editor: IdNameRef | None = None