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

glpi_python_client/content/records/core/scalars.py

@@ -0,0 +1,83 @@
+"""Scalar coercion helpers for GLPI records.
+
+These helpers centralize the small normalization rules used repeatedly while
+parsing loosely typed GLPI payload values.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+
+def _parse_glpi_datetime(value: Any) -> datetime | None:
+    """Parse one GLPI datetime string.
+
+    The helper accepts ISO-like GLPI timestamps, normalizes common timezone
+    suffix variants, and returns ``None`` when parsing fails.
+    """
+
+    text = _optional_text(value)
+    if text is None:
+        return None
+    normalized = text.replace("Z", "+00:00")
+    if len(normalized) >= 5 and normalized[-5] in "+-" and normalized[-3] != ":":
+        normalized = f"{normalized[:-2]}:{normalized[-2:]}"
+    try:
+        return datetime.fromisoformat(normalized)
+    except ValueError:
+        return None
+
+
+def _optional_text(value: Any) -> str | None:
+    """Coerce a value to stripped text when it is meaningfully present.
+
+    Empty strings and ``None`` normalize to ``None`` so callers can treat blank
+    text fields as missing data.
+    """
+
+    text = str(value).strip() if value is not None else ""
+    return text or None
+
+
+def _optional_int(value: Any) -> int | None:
+    """Coerce a value to ``int`` when possible.
+
+    Invalid or missing integer-like values return ``None`` instead of raising,
+    which keeps record parsing tolerant of partial payloads.
+    """
+
+    try:
+        return int(value) if value is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _coerce_bool(value: Any) -> bool:
+    """Coerce common GLPI truthy values to ``bool``.
+
+    The helper accepts booleans, numeric sentinels, and the most common text
+    spellings emitted by GLPI payloads.
+    """
+
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return value != 0
+    if isinstance(value, str):
+        return value.strip().casefold() in {"1", "true", "yes"}
+    return False
+
+
+def _first_int(*values: Any) -> int | None:
+    """Return the first value that can be normalized to ``int``.
+
+    This is useful for payloads that may expose the same identifier under more
+    than one candidate key.
+    """
+
+    for value in values:
+        candidate = _optional_int(value)
+        if candidate is not None:
+            return candidate
+    return None

glpi_python_client/content/records/parsers/__init__.py

@@ -0,0 +1,6 @@
+"""Model-specific GLPI record parsers.
+
+Each parser module in this package focuses on converting one family of GLPI
+payloads into the package's typed models while reusing low-level helpers from
+``content.records.core``.
+"""

glpi_python_client/content/records/parsers/directory.py

@@ -0,0 +1,62 @@
+"""GLPI directory record parsing helpers for users and locations.
+
+This module converts raw user and location payloads from directory-style GLPI
+endpoints into the package's typed models.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from glpi_python_client.content.records.core.references import _glpi_id_value
+from glpi_python_client.content.records.core.scalars import (
+    _optional_int,
+    _optional_text,
+)
+from glpi_python_client.models import GlpiLocation, GlpiUser
+
+
+def _glpi_user_record(raw_user: dict[str, Any]) -> GlpiUser:
+    """Build a ``GlpiUser`` from one raw user payload.
+
+    The parser derives a display name from the available first name, real name,
+    and username fields while preserving the default entity when present.
+    """
+
+    user_id = _optional_text(raw_user.get("id"))
+    if user_id is None:
+        raise ValueError("GLPI user payload did not include an ID")
+    default_entity = raw_user.get("default_entity")
+    firstname = _optional_text(raw_user.get("firstname"))
+    realname = _optional_text(raw_user.get("realname")) or _optional_text(
+        raw_user.get("name")
+    )
+    return GlpiUser(
+        user_id=user_id,
+        email=_optional_text(raw_user.get("email"))
+        or _optional_text(raw_user.get("username")),
+        firstname=firstname,
+        realname=realname,
+        name=" ".join(part for part in (firstname, realname) if part)
+        or realname
+        or firstname,
+        entity_id=_optional_int(_glpi_id_value(default_entity) or default_entity),
+    )
+
+
+def _glpi_location_record(raw_location: dict[str, Any]) -> GlpiLocation:
+    """Build a ``GlpiLocation`` from one raw location payload.
+
+    The location parser requires both the identifier and name because those
+    fields are necessary for the high-level location model.
+    """
+
+    location_id = _optional_text(raw_location.get("id"))
+    name = _optional_text(raw_location.get("name"))
+    if location_id is None or name is None:
+        raise ValueError("GLPI location payload did not include id and name")
+    return GlpiLocation(
+        location_id=location_id,
+        name=name,
+        entity_id=_optional_int(_glpi_id_value(raw_location.get("entity"))),
+    )

glpi_python_client/content/records/parsers/documents.py

@@ -0,0 +1,49 @@
+"""GLPI document record parsing helpers.
+
+This module converts raw document payloads and optional metadata overlays into
+the package's typed ``GlpiDocument`` model.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from glpi_python_client.content.records.core.scalars import _optional_text
+from glpi_python_client.models import GlpiDocument
+
+
+def _glpi_document_record(
+    raw_document: dict[str, Any],
+    *,
+    metadata: dict[str, Any] | None = None,
+) -> GlpiDocument:
+    """Build a ``GlpiDocument`` from one raw document payload.
+
+    The parser can merge additional metadata gathered from a separate document
+    lookup before normalizing identifiers, filenames, and MIME types.
+    """
+
+    merged = dict(raw_document)
+    if metadata:
+        merged.update({f"metadata_{key}": value for key, value in metadata.items()})
+    document_id = (
+        _optional_text(merged.get("documents_id"))
+        or _optional_text(merged.get("metadata_id"))
+        or _optional_text(merged.get("id"))
+    )
+    filename = (
+        _optional_text(merged.get("filename"))
+        or _optional_text(merged.get("name"))
+        or _optional_text(merged.get("metadata_filename"))
+        or _optional_text(merged.get("metadata_name"))
+        or document_id
+    )
+    if document_id is None or filename is None:
+        raise ValueError("GLPI document payload did not include an ID and filename")
+    return GlpiDocument(
+        document_id=document_id,
+        filename=filename,
+        mime_type=_optional_text(merged.get("mime"))
+        or _optional_text(merged.get("metadata_mime")),
+        linked_document_id=_optional_text(merged.get("documents_id")),
+    )

glpi_python_client/content/records/parsers/team.py

@@ -0,0 +1,58 @@
+"""GLPI team-member record parsing helpers.
+
+This module turns raw team-association payloads into typed team-member models
+used by the ticket team helpers.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from glpi_python_client.content.records.core.scalars import _first_int, _optional_text
+from glpi_python_client.models import GlpiTeamMember
+
+
+def _glpi_team_member_record(raw_member: dict[str, Any]) -> GlpiTeamMember | None:
+    """Build a ``GlpiTeamMember`` from one raw association payload.
+
+    Incomplete associations are skipped by returning ``None`` so list parsing
+    can continue without failing the whole team-member batch.
+    """
+
+    member_type = _resolve_glpi_member_type(raw_member)
+    member_id = _first_int(
+        raw_member.get("id"), raw_member.get("items_id"), raw_member.get("users_id")
+    )
+    role = _optional_text(raw_member.get("role"))
+    if member_type is None or member_id is None or role is None:
+        return None
+    return GlpiTeamMember(
+        member_type=member_type,
+        member_id=member_id,
+        role=role,
+        name=_optional_text(raw_member.get("display_name"))
+        or _optional_text(raw_member.get("name")),
+        display_name=_optional_text(raw_member.get("display_name"))
+        or _optional_text(raw_member.get("name")),
+    )
+
+
+def _resolve_glpi_member_type(member: dict[str, Any]) -> str | None:
+    """Resolve the GLPI team-member type from explicit fields or links.
+
+    GLPI may provide the member type directly or only imply it through the
+    linked form URL, so both sources are considered.
+    """
+
+    member_type = member.get("itemtype") or member.get("type")
+    if isinstance(member_type, str) and member_type:
+        return member_type
+    href = member.get("href")
+    if not isinstance(href, str) or not href:
+        return None
+    lowered = href.casefold()
+    if "/group.form.php" in lowered:
+        return "Group"
+    if "/user.form.php" in lowered:
+        return "User"
+    return None

glpi_python_client/content/records/parsers/tests/__init__.py

@@ -0,0 +1,5 @@
+"""Parser tests colocated with record parser modules.
+
+This package keeps unit tests next to the content parser files they exercise so
+the test layout mirrors the implementation layout.
+"""

glpi_python_client/content/records/parsers/tests/test_tickets.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any
+
+from glpi_python_client.content.records.parsers.tickets import (
+    _filter_visible_ticket_batch,
+    _glpi_ticket_record,
+)
+
+
+def test_ticket_record_normalizes_nested_fields(
+    sample_ticket_record: dict[str, Any],
+) -> None:
+    ticket = _glpi_ticket_record(sample_ticket_record)
+
+    assert ticket.id == "123"
+    assert ticket.status == {"id": 2, "name": "Processing"}
+    assert ticket.entity == {"id": 7, "name": "Root"}
+    assert ticket.location == {"id": 8, "name": "Paris"}
+    assert ticket.content == "Body with **formatting**"
+    assert ticket.user_recipient is not None
+    assert ticket.user_recipient.user_id == "9"
+
+
+def test_filter_visible_ticket_batch_removes_deleted_records() -> None:
+    visible, deleted_count = _filter_visible_ticket_batch(
+        [
+            {"id": 1, "is_deleted": 0},
+            {"id": 2, "is_deleted": "true"},
+            {"id": 3, "is_deleted": False},
+        ]
+    )
+
+    assert [ticket["id"] for ticket in visible] == [1, 3]
+    assert deleted_count == 1

glpi_python_client/content/records/parsers/tests/test_timeline.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from glpi_python_client.content.records.parsers.timeline import _glpi_followup_record
+
+
+def test_followup_record_extracts_and_strips_document_references(
+    sample_followup_record: dict[str, Any],
+) -> None:
+    followup = _glpi_followup_record(sample_followup_record)
+
+    assert followup.followup_id == "12"
+    assert followup.author is not None
+    assert followup.author.user_id == "5"
+    assert followup.is_private is True
+    assert followup.attachment_document_ids == ("45", "46")
+    assert followup.content is not None
+    assert "document.send.php" not in followup.content
+    assert "Hello" in followup.content

glpi_python_client/content/records/parsers/tickets.py

@@ -0,0 +1,96 @@
+"""GLPI ticket record parsing helpers.
+
+This module converts raw ticket payloads and search batches into the package's
+typed ``GlpiTicket`` model while handling deleted-ticket filtering.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from glpi_python_client.content.conversion import GlpiContentConverter
+from glpi_python_client.content.records.core.references import (
+    _glpi_id_reference,
+    _glpi_reference,
+    _glpi_text_reference,
+    _glpi_ticket_user_payload,
+)
+from glpi_python_client.content.records.core.scalars import (
+    _optional_int,
+    _optional_text,
+    _parse_glpi_datetime,
+)
+from glpi_python_client.models import GlpiTicket
+
+
+def _is_deleted_ticket(record: dict[str, Any]) -> bool:
+    """Return whether one raw GLPI ticket payload represents a deleted ticket.
+
+    GLPI may encode this flag as a boolean, numeric sentinel, or text value, so
+    the helper accepts all of those shapes.
+    """
+
+    value = record.get("is_deleted")
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return value != 0
+    if isinstance(value, str):
+        return value.strip().casefold() in {"1", "true", "yes"}
+    return False
+
+
+def _filter_visible_ticket_batch(batch: object) -> tuple[list[dict[str, Any]], int]:
+    """Filter deleted tickets out of one GLPI search batch.
+
+    The function returns both the visible ticket payloads and the count removed
+    so callers can log how many deleted records were excluded.
+    """
+
+    if not isinstance(batch, list):
+        return [], 0
+    normalized_batch = [dict(ticket) for ticket in batch if isinstance(ticket, dict)]
+    visible_batch = [
+        ticket for ticket in normalized_batch if not _is_deleted_ticket(ticket)
+    ]
+    return visible_batch, len(normalized_batch) - len(visible_batch)
+
+
+def _glpi_ticket_record(raw_ticket: dict[str, Any]) -> GlpiTicket:
+    """Build a rich ``GlpiTicket`` object from one raw ticket payload.
+
+    The parser normalizes content, references, timestamps, and embedded user
+    fields while preserving the payload keys that map directly to the public
+    ticket model.
+    """
+
+    fields = dict(raw_ticket)
+    status = fields.pop("status", None)
+    ticket_id = _optional_text(fields.pop("id", None))
+    name = _optional_text(fields.pop("name", None))
+    content = str(fields.pop("content", "") or "")
+    if ticket_id is None:
+        raise ValueError("GLPI ticket payload did not include an ID")
+    external_id = _optional_text(fields.get("external_id"))
+    return GlpiTicket(
+        id=ticket_id,
+        name=name,
+        content=GlpiContentConverter.from_transport(content),
+        status=_glpi_id_reference(status),
+        urgency=_optional_int(fields.get("urgency")),
+        impact=_optional_int(fields.get("impact")),
+        priority=_optional_int(fields.get("priority")),
+        type=_optional_int(fields.get("type")),
+        external_id=external_id,
+        category=_glpi_id_reference(fields.get("category")),
+        entity=_glpi_id_reference(fields.get("entity")),
+        location=_glpi_reference(fields.get("location")),
+        request_type=_glpi_text_reference(fields.get("request_type")),
+        date_creation=_parse_glpi_datetime(fields.get("date_creation")),
+        date_mod=_parse_glpi_datetime(fields.get("date_mod"))
+        or datetime.now().astimezone(),
+        date_close=_parse_glpi_datetime(fields.get("date_close")),
+        user_recipient=_glpi_ticket_user_payload(fields.get("user_recipient")),
+        user_editor=_glpi_ticket_user_payload(fields.get("user_editor")),
+    )

glpi_python_client/content/records/parsers/timeline.py

@@ -0,0 +1,119 @@
+"""GLPI timeline record parsing helpers.
+
+This module converts followup, solution, and task timeline payloads into their
+typed rich-model equivalents.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from glpi_python_client.content.conversion import GlpiContentConverter
+from glpi_python_client.content.records.core.document_links import (
+    _glpi_followup_attachment_document_ids,
+    _strip_glpi_document_references,
+)
+from glpi_python_client.content.records.core.references import _glpi_id_value
+from glpi_python_client.content.records.core.scalars import (
+    _coerce_bool,
+    _optional_text,
+    _parse_glpi_datetime,
+)
+from glpi_python_client.models import GlpiFollowup, GlpiSolution, GlpiTask, GlpiUser
+
+
+def _glpi_followup_record(raw_followup: dict[str, Any]) -> GlpiFollowup:
+    """Build a ``GlpiFollowup`` from one raw timeline payload.
+
+    Followup parsing strips inline document references from the human-readable
+    content while extracting attachment document IDs separately.
+    """
+
+    followup_id = _optional_text(raw_followup.get("id"))
+    if followup_id is None:
+        raise ValueError("GLPI followup payload did not include an ID")
+    raw_content = str(raw_followup.get("content") or "")
+    author_id = _glpi_author_id(raw_followup)
+    return GlpiFollowup(
+        followup_id=followup_id,
+        content=GlpiContentConverter.from_transport(
+            _strip_glpi_document_references(raw_content)
+        ),
+        created_at=_parse_glpi_datetime(raw_followup.get("date_creation")),
+        updated_at=_parse_glpi_datetime(raw_followup.get("date_mod")),
+        author=GlpiUser(user_id=author_id) if author_id is not None else None,
+        is_private=_coerce_bool(raw_followup.get("is_private")),
+        attachment_document_ids=_glpi_followup_attachment_document_ids(raw_content),
+    )
+
+
+def _glpi_solution_record(raw_solution: dict[str, Any]) -> GlpiSolution:
+    """Build a ``GlpiSolution`` from one raw solution payload.
+
+    Solutions share most of the same parsing rules as followups, including
+    attachment extraction and Markdown normalization.
+    """
+
+    solution_id = _optional_text(raw_solution.get("id"))
+    if solution_id is None:
+        raise ValueError("GLPI solution payload did not include an ID")
+    raw_content = str(raw_solution.get("content") or "")
+    author_id = _glpi_author_id(raw_solution)
+    return GlpiSolution(
+        solution_id=solution_id,
+        content=GlpiContentConverter.from_transport(
+            _strip_glpi_document_references(raw_content)
+        ),
+        created_at=_parse_glpi_datetime(raw_solution.get("date_creation")),
+        updated_at=_parse_glpi_datetime(raw_solution.get("date_mod")),
+        author=GlpiUser(user_id=author_id) if author_id is not None else None,
+        attachment_document_ids=_glpi_followup_attachment_document_ids(raw_content),
+    )
+
+
+def _glpi_task_record(raw_task: dict[str, Any]) -> GlpiTask:
+    """Build a ``GlpiTask`` from one raw task payload.
+
+    Tasks can encode their dates under multiple keys, so the parser checks the
+    known GLPI variants before building the typed task object.
+    """
+
+    task_id = _optional_text(raw_task.get("id"))
+    if task_id is None:
+        raise ValueError("GLPI task payload did not include an ID")
+    author_id = _glpi_author_id(raw_task)
+    editor = raw_task.get("user_editor")
+    editor_id = _optional_text(_glpi_id_value(editor))
+    return GlpiTask(
+        task_id=task_id,
+        content=GlpiContentConverter.from_transport(raw_task.get("content")),
+        created_at=_parse_glpi_datetime(
+            raw_task.get("date_creation") or raw_task.get("date")
+        ),
+        updated_at=_parse_glpi_datetime(
+            raw_task.get("date_mod") or raw_task.get("date")
+        ),
+        author=GlpiUser(user_id=author_id) if author_id is not None else None,
+        editor=GlpiUser(user_id=editor_id) if editor_id is not None else None,
+        is_private=_coerce_bool(raw_task.get("is_private")),
+    )
+
+
+def _glpi_author_id(raw_item: dict[str, Any]) -> str | None:
+    """Extract the most specific GLPI author identifier from one payload.
+
+    The helper prefers nested user mappings before falling back to the older
+    scalar ``users_id`` field.
+    """
+
+    user_payload = raw_item.get("user")
+    if isinstance(user_payload, dict):
+        user_id = _optional_text(user_payload.get("id"))
+        if user_id is not None:
+            return user_id
+    editor_payload = raw_item.get("user_editor")
+    if isinstance(editor_payload, dict):
+        user_id = _optional_text(editor_payload.get("id"))
+        if user_id is not None:
+            return user_id
+    return _optional_text(raw_item.get("users_id"))

glpi_python_client/content/tests/__init__.py

@@ -0,0 +1,5 @@
+"""Content tests that live beside the implementation package.
+
+These tests stay colocated with the content modules so parser and conversion
+changes can be validated close to the code they exercise.
+"""

glpi_python_client/content/tests/test_conversion.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from glpi_python_client.content.conversion import GlpiContentConverter
+
+
+def test_content_converter_uses_markdown_in_python_and_html_for_glpi() -> None:
+    markdown = GlpiContentConverter.from_transport(
+        "<p>Hello <strong>world</strong></p>"
+    )
+    html = GlpiContentConverter.to_transport("Hello **world**")
+
+    assert markdown == "Hello **world**"
+    assert html == "<p>Hello <strong>world</strong></p>"

glpi_python_client/models/__init__.py

@@ -0,0 +1,30 @@
+"""Public model exports for the GLPI client package.
+
+The models package collects the supported typed objects used for request
+payloads and parsed GLPI responses, and re-exports them from one stable
+import surface.
+"""
+
+from __future__ import annotations
+
+from glpi_python_client.models.glpi import (
+    GlpiDocument,
+    GlpiFollowup,
+    GlpiLocation,
+    GlpiSolution,
+    GlpiTask,
+    GlpiTeamMember,
+    GlpiTicket,
+    GlpiUser,
+)
+
+__all__ = [
+    "GlpiDocument",
+    "GlpiFollowup",
+    "GlpiLocation",
+    "GlpiSolution",
+    "GlpiTask",
+    "GlpiTeamMember",
+    "GlpiTicket",
+    "GlpiUser",
+]

glpi_python_client/models/_base.py

@@ -0,0 +1,22 @@
+"""Base model contracts for GLPI data objects.
+
+This module defines the common Pydantic base class used by the package's typed
+GLPI models.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class GlpiModel(BaseModel):
+    """Base class for field-validated GLPI data models.
+
+    The shared base model forbids undeclared fields and exposes ``extra_payload``
+    so instance-specific API extensions can still be forwarded intentionally.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+    extra_payload: dict[str, Any] = Field(default_factory=dict)