glpi-python-client 0.1.0__py3-none-any.whl

glpi_python_client/models/glpi/_ticket.py

@@ -0,0 +1,303 @@
+"""Typed GLPI ticket model.
+
+The ticket model is the richest object in the package and can hold both the
+core ticket fields and related timeline, document, and team data.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from datetime import datetime
+from typing import Any
+
+from glpi_python_client.content.conversion import GlpiContentConverter
+from glpi_python_client.models._base import GlpiModel
+from glpi_python_client.models._payload import (
+    ApiPayloadMixin,
+    drop_empty_payload_values,
+)
+from glpi_python_client.models._shared import _model_data
+from glpi_python_client.models.glpi._document import GlpiDocument
+from glpi_python_client.models.glpi._followup import GlpiFollowup
+from glpi_python_client.models.glpi._solution import GlpiSolution
+from glpi_python_client.models.glpi._task import GlpiTask
+from glpi_python_client.models.glpi._team_member import GlpiTeamMember
+from glpi_python_client.models.glpi._user import GlpiUser
+
+
+def _glpi_user_from_value(value: object | None) -> GlpiUser | None:
+    if value is None:
+        return None
+    if isinstance(value, GlpiUser):
+        return value
+    return GlpiUser.model_validate(_model_data(value))
+
+
+def _datetime_from_data(value: object) -> datetime | None:
+    return value if isinstance(value, datetime) else None
+
+
+def _glpi_followup_from_value(value: object) -> GlpiFollowup:
+    if isinstance(value, GlpiFollowup):
+        return value
+    data = _model_data(value)
+    author = _glpi_user_from_value(data.get("author"))
+    author_id = data.get("author_id")
+    if author is None and author_id is not None:
+        author = GlpiUser(user_id=str(author_id))
+    return GlpiFollowup(
+        followup_id=_optional_text(data.get("followup_id")),
+        content=GlpiContentConverter.from_transport(data.get("content")),
+        created_at=_datetime_from_data(data.get("created_at")),
+        updated_at=_datetime_from_data(data.get("updated_at")),
+        author=author,
+        editor=_glpi_user_from_value(data.get("editor")),
+        is_private=bool(data.get("is_private", False)),
+        attachment_document_ids=tuple(
+            str(document_id) for document_id in data.get("attachment_document_ids", ())
+        ),
+    )
+
+
+def _glpi_solution_from_value(value: object) -> GlpiSolution:
+    if isinstance(value, GlpiSolution):
+        return value
+    data = _model_data(value)
+    author = _glpi_user_from_value(data.get("author"))
+    author_id = data.get("author_id")
+    if author is None and author_id is not None:
+        author = GlpiUser(user_id=str(author_id))
+    return GlpiSolution(
+        solution_id=_optional_text(data.get("solution_id")),
+        content=GlpiContentConverter.from_transport(data.get("content")),
+        created_at=_datetime_from_data(data.get("created_at")),
+        updated_at=_datetime_from_data(data.get("updated_at")),
+        author=author,
+        attachment_document_ids=tuple(
+            str(document_id) for document_id in data.get("attachment_document_ids", ())
+        ),
+    )
+
+
+def _glpi_task_from_value(value: object) -> GlpiTask:
+    if isinstance(value, GlpiTask):
+        return value
+    data = _model_data(value)
+    author = _glpi_user_from_value(data.get("author"))
+    author_id = data.get("author_id")
+    if author is None and author_id is not None:
+        author = GlpiUser(user_id=str(author_id))
+    editor = _glpi_user_from_value(data.get("editor"))
+    editor_id = data.get("editor_id")
+    if editor is None and editor_id is not None:
+        editor = GlpiUser(user_id=str(editor_id))
+    return GlpiTask(
+        task_id=_optional_text(data.get("task_id")),
+        content=GlpiContentConverter.from_transport(data.get("content")),
+        created_at=_datetime_from_data(data.get("created_at")),
+        updated_at=_datetime_from_data(data.get("updated_at")),
+        author=author,
+        editor=editor,
+        is_private=bool(data.get("is_private", False)),
+    )
+
+
+def _glpi_document_from_value(value: object) -> GlpiDocument:
+    if isinstance(value, GlpiDocument):
+        return value
+    return GlpiDocument.model_validate(_model_data(value))
+
+
+def _glpi_team_member_from_value(value: object) -> GlpiTeamMember:
+    if isinstance(value, GlpiTeamMember):
+        return value
+    return GlpiTeamMember.model_validate(_model_data(value))
+
+
+def _normalize_glpi_ticket_updates(updates: Mapping[str, Any]) -> dict[str, Any]:
+    normalized: dict[str, Any] = {}
+    for key, value in updates.items():
+        if key in {"user_recipient", "user_editor"}:
+            normalized[key] = _glpi_user_from_value(value)
+        elif key == "followups":
+            normalized[key] = tuple(_glpi_followup_from_value(item) for item in value)
+        elif key == "tasks":
+            normalized[key] = tuple(_glpi_task_from_value(item) for item in value)
+        elif key == "solutions":
+            normalized[key] = tuple(_glpi_solution_from_value(item) for item in value)
+        elif key == "documents":
+            normalized[key] = tuple(_glpi_document_from_value(item) for item in value)
+        elif key == "team":
+            normalized[key] = tuple(
+                _glpi_team_member_from_value(item) for item in value
+            )
+        else:
+            normalized[key] = value
+    return normalized
+
+
+class GlpiTicket(ApiPayloadMixin, GlpiModel):
+    """GLPI ticket record.
+
+    Textual ``content`` is stored as canonical Markdown in Python. It is rendered
+    to GLPI HTML only when :meth:`to_api_payload` builds an outgoing payload.
+    """
+
+    id: str | None = None
+    name: str | None = None
+    content: str | None = None
+    status: int | dict[str, object] | None = None
+    urgency: int | None = None
+    impact: int | None = None
+    priority: int | None = None
+    type: int | None = None
+    external_id: str | None = None
+    category: int | dict[str, object] | None = None
+    entity: int | dict[str, object] | None = None
+    location: str | int | dict[str, object] | None = None
+    request_type: str | dict[str, object] | None = None
+    date_creation: datetime | None = None
+    date_mod: datetime | None = None
+    date_close: datetime | None = None
+    user_recipient: GlpiUser | None = None
+    user_editor: GlpiUser | None = None
+    followups: tuple[GlpiFollowup, ...] = ()
+    tasks: tuple[GlpiTask, ...] = ()
+    solutions: tuple[GlpiSolution, ...] = ()
+    documents: tuple[GlpiDocument, ...] = ()
+    team: tuple[GlpiTeamMember, ...] = ()
+
+    @classmethod
+    def from_record(
+        cls, record: GlpiTicket | Mapping[str, Any], **updates: Any
+    ) -> GlpiTicket:
+        """Build a ticket instance from an existing record and override values.
+
+        The helper accepts either an existing ``GlpiTicket`` or a normalized
+        mapping and then applies any requested updates through the same model
+        validation path as direct construction.
+        """
+
+        if isinstance(record, cls):
+            base_data = record.model_dump(mode="python")
+        else:
+            base_data = dict(record)
+        if updates:
+            base_data.update(_normalize_glpi_ticket_updates(updates))
+        return cls.model_validate(base_data)
+
+    def updated_at(self) -> datetime:
+        """Return the best available update timestamp for the ticket.
+
+        When GLPI does not provide ``date_mod``, the current local timestamp is
+        used as a fallback so caller code always receives a ``datetime`` value.
+        """
+
+        return self.date_mod or datetime.now().astimezone()
+
+    def _build_api_payload(
+        self,
+        *,
+        entity_id: int | None = None,
+        include_entity: bool = False,
+        field_mask: tuple[str, ...] = (),
+        category_defaults: Mapping[str, int] | Sequence[int] | None = None,
+        default_status: int | None = None,
+        default_priority: int | None = None,
+        default_type: int | None = None,
+    ) -> dict[str, object]:
+        """Build the raw GLPI API request body for the ticket.
+
+        The payload builder applies the package's defaulting rules for entity,
+        status, priority, type, and category fields before optionally trimming
+        the result with a field mask.
+        """
+
+        status = (
+            _glpi_field_id(self.status)
+            if self.status is not None
+            else (default_status if include_entity else None)
+        )
+        priority = (
+            self.priority
+            if self.priority is not None
+            else (default_priority if include_entity else None)
+        )
+        glpi_type = (
+            self.type
+            if self.type is not None
+            else (default_type if include_entity else None)
+        )
+        category = _glpi_field_id(self.category) or _category_from_defaults(
+            category_defaults, _glpi_field_name(self.category)
+        )
+        payload = drop_empty_payload_values(
+            {
+                "name": self.name,
+                "content": GlpiContentConverter.to_transport(self.content)
+                if self.content is not None
+                else None,
+                "status": _id_object(status),
+                "urgency": self.urgency,
+                "impact": self.impact,
+                "priority": priority,
+                "type": glpi_type,
+                "external_id": self.external_id,
+                "category": _id_object(category),
+                "location": _id_object(_glpi_field_id(self.location)),
+                "entity": _id_object(
+                    entity_id if entity_id is not None else _glpi_field_id(self.entity)
+                )
+                if include_entity
+                else None,
+            }
+        )
+        if not field_mask:
+            return payload
+        return {key: value for key, value in payload.items() if key in field_mask}
+
+
+def _optional_text(value: object) -> str | None:
+    text = str(value).strip() if value is not None else ""
+    return text or None
+
+
+def _id_object(value: object) -> dict[str, object] | None:
+    if value is None:
+        return None
+    return {"id": value}
+
+
+def _glpi_field_id(value: object) -> object | None:
+    if isinstance(value, Mapping):
+        return value.get("id")
+    return value
+
+
+def _glpi_field_name(value: object) -> str | None:
+    if not isinstance(value, Mapping):
+        return None
+    text = str(value.get("name", "")).strip()
+    return text or None
+
+
+def _category_from_defaults(
+    category_defaults: Mapping[str, int] | Sequence[int] | None,
+    category_label: str | None,
+) -> object | None:
+    if not category_defaults:
+        return None
+    if isinstance(category_defaults, Mapping):
+        if category_label:
+            expected = category_label.casefold()
+            for key, value in category_defaults.items():
+                if str(key).casefold() == expected:
+                    return value
+        return None
+    for value in category_defaults:
+        if value is not None:
+            return value
+    return None
+
+
+__all__ = ["GlpiTicket"]

glpi_python_client/models/glpi/_user.py

@@ -0,0 +1,92 @@
+"""Typed GLPI user model.
+
+The user model is used for parsed directory records, embedded ticket users, and
+outgoing user-creation payloads.
+"""
+
+from __future__ import annotations
+
+from glpi_python_client.models._base import GlpiModel
+from glpi_python_client.models._payload import (
+    ApiPayloadMixin,
+    drop_empty_payload_values,
+)
+
+
+class GlpiUser(ApiPayloadMixin, GlpiModel):
+    """GLPI user rich object.
+
+    Parameters
+    ----------
+    user_id : str | None, optional
+        Native GLPI user identifier.
+    email : str | None, optional
+        User email address.
+    firstname : str | None, optional
+        First name.
+    realname : str | None, optional
+        Last name.
+    name : str | None, optional
+        Display name.
+    entity_id : int | None, optional
+        Owning GLPI entity.
+    default_is_notifications_enabled : bool | None, optional
+        Default GLPI user notification preference.
+    """
+
+    user_id: str | None = None
+    email: str | None = None
+    firstname: str | None = None
+    realname: str | None = None
+    name: str | None = None
+    entity_id: int | None = None
+    default_is_notifications_enabled: bool | None = None
+
+    def _build_api_payload(self) -> dict[str, object]:
+        """Return the raw GLPI user-create request body.
+
+        Returns
+        -------
+        dict[str, object]
+            Raw GLPI user-create request body.
+
+        Raises
+        ------
+        ValueError
+            Raised when neither a name nor an email is available.
+        """
+
+        username = _first_not_none(self.email, self.name, self.user_id)
+        if username is None:
+            raise ValueError("GLPI user creation requires at least a name or email")
+        firstname = self.firstname
+        realname = self.realname
+        fallback_identity = _first_not_none(self.name, self.email, username)
+        if firstname is None and realname is None:
+            firstname = fallback_identity
+            realname = ""
+        else:
+            firstname = firstname or ""
+            realname = realname or ""
+        payload: dict[str, object] = {
+            "id": self.user_id,
+            "username": username,
+            "email": self.email,
+            "realname": realname,
+            "firstname": firstname,
+            "name": self.name if self.name is not None else username,
+        }
+        if self.entity_id is not None:
+            payload["default_entity"] = {"id": self.entity_id}
+        if self.default_is_notifications_enabled is not None:
+            payload["default_is_notifications_enabled"] = (
+                self.default_is_notifications_enabled
+            )
+        return drop_empty_payload_values(payload)
+
+
+def _first_not_none(*values: str | None) -> str | None:
+    for value in values:
+        if value is not None:
+            return value
+    return None

glpi_python_client/models/glpi/tests/__init__.py

@@ -0,0 +1,5 @@
+"""Model tests colocated with the concrete GLPI model package.
+
+Keeping these tests near the model definitions helps track validation and
+serialization behavior as the typed objects evolve.
+"""

glpi_python_client/models/glpi/tests/test__document.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from glpi_python_client import GlpiDocument
+
+
+def test_document_upload_payload_defaults_mime_type() -> None:
+    document = GlpiDocument(ticket_id=123, filename="trace.txt", content=b"trace")
+
+    payload = document.to_api_payload()
+
+    assert payload["mime_type"] == "application/octet-stream"
+    assert payload["content"] == b"trace"

glpi_python_client/models/glpi/tests/test__followup.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from glpi_python_client import GlpiFollowup, GlpiUser
+
+
+def test_followup_model_copy_returns_updated_model() -> None:
+    followup = GlpiFollowup(content="hello")
+
+    updated = followup.model_copy(update={"followup_id": "42"})
+
+    assert followup.followup_id is None
+    assert updated.followup_id == "42"
+
+
+def test_followup_payload_renders_markdown_to_html() -> None:
+    followup = GlpiFollowup(content="Observed **again**")
+
+    assert followup.to_api_payload()["content"] == (
+        "<p>Observed <strong>again</strong></p>"
+    )
+
+
+def test_followup_payload_preserves_raw_user_ids() -> None:
+    followup = GlpiFollowup(
+        content="Observed **again**",
+        author=GlpiUser(user_id="0012"),
+        editor=GlpiUser(user_id=" user-7 "),
+    )
+
+    assert followup.to_api_payload()["user"] == {"id": "0012"}
+    assert followup.to_api_payload()["user_editor"] == {"id": " user-7 "}

glpi_python_client/models/glpi/tests/test__location.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from glpi_python_client import GlpiLocation
+
+
+def test_location_payload_preserves_raw_location_id() -> None:
+    location = GlpiLocation(location_id="0012", name="Paris")
+
+    payload = location.to_api_payload()
+
+    assert payload["id"] == "0012"
+    assert payload["name"] == "Paris"

glpi_python_client/models/glpi/tests/test__solution.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from glpi_python_client import GlpiSolution
+
+
+def test_solution_payload_renders_markdown_to_html() -> None:
+    solution = GlpiSolution(content="Rebooted and **validated**")
+
+    assert solution.to_api_payload()["content"] == (
+        "<p>Rebooted and <strong>validated</strong></p>"
+    )

glpi_python_client/models/glpi/tests/test__ticket.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from glpi_python_client import GlpiTicket
+
+
+def test_ticket_payload_uses_glpi_high_level_shapes() -> None:
+    ticket = GlpiTicket(
+        name="Printer issue",
+        content="Cannot print from accounting",
+        status=2,
+        urgency=3,
+        impact=4,
+        priority=5,
+        type=1,
+        category=10,
+        location="12",
+    )
+
+    payload = ticket.to_api_payload(entity_id=7, include_entity=True)
+
+    assert payload == {
+        "name": "Printer issue",
+        "content": "<p>Cannot print from accounting</p>",
+        "status": {"id": 2},
+        "urgency": 3,
+        "impact": 4,
+        "priority": 5,
+        "type": 1,
+        "category": {"id": 10},
+        "location": {"id": "12"},
+        "entity": {"id": 7},
+    }
+
+
+def test_ticket_payload_field_mask_accepts_model_field_names() -> None:
+    ticket = GlpiTicket(name="Updated", status=3, priority=4)
+
+    payload = ticket.to_api_payload(field_mask=("name", "status"))
+
+    assert payload == {"name": "Updated", "status": {"id": 3}}
+
+
+def test_ticket_payload_merges_public_extra_payload() -> None:
+    ticket = GlpiTicket(
+        name="Access badge reader offline",
+        extra_payload={
+            "_room_code": "PAR-3F-12",
+            "_asset_tag": "BADGE-READER-044",
+            "_ignored": None,
+        },
+    )
+
+    payload = ticket.to_api_payload()
+
+    assert payload == {
+        "name": "Access badge reader offline",
+        "_room_code": "PAR-3F-12",
+        "_asset_tag": "BADGE-READER-044",
+    }

glpi_python_client/models/glpi/tests/test__user.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from glpi_python_client import GlpiUser
+
+
+def test_user_payload_uses_email_as_username() -> None:
+    user = GlpiUser(email="jane@example.test", firstname="Jane", realname="Doe")
+
+    payload = user.to_api_payload()
+
+    assert payload["username"] == "jane@example.test"
+    assert payload["name"] == "jane@example.test"
+
+
+def test_user_payload_preserves_raw_input_text() -> None:
+    user = GlpiUser(
+        user_id="0012",
+        email=" jane@example.test ",
+        firstname=" Jane ",
+        realname=" Doe ",
+    )
+
+    payload = user.to_api_payload()
+
+    assert payload["id"] == "0012"
+    assert payload["username"] == " jane@example.test "
+    assert payload["firstname"] == " Jane "
+    assert payload["realname"] == " Doe "
+    assert payload["name"] == " jane@example.test "

glpi_python_client/testing/__init__.py

@@ -0,0 +1,27 @@
+"""Shared testing exports for the GLPI client package.
+
+This package gathers reusable fake responses, record builders, and client
+factories so unit tests can share realistic test data without repeating setup.
+"""
+
+from __future__ import annotations
+
+from glpi_python_client.testing.utils import (
+    FakeResponse,
+    SearchResponse,
+    TicketResponse,
+    TokenResponse,
+    make_client,
+    make_followup_record,
+    make_ticket_record,
+)
+
+__all__ = [
+    "FakeResponse",
+    "SearchResponse",
+    "TicketResponse",
+    "TokenResponse",
+    "make_client",
+    "make_followup_record",
+    "make_ticket_record",
+]

glpi_python_client/testing/fixtures.py

@@ -0,0 +1,52 @@
+"""Pytest fixtures backed by shared glpi_python_client test utilities.
+
+These fixtures provide common sample clients and payloads for unit tests while
+delegating the concrete data construction to the shared testing utilities.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import pytest
+
+from glpi_python_client import GlpiClient
+from glpi_python_client.testing.utils import (
+    make_client,
+    make_followup_record,
+    make_ticket_record,
+)
+
+
+@pytest.fixture
+def client_factory() -> Callable[..., GlpiClient]:
+    """Return the reusable GLPI client factory fixture.
+
+    Tests can call the returned factory with overrides to create focused client
+    instances without duplicating base configuration.
+    """
+
+    return make_client
+
+
+@pytest.fixture
+def sample_followup_record() -> dict[str, Any]:
+    """Return a representative raw GLPI followup payload fixture.
+
+    The payload mirrors the structure expected by the content parsing tests and
+    can be overridden in higher-level helpers when needed.
+    """
+
+    return make_followup_record()
+
+
+@pytest.fixture
+def sample_ticket_record() -> dict[str, Any]:
+    """Return a representative raw GLPI ticket payload fixture.
+
+    The payload captures the common ticket fields exercised by the parsing and
+    client tests.
+    """
+
+    return make_ticket_record()