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

glpi_python_client/clients/v2/async_/timeline.py

@@ -0,0 +1,312 @@
+"""Asynchronous timeline operations for GLPI v2 clients.
+
+This module groups async followup, task, solution, and attachment-lookup
+helpers for ticket timeline data.
+"""
+
+from __future__ import annotations
+
+import asyncio
+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 AsyncTransportMixin
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncTimelineMixin(AsyncTransportMixin):
+    """Asynchronous followup, task, and solution helpers.
+
+    The mixin keeps ticket timeline behavior together because these endpoints
+    share parsing, logging, and optional legacy attachment lookup rules.
+    """
+
+    async 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 async timeline list operations.
+        """
+
+        endpoint = f"{TICKET_ENDPOINT}/{ticket_id}/{FOLLOWUP_SUFFIX}"
+        response = await 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,
+        )
+
+    async 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 = await 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,
+        )
+
+    async 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 and runs through ``asyncio.to_thread`` at that narrow
+        blocking boundary.
+        """
+
+        v1_session = self._v1
+        if v1_session is None:
+            return ()
+
+        document_ids: list[str] = []
+        seen_document_ids: set[str] = set()
+        try:
+            relations = await asyncio.to_thread(
+                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)
+
+    async 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 = await asyncio.to_thread(
+                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)
+
+    async 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 = await 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,
+        )
+
+    async 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 = await 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
+
+    async 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 = await 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
+
+    async 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 = await 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
+
+    async 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 = await 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
+
+    async 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 = await 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

glpi_python_client/clients/v2/async_/transport.py

@@ -0,0 +1,251 @@
+"""Asynchronous GLPI v2 transport methods.
+
+This module owns the awaitable transport helpers that wrap the shared
+``requests`` session and keep blocking calls behind narrow thread boundaries.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING, cast
+
+import requests
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_fixed
+
+from glpi_python_client.clients.v2.common.request_http import (
+    build_request_headers,
+    build_request_url,
+    finalize_request_response,
+    request_params,
+    require_access_token,
+)
+
+if TYPE_CHECKING:
+    from glpi_python_client.auth.auth import GLPITokenManager
+    from glpi_python_client.clients.api_v1_session import GLPIV1Session
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncTransportMixin:
+    """Asynchronous GLPI API transport helpers.
+
+    The transport mixin keeps token handling, header construction, retries, and
+    request dispatch out of the endpoint-specific async mixins.
+    """
+
+    _auth: GLPITokenManager
+    _auth_lock: asyncio.Lock
+    _closed: bool = False
+    _session: requests.Session
+    _v1: GLPIV1Session | None
+    entity_recursive: bool
+    glpi_api_url: str
+    glpi_entity: int | None
+    glpi_profile: int | None
+    language: str
+
+    def _ensure_open(self) -> None:
+        """Raise when the client has already been closed.
+
+        All async transport helpers call this guard before touching the shared
+        HTTP session.
+        """
+
+        if self._closed:
+            raise RuntimeError("GLPI client is closed")
+
+    async def _ensure_token(self) -> None:
+        """Ensure that a valid GLPI access token is available.
+
+        Token refresh is serialized by the async lock so concurrent awaited
+        calls do not race while updating shared authentication state.
+        """
+
+        self._ensure_open()
+        async with self._auth_lock:
+            await asyncio.to_thread(self._auth.ensure_token)
+
+    def _get_headers(
+        self,
+        *,
+        include_content_type: bool = False,
+        skip_entity: bool = False,
+    ) -> dict[str, str]:
+        """Build GLPI request headers for the current client state.
+
+        This convenience wrapper forwards the current transport state to the
+        shared header builder used across sync and async implementations.
+        """
+
+        return build_request_headers(
+            access_token=self._auth.access_token,
+            language=self.language,
+            glpi_entity=self.glpi_entity,
+            glpi_profile=self.glpi_profile,
+            entity_recursive=self.entity_recursive,
+            include_content_type=include_content_type,
+            skip_entity=skip_entity,
+        )
+
+    async def _send_request(
+        self,
+        method: str,
+        url: str,
+        **kwargs: object,
+    ) -> requests.Response:
+        request_method = getattr(self._session, method)
+        return cast(
+            requests.Response,
+            await asyncio.to_thread(request_method, url, **kwargs),
+        )
+
+    async def _execute_request(
+        self,
+        *,
+        method: str,
+        endpoint: str,
+        success_statuses: tuple[int, ...],
+        params: dict[str, object] | None = None,
+        json_body: dict[str, object] | None = None,
+        skip_entity: bool = False,
+        include_content_type: bool = False,
+    ) -> requests.Response:
+        """Execute one authenticated GLPI request asynchronously.
+
+        The helper normalizes the endpoint URL, headers, timeout, and payload
+        placement before dispatching the blocking HTTP call through the async
+        transport wrapper.
+        """
+
+        await self._ensure_token()
+        access_token = require_access_token(self._auth.access_token)
+        url = build_request_url(self.glpi_api_url, endpoint)
+
+        request_kwargs: dict[str, object] = {
+            "headers": build_request_headers(
+                access_token=access_token,
+                language=self.language,
+                glpi_entity=self.glpi_entity,
+                glpi_profile=self.glpi_profile,
+                entity_recursive=self.entity_recursive,
+                include_content_type=include_content_type,
+                skip_entity=skip_entity,
+            ),
+            "timeout": 30,
+        }
+        if method == "get":
+            request_kwargs["params"] = request_params(params)
+        else:
+            request_kwargs["json"] = json_body
+
+        response = await self._send_request(method, url, **request_kwargs)
+        return finalize_request_response(
+            response,
+            method=method,
+            url=url,
+            success_statuses=success_statuses,
+            logger=logger,
+        )
+
+    @retry(
+        retry=retry_if_exception_type(requests.RequestException),
+        stop=stop_after_attempt(3),
+        wait=wait_fixed(3),
+    )
+    async def _get_request(
+        self,
+        endpoint: str,
+        params: dict[str, object] | None = None,
+        skip_entity: bool = False,
+    ) -> requests.Response:
+        """Execute one authenticated GLPI ``GET`` request asynchronously.
+
+        Network-level request exceptions are retried according to the transport
+        retry policy before the response is returned to the caller.
+        """
+
+        return await self._execute_request(
+            method="get",
+            endpoint=endpoint,
+            success_statuses=(200, 206),
+            params=params,
+            skip_entity=skip_entity,
+        )
+
+    @retry(
+        retry=retry_if_exception_type(requests.RequestException),
+        stop=stop_after_attempt(3),
+        wait=wait_fixed(3),
+    )
+    async def _post_request(
+        self,
+        endpoint: str,
+        json_body: dict[str, object] | None = None,
+        skip_entity: bool = False,
+    ) -> requests.Response:
+        """Execute one authenticated GLPI ``POST`` request asynchronously.
+
+        JSON request bodies automatically include the content-type header needed
+        by the GLPI API.
+        """
+
+        return await self._execute_request(
+            method="post",
+            endpoint=endpoint,
+            success_statuses=(200, 201),
+            json_body=json_body,
+            skip_entity=skip_entity,
+            include_content_type=True,
+        )
+
+    @retry(
+        retry=retry_if_exception_type(requests.RequestException),
+        stop=stop_after_attempt(3),
+        wait=wait_fixed(3),
+    )
+    async def _update_request(
+        self,
+        endpoint: str,
+        json_body: dict[str, object] | None = None,
+    ) -> requests.Response:
+        """Execute one authenticated GLPI ``PATCH`` request asynchronously.
+
+        The helper uses the same authenticated execution path as the other HTTP
+        verbs while targeting the success codes expected from update calls.
+        """
+
+        return await self._execute_request(
+            method="patch",
+            endpoint=endpoint,
+            success_statuses=(200, 204),
+            json_body=json_body,
+            include_content_type=True,
+        )
+
+    @retry(
+        retry=retry_if_exception_type(requests.RequestException),
+        stop=stop_after_attempt(3),
+        wait=wait_fixed(3),
+    )
+    async def _delete_request(
+        self,
+        endpoint: str,
+        json_body: dict[str, object] | None = None,
+        skip_entity: bool = False,
+    ) -> requests.Response:
+        """Execute one authenticated GLPI ``DELETE`` request asynchronously.
+
+        Some delete endpoints accept a JSON body, so the content-type header is
+        enabled automatically when a body is supplied.
+        """
+
+        return await self._execute_request(
+            method="delete",
+            endpoint=endpoint,
+            success_statuses=(200, 204),
+            json_body=json_body,
+            skip_entity=skip_entity,
+            include_content_type=json_body is not None,
+        )

glpi_python_client/clients/v2/common/__init__.py

@@ -0,0 +1,6 @@
+"""Shared helper modules for the GLPI v2 clients.
+
+This package holds deterministic logic such as endpoint constants, request
+normalization, payload building, and response extraction that is reused by
+both the synchronous and asynchronous client implementations.
+"""