glpi-python-client 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

glpi_python_client/__init__.py

@@ -64,7 +64,7 @@ from glpi_python_client.models import (
     PostUser,
 )
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 __all__ = [
     "DeleteDocument",

glpi_python_client/models/custom_schema/_ticket_context.py

@@ -8,9 +8,14 @@ single object to reason about a ticket and its history.
 
 from __future__ import annotations
 
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
 from pydantic import Field
 
 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.assistance._ticket import GetTicket
 from glpi_python_client.models.api_schema.assistance.timeline._document import (
     GetTimelineDocument,
@@ -25,6 +30,78 @@ from glpi_python_client.models.api_schema.assistance.timeline._task import (
     GetTicketTask,
 )
 
+_MAX_DATETIME = datetime.max
+
+
+def _ref_label(ref: IdNameRef | None) -> str | None:
+    """Return the human-readable label of one ``IdNameRef`` reference.
+
+    The helper prefers ``name`` (the GLPI display label) and falls back to
+    the numeric identifier when the server only returned the foreign key.
+    Returns ``None`` when the reference itself is missing so callers can
+    omit the field from the rendered Markdown.
+    """
+
+    if ref is None:
+        return None
+    if ref.name:
+        return ref.name
+    if ref.id is not None:
+        return f"#{ref.id}"
+    return None
+
+
+def _render_value(value: object | None) -> str | None:
+    """Convert one supported metadata value into a display string.
+
+    The ticket-context Markdown view reuses one compact subtitle format
+    across the main ticket and every timeline item. This helper keeps
+    the formatting rules consistent for timestamps, GLPI references,
+    and enum values while leaving plain strings unchanged.
+    """
+
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, IdNameRef):
+        return _ref_label(value)
+    if isinstance(value, Enum):
+        return value.name.replace("_", " ").title()
+    return str(value)
+
+
+def _subtitle_line(*parts: tuple[str, object | None]) -> str | None:
+    """Build one Markdown subtitle line from labeled metadata values.
+
+    Missing values are skipped so callers can pass the full set of
+    potentially interesting fields without having to pre-filter them.
+    The subtitle is emitted as one Markdown blockquote line to make the
+    metadata visually distinct from the section body.
+    """
+
+    rendered_parts = []
+    for label, value in parts:
+        rendered_value = _render_value(value)
+        if rendered_value:
+            rendered_parts.append(f"{label}: {rendered_value}")
+    if not rendered_parts:
+        return None
+    return f"> {' | '.join(rendered_parts)}"
+
+
+def _event_sort_key(event: Any) -> datetime:
+    """Compute the sort key used to order timeline events for rendering.
+
+    Ticket context rendering must follow the actual activity chronology,
+    not the left/right anchoring hint used by the GLPI chat UI. Entries
+    are therefore always ordered by ``date_creation`` and items missing a
+    creation timestamp are pushed to the end while preserving the sort's
+    stability.
+    """
+
+    return getattr(event, "date_creation", None) or _MAX_DATETIME
+
 
 class GlpiTicketContext(GlpiModel):
     """Grouped public ticket context returned by ticket-context workflows.
@@ -49,5 +126,114 @@ class GlpiTicketContext(GlpiModel):
     solutions: list[GetSolution] = Field(default_factory=list)
     documents: list[GetTimelineDocument] = Field(default_factory=list)
 
+    def to_markdown(self) -> str:
+        """Render the ticket and its timeline as one Markdown transcript.
+
+        The rendering starts with the ticket title, then a compact
+        subtitle line containing the requester, last editor, and the
+        key timestamps exposed by the public ticket model. The ticket
+        body is separated from the timeline itself, and each followup,
+        task, and solution receives its own heading plus a metadata
+        subtitle. Timeline entries are always sorted by ``date_creation``
+        so the transcript follows the actual chronology rather than the
+        GLPI UI anchoring hints. Linked documents are still appended in a
+        dedicated section because the document-link payload does not
+        expose the same authoring metadata.
+
+        Returns
+        -------
+        str
+            Markdown transcript suitable for direct display or for
+            forwarding into a downstream Markdown renderer. The string
+            never ends with trailing whitespace.
+        """
+
+        lines: list[str] = []
+        ticket = self.ticket
+        ticket_label = ticket.name or "(unnamed ticket)"
+        if ticket.id is not None:
+            lines.append(f"# Ticket #{ticket.id} \u2014 {ticket_label}")
+        else:
+            lines.append(f"# Ticket \u2014 {ticket_label}")
+
+        ticket_subtitle = _subtitle_line(
+            ("Status", ticket.status),
+            ("Requester", ticket.user_recipient),
+            ("Last edited by", ticket.user_editor),
+            ("Created at", ticket.date_creation),
+            ("Updated at", ticket.date_mod),
+            ("Resolved at", ticket.date_solve),
+            ("Closed at", ticket.date_close),
+        )
+        if ticket_subtitle is not None:
+            lines.append(ticket_subtitle)
+
+        if ticket.content:
+            lines.append("")
+            lines.append("## Description")
+            lines.append("")
+            lines.append(ticket.content)
+
+        events: list[tuple[str, Any]] = []
+        events.extend(("Followup", item) for item in self.followups)
+        events.extend(("Task", item) for item in self.tasks)
+        events.extend(("Solution", item) for item in self.solutions)
+        events.sort(key=lambda pair: _event_sort_key(pair[1]))
+
+        if events:
+            lines.append("")
+            lines.append("## Timeline")
+
+        for kind, event in events:
+            event_id = getattr(event, "id", None)
+            heading = (
+                f"### {kind} #{event_id}" if event_id is not None else f"### {kind}"
+            )
+            lines.append("")
+            lines.append(heading)
+
+            event_subtitle = _subtitle_line(
+                ("Created by", getattr(event, "user", None)),
+                ("Last edited by", getattr(event, "user_editor", None)),
+                ("Created at", getattr(event, "date_creation", None)),
+                ("Updated at", getattr(event, "date_mod", None)),
+                ("Scheduled for", getattr(event, "date", None)),
+                ("Planned start", getattr(event, "planned_begin", None)),
+                ("Planned end", getattr(event, "planned_end", None)),
+                ("Approved at", getattr(event, "date_approval", None)),
+                ("State", getattr(event, "state", None)),
+                ("Status", getattr(event, "status", None)),
+                (
+                    "Duration",
+                    (
+                        f"{duration}s"
+                        if (duration := getattr(event, "duration", None)) is not None
+                        else None
+                    ),
+                ),
+                ("Technician", getattr(event, "user_tech", None)),
+                ("Technician group", getattr(event, "group_tech", None)),
+                ("Approver", getattr(event, "approver", None)),
+            )
+            if event_subtitle is not None:
+                lines.append(event_subtitle)
+
+            content = getattr(event, "content", None)
+            if content:
+                lines.append("")
+                lines.append(content)
+
+        if self.documents:
+            lines.append("")
+            lines.append("## Documents")
+            for document in self.documents:
+                identifier = document.documents_id or document.id
+                label = document.filepath or (
+                    f"document #{identifier}" if identifier is not None else "document"
+                )
+                lines.append(f"- {label}")
+
+        return "\n".join(lines).rstrip()
+
 
 __all__ = ["GlpiTicketContext"]

glpi_python_client/models/custom_schema/tests/test_ticket_context.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from datetime import datetime, timezone
+
 import pytest
 from pydantic import ValidationError
 
@@ -38,3 +40,171 @@ def test_ticket_context_accepts_timeline_records() -> None:
     context = GlpiTicketContext.model_validate(payload)
     assert context.tasks[0].id == 11
     assert context.documents[0].documents_id == 99
+
+
+def test_to_markdown_renders_header_and_status() -> None:
+    """``to_markdown`` includes the ticket id, name, status and content."""
+
+    context = GlpiTicketContext.model_validate(
+        {
+            "ticket": {
+                "id": 42,
+                "name": "Printer broken",
+                "content": "Cannot print",
+                "status": {"id": 2, "name": "Processing (assigned)"},
+            }
+        }
+    )
+    rendered = context.to_markdown()
+    assert rendered.startswith("# Ticket #42 \u2014 Printer broken")
+    assert "> Status: Processing (assigned)" in rendered
+    assert "## Description" in rendered
+    assert "Cannot print" in rendered
+
+
+def test_to_markdown_renders_ticket_subtitle_metadata() -> None:
+    """The main ticket subtitle includes requester, editor, and timestamps."""
+
+    context = GlpiTicketContext.model_validate(
+        {
+            "ticket": {
+                "id": 42,
+                "name": "Printer broken",
+                "user_recipient": {"id": 7, "name": "Alice"},
+                "user_editor": {"id": 8, "name": "Bob"},
+                "date_creation": datetime(2024, 1, 1, 9, 30, tzinfo=timezone.utc),
+                "date_mod": datetime(2024, 1, 2, 11, 45, tzinfo=timezone.utc),
+            }
+        }
+    )
+
+    rendered = context.to_markdown()
+
+    assert "Requester: Alice" in rendered
+    assert "Last edited by: Bob" in rendered
+    assert "Created at: 2024-01-01T09:30:00+00:00" in rendered
+    assert "Updated at: 2024-01-02T11:45:00+00:00" in rendered
+
+
+def test_to_markdown_orders_events_by_creation_when_no_position() -> None:
+    """Events without ``timeline_position`` are ordered by creation date."""
+
+    context = GlpiTicketContext.model_validate(
+        {
+            "ticket": {"id": 1, "name": "x"},
+            "followups": [
+                {
+                    "id": 2,
+                    "content": "second note",
+                    "date_creation": datetime(2024, 1, 2, tzinfo=timezone.utc),
+                },
+                {
+                    "id": 1,
+                    "content": "first note",
+                    "date_creation": datetime(2024, 1, 1, tzinfo=timezone.utc),
+                },
+            ],
+        }
+    )
+    rendered = context.to_markdown()
+    assert rendered.index("first note") < rendered.index("second note")
+
+
+def test_to_markdown_ignores_timeline_position_for_ordering() -> None:
+    """Timeline anchoring does not override chronological ordering."""
+
+    context = GlpiTicketContext.model_validate(
+        {
+            "ticket": {"id": 1, "name": "x"},
+            "followups": [
+                {
+                    "id": 1,
+                    "content": "no position late",
+                    "date_creation": datetime(2024, 1, 5, tzinfo=timezone.utc),
+                },
+            ],
+            "tasks": [
+                {
+                    "id": 2,
+                    "content": "left positioned",
+                    "timeline_position": 1,
+                    "date_creation": datetime(2024, 1, 10, tzinfo=timezone.utc),
+                },
+            ],
+        }
+    )
+    rendered = context.to_markdown()
+    assert rendered.index("no position late") < rendered.index("left positioned")
+    assert "## Timeline" in rendered
+    assert "### Task #2" in rendered
+    assert "### Followup #1" in rendered
+
+
+def test_to_markdown_renders_solution_and_documents() -> None:
+    """Solutions and document links are rendered with their dedicated sections."""
+
+    context = GlpiTicketContext.model_validate(
+        {
+            "ticket": {"id": 7, "name": "Reset"},
+            "solutions": [{"id": 4, "content": "All fixed"}],
+            "documents": [
+                {"id": 11, "documents_id": 99, "filepath": "logs/run.txt"},
+                {"id": 12, "documents_id": 100},
+            ],
+        }
+    )
+    rendered = context.to_markdown()
+    assert "### Solution #4" in rendered
+    assert "All fixed" in rendered
+    assert "## Documents" in rendered
+    assert "- logs/run.txt" in rendered
+    assert "- document #100" in rendered
+
+
+def test_to_markdown_handles_empty_timeline() -> None:
+    """A ticket with no events still produces a valid Markdown header."""
+
+    context = GlpiTicketContext.model_validate({"ticket": {"id": 3, "name": "Quiet"}})
+    rendered = context.to_markdown()
+    assert rendered == "# Ticket #3 \u2014 Quiet"
+
+
+def test_to_markdown_renders_task_duration() -> None:
+    """Tasks expose their ``duration`` field in seconds."""
+
+    context = GlpiTicketContext.model_validate(
+        {
+            "ticket": {"id": 1, "name": "x"},
+            "tasks": [{"id": 9, "content": "work", "duration": 1800}],
+        }
+    )
+    rendered = context.to_markdown()
+    assert "> Duration: 1800s" in rendered
+
+
+def test_to_markdown_renders_event_creator_editor_and_timestamps() -> None:
+    """Timeline subtitles include author, editor, and timestamp metadata."""
+
+    context = GlpiTicketContext.model_validate(
+        {
+            "ticket": {"id": 1, "name": "x"},
+            "followups": [
+                {
+                    "id": 12,
+                    "content": "note",
+                    "user": {"id": 7, "name": "Alice"},
+                    "user_editor": {"id": 8, "name": "Bob"},
+                    "date_creation": datetime(2024, 1, 2, 10, 0, tzinfo=timezone.utc),
+                    "date_mod": datetime(2024, 1, 2, 10, 5, tzinfo=timezone.utc),
+                }
+            ],
+        }
+    )
+
+    rendered = context.to_markdown()
+
+    assert "### Followup #12" in rendered
+    assert "Created by: Alice" in rendered
+    assert "Last edited by: Bob" in rendered
+    assert "Created at: 2024-01-02T10:00:00+00:00" in rendered
+    assert "Updated at: 2024-01-02T10:05:00+00:00" in rendered

{glpi_python_client-0.2.0.dist-info → glpi_python_client-0.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: glpi-python-client
-Version: 0.2.0
+Version: 0.2.1
 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.2.0.dist-info → glpi_python_client-0.2.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-glpi_python_client/__init__.py,sha256=dvP_bOZBNLXIMt05cJ-9G5uAllPnrxC3KdNPLbDE2Z8,2614
+glpi_python_client/__init__.py,sha256=COSBZDaTdbd29TBO8qFMDCSIIf3AZELcnwHY_5QrAkY,2614
 glpi_python_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 glpi_python_client/auth/__init__.py,sha256=rvvca0KTgvI2bkTSYX-h5KxpPpHQd2n9UFYl0nHAJ_Y,457
 glpi_python_client/auth/_v1_session.py,sha256=R_SlKBrFJXCmXF0K3rmGAqkxH8cjaltItOJstcd-GVY,10263
@@ -81,13 +81,13 @@ glpi_python_client/models/api_schema/management/_document.py,sha256=Q-Tvo2fj9jzQ
 glpi_python_client/models/api_schema/management/tests/__init__.py,sha256=c_aRMSPAlwOgz_YlkII5mvYgr780F4Du4eSnZn5ITpM,63
 glpi_python_client/models/api_schema/management/tests/test_management_schemas.py,sha256=wMM8287WBhDUezKezCgINMyxqwjtYxpYRTKkRpmRNTI,1473
 glpi_python_client/models/custom_schema/__init__.py,sha256=hB9OfuJzV6cF6jwvrLeT2CJhFHTqXYC5VlmwOoRknck,448
-glpi_python_client/models/custom_schema/_ticket_context.py,sha256=HTOVvL6bLh0i1A33DG8Qw79Fs2ckMvp9BzIYSzL3HMI,1805
+glpi_python_client/models/custom_schema/_ticket_context.py,sha256=G-W1IDY6JSv1FF2X2ntRKzso8GJAvPUcAlesv-MzdFc,8952
 glpi_python_client/models/custom_schema/tests/__init__.py,sha256=62-bctnIbC39LbL18mCX10ItpxeqFvpORXslREcqjzs,55
-glpi_python_client/models/custom_schema/tests/test_ticket_context.py,sha256=jr_ipxyQBPYEjjiZ4CiaQX_ljbkda6uG1iOnPe6cvZA,1365
+glpi_python_client/models/custom_schema/tests/test_ticket_context.py,sha256=yZHQqFJGlg7X4rh8FIX6OAlNb4lKvF1yvirOXUf0WxQ,7195
 glpi_python_client/testing/__init__.py,sha256=ilUPAUlbMa2NuXiRGZjC97argNKMnJ-heK_kf7fotkE,512
 glpi_python_client/testing/fixtures.py,sha256=VQ-blVMyG706SR7SWuTW2UYr_nGa1qjKVnLwpsUFgHc,758
 glpi_python_client/testing/utils.py,sha256=MtfHRKVDW_Lq8LrDaY9U6QaFvU-K0CnXMV4ZvJyVyzU,3054
-glpi_python_client-0.2.0.dist-info/METADATA,sha256=cegISZjSMa4flRNaHJUYCLyCEL18B80rtVbwujH78PE,6351
-glpi_python_client-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-glpi_python_client-0.2.0.dist-info/licenses/LICENSE,sha256=nL8re-TIKkxCoL7OkSBja6EB4NsQR1HoOJgxv_MEhtc,1088
-glpi_python_client-0.2.0.dist-info/RECORD,,
+glpi_python_client-0.2.1.dist-info/METADATA,sha256=M8mNSEvZZjLZIeKyO-n_2WgBERzX8cfW4GNi33qXd2M,6351
+glpi_python_client-0.2.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+glpi_python_client-0.2.1.dist-info/licenses/LICENSE,sha256=nL8re-TIKkxCoL7OkSBja6EB4NsQR1HoOJgxv_MEhtc,1088
+glpi_python_client-0.2.1.dist-info/RECORD,,