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

glpi_python_client/models/_payload.py

@@ -0,0 +1,79 @@
+"""Shared API payload serialization helpers for rich ticket objects.
+
+These helpers keep payload cleanup and the uniform payload entrypoint in one
+place for all models that can be sent back to GLPI.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from typing import Any
+
+
+def drop_empty_payload_values(payload: Mapping[str, object]) -> dict[str, object]:
+    """Return a payload without empty values that GLPI should not receive.
+
+    ``None``, empty mappings, and empty sequences are removed so outgoing API
+    payloads stay concise and avoid sending meaningless placeholders to GLPI.
+    """
+
+    return {
+        key: value
+        for key, value in payload.items()
+        if value is not None and value != {} and value != []
+    }
+
+
+class ApiPayloadMixin(ABC):
+    """Mixin exposing one uniform API payload entrypoint.
+
+    Notes
+    -----
+    Subclasses must implement ``_build_api_payload`` with the keyword
+    arguments they require. The public ``to_api_payload`` method remains the
+    shared entrypoint used by transport clients.
+    """
+
+    def to_api_payload(self, *args: Any, **kwargs: Any) -> dict[str, object]:
+        """Return the raw API payload for the model.
+
+        Parameters
+        ----------
+        *args : object
+            Positional arguments forwarded to the payload builder.
+        **kwargs : object
+            Keyword arguments forwarded to the payload builder.
+
+        Returns
+        -------
+        dict[str, object]
+            Raw API payload.
+        """
+
+        payload = dict(self._build_api_payload(*args, **kwargs))
+        extra_payload = getattr(self, "extra_payload", None)
+        if not isinstance(extra_payload, Mapping) or not extra_payload:
+            return payload
+
+        merged_payload = dict(payload)
+        merged_payload.update(drop_empty_payload_values(extra_payload))
+        return drop_empty_payload_values(merged_payload)
+
+    @abstractmethod
+    def _build_api_payload(self, *args: Any, **kwargs: Any) -> Mapping[str, object]:
+        """Build the raw API payload for the concrete model.
+
+        Parameters
+        ----------
+        *args : object
+            Positional arguments supplied by the caller.
+        **kwargs : object
+            Keyword arguments supplied by the caller.
+
+        Returns
+        -------
+        dict[str, object]
+            Raw API payload.
+
+        """

glpi_python_client/models/_shared.py

@@ -0,0 +1,37 @@
+"""Shared helper functions for rich ticket normalization.
+
+This module contains small model-normalization helpers used by the richer GLPI
+objects when they accept either typed models or plain mappings.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def _model_data(value: object) -> dict[str, Any]:
+    """Normalize one model-like value to a plain mapping.
+
+    Parameters
+    ----------
+    value : object
+        Model-like value to normalize.
+
+    Returns
+    -------
+    dict[str, Any]
+        Plain mapping representation of the value.
+
+    Raises
+    ------
+    TypeError
+        Raised when the value is neither a Pydantic model nor a mapping.
+    """
+
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="python")
+    if isinstance(value, dict):
+        return dict(value)
+    raise TypeError(f"Unsupported model value {type(value)!r}")

glpi_python_client/models/glpi/__init__.py

@@ -0,0 +1,27 @@
+"""Concrete GLPI model exports used by the high-level v2 clients.
+
+This subpackage groups the rich ticket-related models that the client returns
+and accepts when interacting with GLPI resources.
+"""
+
+from __future__ import annotations
+
+from glpi_python_client.models.glpi._document import GlpiDocument
+from glpi_python_client.models.glpi._followup import GlpiFollowup
+from glpi_python_client.models.glpi._location import GlpiLocation
+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._ticket import GlpiTicket
+from glpi_python_client.models.glpi._user import GlpiUser
+
+__all__ = [
+    "GlpiDocument",
+    "GlpiFollowup",
+    "GlpiLocation",
+    "GlpiSolution",
+    "GlpiTask",
+    "GlpiTeamMember",
+    "GlpiTicket",
+    "GlpiUser",
+]

glpi_python_client/models/glpi/_document.py

@@ -0,0 +1,59 @@
+"""Typed GLPI document model.
+
+The document model represents both fetched document metadata and the input data
+needed by the legacy upload workflow.
+"""
+
+from __future__ import annotations
+
+from glpi_python_client.models._base import GlpiModel
+from glpi_python_client.models._payload import ApiPayloadMixin
+
+
+class GlpiDocument(ApiPayloadMixin, GlpiModel):
+    """GLPI document rich object.
+
+    Parameters
+    ----------
+    document_id : str | None, optional
+        Native GLPI document identifier.
+    filename : str | None, optional
+        Document filename.
+    mime_type : str | None, optional
+        MIME type.
+    linked_document_id : str | None, optional
+        Linked GLPI document identifier when different from ``document_id``.
+    ticket_id : int | None, optional
+        Owning ticket ID for uploads.
+    content : bytes | None, optional
+        Binary payload used for uploads.
+    document_name : str | None, optional
+        GLPI document title used during upload.
+    """
+
+    document_id: str | None = None
+    filename: str | None = None
+    mime_type: str | None = None
+    linked_document_id: str | None = None
+    ticket_id: int | str | None = None
+    content: bytes | None = None
+    document_name: str | None = None
+
+    def _build_api_payload(self) -> dict[str, object]:
+        """Return the raw upload payload consumed by the GLPI document gateway.
+
+        Returns
+        -------
+        dict[str, object]
+            Raw upload payload.
+        """
+
+        return {
+            "ticket_id": self.ticket_id,
+            "filename": self.filename,
+            "content": self.content,
+            "mime_type": self.mime_type
+            if self.mime_type is not None
+            else "application/octet-stream",
+            "document_name": self.document_name,
+        }

glpi_python_client/models/glpi/_followup.py

@@ -0,0 +1,77 @@
+"""Typed GLPI followup model.
+
+The followup model stores normalized Markdown content and the metadata returned
+by GLPI timeline endpoints.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+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.glpi._user import GlpiUser
+
+
+class GlpiFollowup(ApiPayloadMixin, GlpiModel):
+    """GLPI followup rich object.
+
+    Parameters
+    ----------
+    content : str | None, optional
+        Followup body in canonical Markdown.
+    followup_id : str | None, optional
+        Native GLPI followup identifier.
+    created_at : datetime | None, optional
+        Creation timestamp.
+    updated_at : datetime | None, optional
+        Last update timestamp.
+    author : GlpiUser | None, optional
+        Followup author.
+    editor : GlpiUser | None, optional
+        Last editor.
+    is_private : bool, optional
+        Whether the followup is private.
+    attachment_document_ids : tuple[str, ...], optional
+        GLPI document identifiers referenced by the followup.
+    """
+
+    followup_id: str | None = None
+    content: str | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    author: GlpiUser | None = None
+    editor: GlpiUser | None = None
+    is_private: bool = False
+    attachment_document_ids: tuple[str, ...] = ()
+
+    def _build_api_payload(self) -> dict[str, object]:
+        """Return the raw GLPI API request body for the followup.
+
+        Returns
+        -------
+        dict[str, object]
+            Raw followup API request body.
+        """
+
+        payload: dict[str, object] = {
+            "content": GlpiContentConverter.to_transport(self.content),
+            "is_private": self.is_private,
+        }
+        author_id = getattr(self.author, "user_id", None)
+        if author_id is not None:
+            payload["user"] = {"id": author_id}
+        editor_id = getattr(self.editor, "user_id", None)
+        if editor_id is not None:
+            payload["user_editor"] = {"id": editor_id}
+        if self.created_at is not None:
+            timestamp = self.created_at.strftime("%Y-%m-%d %H:%M:%S")
+            payload["date_creation"] = timestamp
+            payload["date"] = timestamp
+        if self.updated_at is not None:
+            payload["date_mod"] = self.updated_at.strftime("%Y-%m-%d %H:%M:%S")
+        return drop_empty_payload_values(payload)

glpi_python_client/models/glpi/_location.py

@@ -0,0 +1,53 @@
+"""Typed GLPI location model.
+
+The location model is used both for parsed directory responses and for outgoing
+location-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 GlpiLocation(ApiPayloadMixin, GlpiModel):
+    """GLPI location rich object.
+
+    Parameters
+    ----------
+    location_id : str | None, optional
+        Native GLPI location identifier.
+    name : str | None, optional
+        Location display name.
+    entity_id : int | None, optional
+        Owning GLPI entity.
+    """
+
+    location_id: str | None = None
+    name: str | None = None
+    entity_id: int | None = None
+
+    def _build_api_payload(self) -> dict[str, object]:
+        """Return the raw GLPI location-create request body.
+
+        Returns
+        -------
+        dict[str, object]
+            Raw GLPI location-create request body.
+
+        """
+
+        location_id = self.location_id
+
+        return drop_empty_payload_values(
+            {
+                "id": location_id,
+                "name": self.name,
+                "entity": {"id": self.entity_id}
+                if self.entity_id is not None
+                else None,
+            }
+        )

glpi_python_client/models/glpi/_solution.py

@@ -0,0 +1,57 @@
+"""Typed GLPI solution model.
+
+The solution model stores normalized Markdown content together with the metadata
+returned by GLPI solution timeline endpoints.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+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.glpi._user import GlpiUser
+
+
+class GlpiSolution(ApiPayloadMixin, GlpiModel):
+    """GLPI solution rich object.
+
+    Parameters
+    ----------
+    content : str | None, optional
+        Solution body in canonical Markdown.
+    solution_id : str | None, optional
+        Native GLPI solution identifier.
+    created_at : datetime | None, optional
+        Creation timestamp.
+    updated_at : datetime | None, optional
+        Last update timestamp.
+    author : GlpiUser | None, optional
+        Solution author.
+    attachment_document_ids : tuple[str, ...], optional
+        GLPI document identifiers referenced by the solution.
+    """
+
+    solution_id: str | None = None
+    content: str | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    author: GlpiUser | None = None
+    attachment_document_ids: tuple[str, ...] = ()
+
+    def _build_api_payload(self) -> dict[str, object]:
+        """Return the raw GLPI API request body for the solution.
+
+        Returns
+        -------
+        dict[str, object]
+            Raw solution API request body.
+        """
+
+        return drop_empty_payload_values(
+            {"content": GlpiContentConverter.to_transport(self.content)}
+        )

glpi_python_client/models/glpi/_task.py

@@ -0,0 +1,41 @@
+"""Typed GLPI task model.
+
+The task model represents parsed task timeline entries returned by GLPI.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from glpi_python_client.models._base import GlpiModel
+from glpi_python_client.models.glpi._user import GlpiUser
+
+
+class GlpiTask(GlpiModel):
+    """GLPI task rich object.
+
+    Parameters
+    ----------
+    content : str | None, optional
+        Task body in canonical Markdown.
+    task_id : str | None, optional
+        Native GLPI task identifier.
+    created_at : datetime | None, optional
+        Creation timestamp.
+    updated_at : datetime | None, optional
+        Last update timestamp.
+    author : GlpiUser | None, optional
+        Task author.
+    editor : GlpiUser | None, optional
+        Last editor.
+    is_private : bool, optional
+        Whether the task is private.
+    """
+
+    task_id: str | None = None
+    content: str | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    author: GlpiUser | None = None
+    editor: GlpiUser | None = None
+    is_private: bool = False

glpi_python_client/models/glpi/_team_member.py

@@ -0,0 +1,33 @@
+"""Typed GLPI team-member model.
+
+The team-member model is used by the ticket team helpers for both parsed team
+associations and outgoing membership mutations.
+"""
+
+from __future__ import annotations
+
+from glpi_python_client.models._base import GlpiModel
+
+
+class GlpiTeamMember(GlpiModel):
+    """GLPI team-member rich object.
+
+    Parameters
+    ----------
+    member_type : str
+        GLPI member type such as ``"User"`` or ``"Group"``.
+    member_id : int
+        Native GLPI member identifier when known.
+    role : str
+        Team role carried by the member.
+    name : str | None, optional
+        Optional member name.
+    display_name : str | None, optional
+        Optional display name.
+    """
+
+    member_type: str
+    member_id: int
+    role: str
+    name: str | None = None
+    display_name: str | None = None