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

glpi_python_client/clients/v2/sync/tickets.py

@@ -0,0 +1,312 @@
+"""Synchronous ticket operations for GLPI v2 clients.
+
+This module contains the ticket search, fetch, create, update, and delete
+helpers used by the synchronous high-level client.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterator
+from typing import Any, cast, overload
+
+from glpi_python_client.clients.v2.common.constants import TICKET_ENDPOINT, GlpiId
+from glpi_python_client.clients.v2.common.request_http import (
+    ensure_response_status,
+    require_non_empty_text,
+    require_response_text,
+)
+from glpi_python_client.clients.v2.common.ticket_search import (
+    advance_ticket_search_pagination,
+    build_ticket_search_params,
+    filter_ticket_search_batch,
+    is_deleted_ticket,
+    merge_list_ticket_fields,
+)
+from glpi_python_client.content.records.core.normalization import (
+    _normalize_ticket_record,
+)
+from glpi_python_client.content.records.parsers.tickets import (
+    _glpi_ticket_record,
+)
+from glpi_python_client.models import GlpiTicket
+
+from .transport import SyncTransportMixin
+
+logger = logging.getLogger(__name__)
+
+
+class SyncTicketMixin(SyncTransportMixin):
+    """Synchronous GLPI ticket search and mutation helpers.
+
+    The mixin exposes the typed ticket operations while delegating shared field
+    and pagination rules to the common helper modules.
+    """
+
+    @overload
+    def search_ticket_records(
+        self,
+        query: str | None = None,
+        *,
+        fields: tuple[str, ...] = (),
+        sort: str | None = None,
+        batch_size: None = None,
+        include_deleted_ticket: bool = False,
+    ) -> list[GlpiTicket]: ...
+
+    @overload
+    def search_ticket_records(
+        self,
+        query: str | None = None,
+        *,
+        fields: tuple[str, ...] = (),
+        sort: str | None = None,
+        batch_size: int,
+        include_deleted_ticket: bool = False,
+    ) -> Iterator[list[GlpiTicket]]: ...
+
+    def search_ticket_records(
+        self,
+        query: str | None = None,
+        *,
+        fields: tuple[str, ...] = (),
+        sort: str | None = None,
+        batch_size: int | None = None,
+        include_deleted_ticket: bool = False,
+    ) -> list[GlpiTicket] | Iterator[list[GlpiTicket]]:
+        """Search GLPI tickets and return either a full list or record batches.
+
+        Passing ``batch_size`` switches the method into streaming mode and
+        returns an iterator of typed ticket batches instead of materializing the
+        full result set.
+        """
+
+        if batch_size is not None and batch_size < 1:
+            raise ValueError("batch_size must be a positive integer or None")
+
+        merged_fields = merge_list_ticket_fields(list(fields) or None)
+        batches = self._iter_ticket_record_batches(
+            query=query,
+            fields=merged_fields,
+            sort=sort,
+            batch_size=batch_size,
+            include_deleted_ticket=include_deleted_ticket,
+        )
+        if batch_size is not None:
+            return batches
+
+        records: list[GlpiTicket] = []
+        for page in batches:
+            records.extend(page)
+        return records
+
+    def _iter_ticket_record_batches(
+        self,
+        *,
+        query: str | None = None,
+        fields: list[str] | None = None,
+        sort: str | None = None,
+        batch_size: int | None = None,
+        include_deleted_ticket: bool = False,
+    ) -> Iterator[list[GlpiTicket]]:
+        """Yield typed ticket batches produced from paginated raw payloads.
+
+        This helper sits between raw payload pagination and public return types,
+        ensuring each yielded batch already contains parsed ``GlpiTicket``
+        objects.
+        """
+
+        for page in self._yield_ticket_payloads(
+            query=query,
+            fields=fields,
+            sort=sort,
+            batch_size=batch_size,
+            include_deleted_ticket=include_deleted_ticket,
+        ):
+            yield [
+                _glpi_ticket_record(raw_ticket)
+                for raw_ticket in page
+                if isinstance(raw_ticket, dict)
+            ]
+
+    def get_ticket_record(
+        self,
+        ticket_id: GlpiId,
+        *,
+        include_deleted_ticket: bool = False,
+    ) -> GlpiTicket:
+        """Fetch one GLPI ticket by identifier.
+
+        Deleted tickets are rejected by default so single-record fetch behavior
+        stays aligned with the default search behavior.
+        """
+
+        response = self._get_request(f"{TICKET_ENDPOINT}/{ticket_id}")
+        if response.status_code not in (200, 206):
+            raise ValueError(
+                f"Failed to get ticket {ticket_id}: {response.status_code}"
+            )
+        payload = _normalize_ticket_record(response.json())
+        if not isinstance(payload, dict):
+            raise ValueError(f"Unexpected GLPI ticket payload for {ticket_id}")
+        if not include_deleted_ticket and is_deleted_ticket(payload):
+            raise ValueError(
+                f"Ticket {ticket_id} is deleted and excluded from fetch results"
+            )
+        return _glpi_ticket_record(payload)
+
+    def create_ticket(self, ticket: GlpiTicket) -> str:
+        """Create a GLPI ticket and return the identifier assigned by GLPI.
+
+        The ticket name precondition is enforced locally before the request is
+        sent, and the response must contain a created ticket ID.
+        """
+
+        require_non_empty_text(
+            ticket.name,
+            error_message="GLPI ticket creation requires a name",
+        )
+
+        payload_data = ticket.to_api_payload(
+            entity_id=self.glpi_entity,
+            include_entity=True,
+        )
+        response = self._post_request(TICKET_ENDPOINT, payload_data)
+        ensure_response_status(
+            response,
+            success_statuses=(200, 201),
+            failure_message="Failed to create ticket",
+        )
+        ticket_id = require_response_text(
+            response,
+            keys=("id",),
+            missing_message="GLPI create response did not include a ticket ID",
+        )
+        logger.info(
+            "GLPI API created ticket %s fields=%s",
+            ticket_id,
+            sorted(payload_data),
+        )
+        return ticket_id
+
+    def update_ticket(
+        self,
+        ticket_id: GlpiId,
+        ticket: GlpiTicket,
+        *,
+        field_mask: tuple[str, ...] = (),
+    ) -> None:
+        """Update one GLPI ticket with the provided field changes.
+
+        Optional field masks are forwarded to the model serializer so callers
+        can restrict the update payload to a specific subset of fields.
+        """
+
+        payload_data = ticket.to_api_payload(
+            entity_id=self.glpi_entity,
+            include_entity=False,
+            field_mask=field_mask,
+        )
+        response = self._update_request(
+            f"{TICKET_ENDPOINT}/{ticket_id}",
+            payload_data,
+        )
+        ensure_response_status(
+            response,
+            success_statuses=(200, 204),
+            failure_message=f"Failed to update ticket {ticket_id}",
+        )
+        logger.info(
+            "GLPI API updated ticket %s fields=%s",
+            ticket_id,
+            sorted(payload_data),
+        )
+        return None
+
+    def delete_ticket(self, ticket_id: GlpiId) -> None:
+        """Delete one GLPI ticket by identifier.
+
+        The method logs successful deletion and returns ``None`` to match the
+        package's mutation-helper conventions.
+        """
+
+        response = self._delete_request(f"{TICKET_ENDPOINT}/{ticket_id}")
+        ensure_response_status(
+            response,
+            success_statuses=(200, 204),
+            failure_message=f"Failed to delete ticket {ticket_id}",
+        )
+        logger.info("GLPI API deleted ticket %s", ticket_id)
+        return None
+
+    def _yield_ticket_payloads(
+        self,
+        *,
+        query: str | None = None,
+        fields: list[str] | None = None,
+        sort: str | None = None,
+        batch_size: int | None = None,
+        include_deleted_ticket: bool = False,
+    ) -> Iterator[list[dict[str, Any]]]:
+        """Yield paginated raw ticket payload batches from the GLPI API.
+
+        Pagination continues until the server indicates no more content or the
+        observed page-size heuristic shows that iteration is complete.
+        """
+
+        params = build_ticket_search_params(
+            query=query,
+            fields=fields,
+            sort=sort,
+            batch_size=batch_size,
+        )
+
+        observed_page_size = batch_size
+        while True:
+            current_start = cast(int, params["start"])
+            response = self._get_request(TICKET_ENDPOINT, params)
+            if response.status_code not in (200, 206):
+                logger.info(
+                    "GLPI ticket search returned status %s (start=%d)",
+                    response.status_code,
+                    current_start,
+                )
+                return
+
+            batch = response.json()
+            if not isinstance(batch, list) or not batch:
+                logger.info(
+                    "GLPI ticket search returned empty batch (start=%d)",
+                    current_start,
+                )
+                return
+
+            logger.info(
+                "GLPI ticket search: batch of %d tickets (start=%d)",
+                len(batch),
+                current_start,
+            )
+            result_batch, deleted_count = filter_ticket_search_batch(
+                batch,
+                include_deleted_ticket=include_deleted_ticket,
+            )
+            if deleted_count:
+                logger.info(
+                    "GLPI ticket search: excluded %d deleted tickets (start=%d)",
+                    deleted_count,
+                    current_start,
+                )
+            if result_batch:
+                yield result_batch
+
+            next_start, observed_page_size, should_continue = (
+                advance_ticket_search_pagination(
+                    current_start=current_start,
+                    page_size=len(batch),
+                    content_range=response.headers.get("Content-Range", ""),
+                    observed_page_size=observed_page_size,
+                )
+            )
+            params["start"] = next_start
+            if not should_continue:
+                return

glpi_python_client/clients/v2/sync/timeline.py

@@ -0,0 +1,308 @@
+"""Synchronous timeline operations for GLPI v2 clients.
+
+This module groups followup, task, solution, and attachment-lookup helpers for
+ticket timeline data.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from tenacity import RetryError
+
+from glpi_python_client.clients.v2.common.constants import (
+    FOLLOWUP_SUFFIX,
+    SOLUTION_SUFFIX,
+    TASK_SUFFIX,
+    TICKET_ENDPOINT,
+    GlpiId,
+)
+from glpi_python_client.clients.v2.common.errors import remote_error_message
+from glpi_python_client.clients.v2.common.request_http import (
+    ensure_response_status,
+    require_response_text,
+)
+from glpi_python_client.clients.v2.common.response_payloads import (
+    timeline_records_from_response,
+)
+from glpi_python_client.content.records.core.scalars import _optional_text
+from glpi_python_client.content.records.parsers.timeline import (
+    _glpi_followup_record,
+    _glpi_solution_record,
+    _glpi_task_record,
+)
+from glpi_python_client.models import GlpiFollowup, GlpiSolution, GlpiTask
+
+from .transport import SyncTransportMixin
+
+logger = logging.getLogger(__name__)
+
+
+class SyncTimelineMixin(SyncTransportMixin):
+    """Synchronous followup, task, and solution helpers.
+
+    The mixin keeps ticket timeline behavior together because these endpoints
+    share parsing, logging, and optional legacy attachment lookup rules.
+    """
+
+    def get_followup_records(self, ticket_id: GlpiId) -> list[GlpiFollowup]:
+        """Fetch the followups associated with one ticket.
+
+        Non-success responses are logged and normalized to an empty list so the
+        helper behaves like the other timeline list operations.
+        """
+
+        endpoint = f"{TICKET_ENDPOINT}/{ticket_id}/{FOLLOWUP_SUFFIX}"
+        response = self._get_request(endpoint)
+        if response.status_code not in (200, 206):
+            logger.warning(
+                "Failed to get followups for ticket %s: %s",
+                ticket_id,
+                response.status_code,
+            )
+            return []
+        return timeline_records_from_response(
+            response,
+            record_factory=_glpi_followup_record,
+        )
+
+    def get_task_records(self, ticket_id: GlpiId) -> list[GlpiTask]:
+        """Fetch the tasks associated with one ticket.
+
+        Returned records are parsed into typed ``GlpiTask`` instances using the
+        shared timeline response handling helpers.
+        """
+
+        endpoint = f"{TICKET_ENDPOINT}/{ticket_id}/{TASK_SUFFIX}"
+        response = self._get_request(endpoint)
+        if response.status_code not in (200, 206):
+            logger.warning(
+                "Failed to get tasks for ticket %s: %s",
+                ticket_id,
+                response.status_code,
+            )
+            return []
+        return timeline_records_from_response(
+            response,
+            record_factory=_glpi_task_record,
+        )
+
+    def get_followup_attachment_document_ids(
+        self, followup_id: GlpiId
+    ) -> tuple[str, ...]:
+        """Fetch document IDs linked directly to one followup through v1.
+
+        Attachment lookup is best-effort because it depends on the optional
+        legacy v1 session; failures are logged and normalized to an empty tuple.
+        """
+
+        v1_session = self._v1
+        if v1_session is None:
+            return ()
+
+        document_ids: list[str] = []
+        seen_document_ids: set[str] = set()
+        try:
+            relations = v1_session.get_sub_items(
+                "ITILFollowup",
+                followup_id,
+                "Document_Item",
+            )
+        except (RetryError, ValueError) as exc:
+            logger.warning(
+                "Skipping GLPI followup %s attachment lookup after v1 API failure: %s",
+                followup_id,
+                remote_error_message(exc),
+            )
+            return ()
+        for relation in relations:
+            document_id = _optional_text(relation.get("documents_id"))
+            if document_id is None or document_id in seen_document_ids:
+                continue
+            seen_document_ids.add(document_id)
+            document_ids.append(document_id)
+        return tuple(document_ids)
+
+    def get_solution_attachment_document_ids(
+        self, solution_id: GlpiId
+    ) -> tuple[str, ...]:
+        """Fetch document IDs linked directly to one solution through v1.
+
+        This mirrors followup attachment lookup and preserves first-seen order
+        while removing duplicate document identifiers.
+        """
+
+        v1_session = self._v1
+        if v1_session is None:
+            return ()
+
+        document_ids: list[str] = []
+        seen_document_ids: set[str] = set()
+        try:
+            relations = v1_session.get_sub_items(
+                "ITILSolution",
+                solution_id,
+                "Document_Item",
+            )
+        except (RetryError, ValueError) as exc:
+            logger.warning(
+                "Skipping GLPI solution %s attachment lookup after v1 API failure: %s",
+                solution_id,
+                remote_error_message(exc),
+            )
+            return ()
+        for relation in relations:
+            document_id = _optional_text(relation.get("documents_id"))
+            if document_id is None or document_id in seen_document_ids:
+                continue
+            seen_document_ids.add(document_id)
+            document_ids.append(document_id)
+        return tuple(document_ids)
+
+    def get_solution_records(self, ticket_id: GlpiId) -> list[GlpiSolution]:
+        """Fetch the solutions associated with one ticket.
+
+        Each returned item is parsed into a typed ``GlpiSolution`` record using
+        the shared timeline parsing helpers.
+        """
+
+        endpoint = f"{TICKET_ENDPOINT}/{ticket_id}/{SOLUTION_SUFFIX}"
+        response = self._get_request(endpoint)
+        if response.status_code not in (200, 206):
+            logger.warning(
+                "Failed to get solutions for ticket %s: %s",
+                ticket_id,
+                response.status_code,
+            )
+            return []
+        return timeline_records_from_response(
+            response,
+            record_factory=_glpi_solution_record,
+        )
+
+    def create_followup(
+        self,
+        ticket_id: GlpiId,
+        followup: GlpiFollowup,
+    ) -> str:
+        """Create a GLPI followup and return the identifier assigned by GLPI.
+
+        The response may expose the created ID under different keys, so the
+        helper normalizes that lookup before returning to callers.
+        """
+
+        endpoint = f"{TICKET_ENDPOINT}/{ticket_id}/{FOLLOWUP_SUFFIX}"
+        payload_data = followup.to_api_payload()
+        response = self._post_request(endpoint, payload_data)
+        ensure_response_status(
+            response,
+            success_statuses=(200, 201),
+            failure_message=f"Failed to post followup on ticket {ticket_id}",
+        )
+        followup_id = require_response_text(
+            response,
+            keys=("id", "followup_id"),
+            missing_message="GLPI followup create response did not include an ID",
+        )
+        logger.info(
+            "GLPI API created %s followup %s on ticket %s",
+            "private" if payload_data.get("is_private") else "public",
+            followup_id,
+            ticket_id,
+        )
+        return followup_id
+
+    def update_followup(
+        self,
+        ticket_id: GlpiId,
+        followup_id: GlpiId,
+        followup: GlpiFollowup,
+    ) -> None:
+        """Update one GLPI followup on a ticket.
+
+        The followup model is serialized as-is and the method returns ``None``
+        once GLPI accepts the update.
+        """
+
+        endpoint = f"{TICKET_ENDPOINT}/{ticket_id}/{FOLLOWUP_SUFFIX}/{followup_id}"
+        payload_data = followup.to_api_payload()
+        response = self._update_request(endpoint, payload_data)
+        ensure_response_status(
+            response,
+            success_statuses=(200, 204),
+            failure_message=(
+                f"Failed to patch followup {followup_id} on ticket {ticket_id}"
+            ),
+        )
+        logger.info(
+            "GLPI API updated followup %s on ticket %s fields=%s",
+            followup_id,
+            ticket_id,
+            sorted(payload_data),
+        )
+        return None
+
+    def delete_followup(self, ticket_id: GlpiId, followup_id: GlpiId) -> None:
+        """Delete one GLPI ticket followup by identifier.
+
+        Successful deletes are logged with both ticket and followup context to
+        help trace timeline mutations.
+        """
+
+        endpoint = f"{TICKET_ENDPOINT}/{ticket_id}/{FOLLOWUP_SUFFIX}/{followup_id}"
+        response = self._delete_request(endpoint)
+        ensure_response_status(
+            response,
+            success_statuses=(200, 204),
+            failure_message=(
+                f"Failed to delete followup {followup_id} on ticket {ticket_id}"
+            ),
+        )
+        logger.info("GLPI API deleted followup %s on ticket %s", followup_id, ticket_id)
+        return None
+
+    def create_solution(
+        self,
+        ticket_id: GlpiId,
+        solution: GlpiSolution,
+    ) -> str:
+        """Create a GLPI solution and return the identifier assigned by GLPI.
+
+        As with followups, the created solution identifier is normalized from
+        the response payload before being returned.
+        """
+
+        endpoint = f"{TICKET_ENDPOINT}/{ticket_id}/{SOLUTION_SUFFIX}"
+        payload_data = solution.to_api_payload()
+        response = self._post_request(endpoint, payload_data)
+        ensure_response_status(
+            response,
+            success_statuses=(200, 201),
+            failure_message=f"Failed to post solution on ticket {ticket_id}",
+        )
+        solution_id = require_response_text(
+            response,
+            keys=("id", "solution_id"),
+            missing_message="GLPI solution create response did not include an ID",
+        )
+        logger.info("GLPI API created solution %s on ticket %s", solution_id, ticket_id)
+        return solution_id
+
+    def delete_solution(self, ticket_id: GlpiId, solution_id: GlpiId) -> None:
+        """Delete one GLPI ticket solution by identifier.
+
+        The helper returns ``None`` after a successful delete response and logs
+        the mutation for troubleshooting and auditability.
+        """
+
+        endpoint = f"{TICKET_ENDPOINT}/{ticket_id}/{SOLUTION_SUFFIX}/{solution_id}"
+        response = self._delete_request(endpoint)
+        ensure_response_status(
+            response,
+            success_statuses=(200, 204),
+            failure_message=(
+                f"Failed to delete solution {solution_id} on ticket {ticket_id}"
+            ),
+        )
+        logger.info("GLPI API deleted solution %s on ticket %s", solution_id, ticket_id)
+        return None