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

glpi_python_client/clients/v2/common/ticket_search.py

@@ -0,0 +1,113 @@
+"""Ticket search field and pagination helpers for GLPI v2 clients.
+
+These helpers keep field merging, deleted-ticket filtering, and pagination math
+in one place so sync and async search implementations behave the same way.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from glpi_python_client.content.records.parsers.tickets import (
+    _filter_visible_ticket_batch,
+)
+
+from .constants import LIST_TICKET_CORE_FIELDS
+
+
+def merge_list_ticket_fields(fields: list[str] | None) -> list[str] | None:
+    """Merge caller-requested list fields with required core ticket fields.
+
+    The helper preserves caller order while ensuring the fields needed for the
+    package's ticket parsing logic are always present.
+    """
+
+    if fields is None:
+        return list(LIST_TICKET_CORE_FIELDS)
+    return list(dict.fromkeys([*fields, *LIST_TICKET_CORE_FIELDS]))
+
+
+def is_deleted_ticket(record: dict[str, Any]) -> bool:
+    """Return whether one raw GLPI ticket payload represents a deleted ticket.
+
+    This delegates to the shared batch filter so the single-record check uses
+    the exact same deleted-ticket rules as paginated search results.
+    """
+
+    return _filter_visible_ticket_batch([record])[1] == 1
+
+
+def build_ticket_search_params(
+    *,
+    query: str | None = None,
+    fields: list[str] | None = None,
+    sort: str | None = None,
+    batch_size: int | None = None,
+) -> dict[str, object]:
+    """Build the request parameter mapping for a ticket search call.
+
+    Search pagination always starts at zero here, and optional query, field,
+    sort, and limit arguments are included only when the caller supplies them.
+    """
+
+    params: dict[str, object] = {"start": 0}
+    if batch_size is not None:
+        params["limit"] = batch_size
+    if query:
+        params["filter"] = query
+    if fields:
+        params["fields"] = ",".join(fields)
+    if sort:
+        params["sort"] = sort
+    return params
+
+
+def filter_ticket_search_batch(
+    batch: list[object],
+    *,
+    include_deleted_ticket: bool,
+) -> tuple[list[dict[str, Any]], int]:
+    """Return visible ticket payloads and the number excluded as deleted.
+
+    When deleted tickets are allowed, the helper simply normalizes dictionary
+    items. Otherwise it defers to the shared deleted-ticket filter.
+    """
+
+    if include_deleted_ticket:
+        return [dict(ticket) for ticket in batch if isinstance(ticket, dict)], 0
+    return _filter_visible_ticket_batch(batch)
+
+
+def advance_ticket_search_pagination(
+    *,
+    current_start: int,
+    page_size: int,
+    content_range: str,
+    observed_page_size: int | None,
+) -> tuple[int, int | None, bool]:
+    """Return the next ticket page start and whether another page is needed.
+
+    The function prefers the server-provided ``Content-Range`` total when it is
+    available and otherwise falls back to observed page sizes to decide whether
+    iteration should continue.
+    """
+
+    total_count: int | None = None
+    if content_range:
+        try:
+            total_count = int(content_range.split("/")[-1])
+        except (ValueError, IndexError):
+            total_count = None
+
+    next_start = current_start + page_size
+    if total_count is not None:
+        return next_start, observed_page_size, next_start < total_count
+
+    next_observed_page_size = observed_page_size
+    if next_observed_page_size is None:
+        next_observed_page_size = page_size
+    return (
+        next_start,
+        next_observed_page_size,
+        page_size >= next_observed_page_size,
+    )

glpi_python_client/clients/v2/sync/__init__.py

@@ -0,0 +1,12 @@
+"""Synchronous GLPI v2 implementation exports.
+
+The synchronous client is assembled from mixins grouped by endpoint area.
+This package exposes the combined synchronous API mixin used by
+``GlpiClient``.
+"""
+
+from __future__ import annotations
+
+from glpi_python_client.clients.v2.sync.api import GlpiApiClientMixin
+
+__all__ = ["GlpiApiClientMixin"]

glpi_python_client/clients/v2/sync/api.py

@@ -0,0 +1,29 @@
+"""Synchronous GLPI v2 API mixin assembly.
+
+This module combines the scope-focused synchronous mixins into the single API
+surface consumed by the public ``GlpiClient`` class.
+"""
+
+from __future__ import annotations
+
+from .directory import SyncDirectoryMixin
+from .documents import SyncDocumentMixin
+from .team import SyncTeamMixin
+from .tickets import SyncTicketMixin
+from .timeline import SyncTimelineMixin
+from .transport import SyncTransportMixin
+
+
+class GlpiApiClientMixin(
+    SyncTicketMixin,
+    SyncTimelineMixin,
+    SyncDocumentMixin,
+    SyncTeamMixin,
+    SyncDirectoryMixin,
+    SyncTransportMixin,
+):
+    """Combined synchronous GLPI v2 client behavior.
+
+    The mixin class has no state of its own. It exists to provide a readable
+    composition point for the synchronous endpoint and transport helpers.
+    """

glpi_python_client/clients/v2/sync/directory.py

@@ -0,0 +1,90 @@
+"""Synchronous user and location lookup operations for GLPI v2 clients.
+
+This module contains the directory-style search helpers used to query users and
+locations through the GLPI high-level API.
+"""
+
+from __future__ import annotations
+
+from glpi_python_client.clients.v2.common.constants import (
+    LOCATION_ENDPOINT,
+    USER_ENDPOINT,
+)
+from glpi_python_client.clients.v2.common.filters import rsql_contains_filter
+from glpi_python_client.clients.v2.common.response_payloads import list_payload_records
+from glpi_python_client.content.records.core.scalars import _optional_text
+from glpi_python_client.content.records.parsers.directory import (
+    _glpi_location_record,
+    _glpi_user_record,
+)
+from glpi_python_client.models import GlpiLocation, GlpiUser
+
+from .transport import SyncTransportMixin
+
+
+class SyncDirectoryMixin(SyncTransportMixin):
+    """Synchronous GLPI user and location lookup helpers.
+
+    The methods in this mixin return typed directory models and hide the
+    filtering and payload-normalization details required by the GLPI API.
+    """
+
+    def search_users(
+        self,
+        rsql_filter: str = "",
+        *,
+        limit: int = 1,
+        start: int = 0,
+        skip_entity: bool = False,
+    ) -> list[GlpiUser]:
+        """Search GLPI users with an optional raw RSQL filter.
+
+        The method returns only records that include a usable GLPI user ID and
+        silently yields an empty list when the remote endpoint does not return a
+        success status.
+        """
+
+        params: dict[str, object] = {"limit": limit, "start": start}
+        if rsql_filter:
+            params["filter"] = rsql_filter
+        response = self._get_request(
+            USER_ENDPOINT, params=params, skip_entity=skip_entity
+        )
+        if response.status_code not in (200, 206):
+            return []
+        return list_payload_records(
+            response.json(),
+            record_factory=lambda user: (
+                _glpi_user_record(user)
+                if _optional_text(user.get("id")) is not None
+                else None
+            ),
+        )
+
+    def search_locations(self, name: str) -> list[GlpiLocation]:
+        """Search GLPI locations by name.
+
+        Blank names are filtered out locally, and non-success API responses are
+        normalized to an empty result list so callers can treat this as a lookup
+        helper rather than a strict mutation-style operation.
+        """
+
+        location_filter = rsql_contains_filter("name", name)
+        if location_filter is None:
+            return []
+
+        response = self._get_request(
+            LOCATION_ENDPOINT,
+            params={"filter": location_filter},
+        )
+        if response.status_code not in (200, 206):
+            return []
+        return list_payload_records(
+            response.json(),
+            record_factory=lambda location: (
+                _glpi_location_record(location)
+                if _optional_text(location.get("id")) is not None
+                and _optional_text(location.get("name")) is not None
+                else None
+            ),
+        )

glpi_python_client/clients/v2/sync/documents.py

@@ -0,0 +1,144 @@
+"""Synchronous document operations for GLPI v2 clients.
+
+This module covers document listing, metadata lookup, binary download, and
+deletion for ticket-linked GLPI documents.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import requests
+from tenacity import RetryError
+
+from glpi_python_client.clients.v2.common.constants import (
+    DOCUMENT_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
+from glpi_python_client.clients.v2.common.response_payloads import (
+    timeline_payload_items,
+)
+from glpi_python_client.content.records.core.scalars import _optional_text
+from glpi_python_client.content.records.parsers.documents import _glpi_document_record
+from glpi_python_client.models import GlpiDocument
+
+from .transport import SyncTransportMixin
+
+logger = logging.getLogger(__name__)
+
+
+class SyncDocumentMixin(SyncTransportMixin):
+    """Synchronous GLPI ticket document helpers.
+
+    These helpers translate document-related GLPI payloads into typed document
+    models and keep metadata enrichment behavior consistent across calls.
+    """
+
+    def get_document_records(
+        self,
+        ticket_id: GlpiId,
+        *,
+        enrich_metadata: bool = True,
+    ) -> list[GlpiDocument]:
+        """Fetch the documents linked to one ticket.
+
+        When metadata enrichment is enabled, the method performs per-document
+        lookups and logs skipped enrichments without failing the whole batch.
+        """
+
+        endpoint = f"{TICKET_ENDPOINT}/{ticket_id}/{DOCUMENT_SUFFIX}"
+        response = self._get_request(endpoint)
+        if response.status_code not in (200, 206):
+            logger.warning(
+                "Failed to get documents for ticket %s: %s",
+                ticket_id,
+                response.status_code,
+            )
+            return []
+
+        records: list[GlpiDocument] = []
+        for relation in timeline_payload_items(response.json()):
+            document_id = _optional_text(
+                relation.get("documents_id")
+            ) or _optional_text(relation.get("id"))
+            if document_id is None:
+                continue
+            metadata: dict[str, Any] = {}
+            if enrich_metadata:
+                try:
+                    document_record = self.get_document_record(document_id)
+                    metadata = {
+                        "id": document_record.document_id,
+                        "filename": document_record.filename,
+                        "mime": document_record.mime_type,
+                    }
+                except (RetryError, ValueError, requests.RequestException) as exc:
+                    logger.warning(
+                        "Skipping GLPI document %s metadata lookup: %s",
+                        document_id,
+                        remote_error_message(exc),
+                    )
+            records.append(_glpi_document_record(relation, metadata=metadata))
+        return records
+
+    def get_document_record(self, document_id: GlpiId) -> GlpiDocument:
+        """Fetch one GLPI document record by identifier.
+
+        The payload must be a mapping and is converted into a typed
+        ``GlpiDocument`` instance before being returned.
+        """
+
+        response = self._get_request(
+            f"Management/Document/{document_id}",
+            skip_entity=True,
+        )
+        if response.status_code not in (200, 206):
+            raise ValueError(
+                f"Failed to get document {document_id}: "
+                f"{response.status_code} {response.text[:200]}"
+            )
+        payload = response.json()
+        if not isinstance(payload, dict):
+            raise ValueError(f"Unexpected GLPI document payload for {document_id}")
+        return _glpi_document_record(payload)
+
+    def download_document_content(self, document_id: GlpiId) -> bytes:
+        """Download the raw binary payload for one GLPI document.
+
+        This method is intended for file-content retrieval and returns the raw
+        response bytes without additional decoding.
+        """
+
+        response = self._get_request(
+            f"Management/Document/{document_id}/Download",
+            skip_entity=True,
+        )
+        if response.status_code != 200:
+            raise ValueError(
+                f"Failed to download document {document_id}: "
+                f"{response.status_code} {response.text[:200]}"
+            )
+        return response.content
+
+    def delete_document(self, document_id: GlpiId) -> None:
+        """Delete one GLPI document by identifier.
+
+        Successful deletes return ``None`` and are logged so document cleanup
+        workflows can be traced in client logs.
+        """
+
+        response = self._delete_request(
+            f"Management/Document/{document_id}",
+            skip_entity=True,
+        )
+        ensure_response_status(
+            response,
+            success_statuses=(200, 204),
+            failure_message=f"Failed to delete document {document_id}",
+        )
+        logger.info("GLPI API deleted document %s", document_id)
+        return None

glpi_python_client/clients/v2/sync/team.py

@@ -0,0 +1,125 @@
+"""Synchronous team member operations for GLPI v2 clients.
+
+This module provides the ticket team-member helpers that list, add, and remove
+assigned members through the GLPI API.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from glpi_python_client.clients.v2.common.constants import (
+    TEAM_MEMBER_SUFFIX,
+    TICKET_ENDPOINT,
+    GlpiId,
+)
+from glpi_python_client.clients.v2.common.payloads import build_team_member_payload
+from glpi_python_client.clients.v2.common.request_http import ensure_response_status
+from glpi_python_client.clients.v2.common.response_payloads import list_payload_records
+from glpi_python_client.content.records.parsers.team import _glpi_team_member_record
+from glpi_python_client.models import GlpiTeamMember
+
+from .transport import SyncTransportMixin
+
+logger = logging.getLogger(__name__)
+
+
+class SyncTeamMixin(SyncTransportMixin):
+    """Synchronous GLPI ticket team member helpers.
+
+    The mixin keeps team-member payload construction and response handling out
+    of the public client class.
+    """
+
+    def get_team_member_records(self, ticket_id: GlpiId) -> list[GlpiTeamMember]:
+        """Fetch the team members currently linked to one ticket.
+
+        Non-success list responses are treated as empty results and logged as a
+        warning rather than raising immediately.
+        """
+
+        endpoint = f"{TICKET_ENDPOINT}/{ticket_id}/{TEAM_MEMBER_SUFFIX}"
+        response = self._get_request(endpoint)
+        if response.status_code not in (200, 206):
+            logger.warning(
+                "Failed to get team members for ticket %s: %s",
+                ticket_id,
+                response.status_code,
+            )
+            return []
+        return list_payload_records(
+            response.json(),
+            record_factory=_glpi_team_member_record,
+        )
+
+    def add_team_member(
+        self,
+        ticket_id: GlpiId,
+        member: GlpiTeamMember,
+    ) -> None:
+        """Add one team member to a GLPI ticket.
+
+        The method builds the API payload from the typed member object and logs
+        the resulting membership change on success.
+        """
+
+        endpoint = f"{TICKET_ENDPOINT}/{ticket_id}/{TEAM_MEMBER_SUFFIX}"
+        payload = build_team_member_payload(
+            member_type=member.member_type,
+            member_id=member.member_id,
+            role=member.role,
+        )
+        response = self._post_request(endpoint, payload)
+        ensure_response_status(
+            response,
+            success_statuses=(200, 201),
+            failure_message=(
+                "Failed to add team member "
+                f"{member.member_type}:{member.member_id} "
+                f"role={member.role} on ticket {ticket_id}"
+            ),
+        )
+        logger.info(
+            "GLPI API added team member %s:%s role=%s on ticket %s",
+            member.member_type,
+            member.member_id,
+            member.role,
+            ticket_id,
+        )
+        return None
+
+    def remove_team_member(
+        self,
+        ticket_id: GlpiId,
+        member: GlpiTeamMember,
+    ) -> None:
+        """Remove one team member from a GLPI ticket.
+
+        The payload shape mirrors team-member creation so the same member model
+        can be used for both add and remove workflows.
+        """
+
+        endpoint = f"{TICKET_ENDPOINT}/{ticket_id}/{TEAM_MEMBER_SUFFIX}"
+        payload = build_team_member_payload(
+            member_type=member.member_type,
+            member_id=member.member_id,
+            role=member.role,
+        )
+        response = self._delete_request(endpoint, payload)
+        ensure_response_status(
+            response,
+            success_statuses=(200, 204),
+            failure_message=(
+                "Failed to remove team member "
+                f"{member.member_type}:{member.member_id} "
+                f"role={member.role} from ticket {ticket_id}"
+            ),
+        )
+        logger.info(
+            "GLPI API removed team member %s:%s role=%s from ticket %s",
+            member.member_type,
+            member.member_id,
+            member.role,
+            ticket_id,
+        )
+        return None

glpi_python_client/clients/v2/sync/tests/__init__.py

@@ -0,0 +1,5 @@
+"""Sync v2 client tests colocated with sync implementation modules.
+
+Each test module mirrors the sync client file it exercises so behavior remains
+easy to find from the implementation filename.
+"""

glpi_python_client/clients/v2/sync/tests/test_directory.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import pytest
+
+from glpi_python_client import GlpiClient
+from glpi_python_client.testing.utils import SearchResponse
+
+
+def test_search_locations_escapes_query_text(
+    client_factory: Callable[..., GlpiClient],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    client = client_factory()
+    observed_params: dict[str, object] | None = None
+
+    def fake_get_request(
+        endpoint: str,
+        params: dict[str, object] | None = None,
+        skip_entity: bool = False,
+    ) -> SearchResponse:
+        nonlocal observed_params
+        assert endpoint == "Dropdowns/Location"
+        assert skip_entity is False
+        observed_params = params
+        return SearchResponse([])
+
+    monkeypatch.setattr(client, "_get_request", fake_get_request)
+    try:
+        client.search_locations('Paris "HQ" *East\\West')
+
+        assert observed_params == {
+            "filter": 'name=like="*Paris \\"HQ\\" \\*East\\\\West*"'
+        }
+    finally:
+        client.close()
+
+
+def test_search_locations_returns_empty_for_blank_query(
+    client_factory: Callable[..., GlpiClient],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    client = client_factory()
+
+    def fake_get_request(
+        endpoint: str,
+        params: dict[str, object] | None = None,
+        skip_entity: bool = False,
+    ) -> SearchResponse:
+        raise AssertionError("blank location search should not call GLPI")
+
+    monkeypatch.setattr(client, "_get_request", fake_get_request)
+    try:
+        assert client.search_locations("  ") == []
+    finally:
+        client.close()

glpi_python_client/clients/v2/sync/tests/test_documents.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import pytest
+
+from glpi_python_client import GlpiClient
+from glpi_python_client.testing.utils import FakeResponse, SearchResponse
+
+
+def _empty_response() -> FakeResponse:
+    return FakeResponse(status_code=204, payload={}, text="", content=b"")
+
+
+def test_get_document_records_can_skip_metadata_enrichment(
+    client_factory: Callable[..., GlpiClient],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    client = client_factory()
+    metadata_calls: list[str] = []
+
+    def fake_get_request(
+        endpoint: str,
+        params: dict[str, object] | None = None,
+        skip_entity: bool = False,
+    ) -> SearchResponse:
+        assert endpoint == "Assistance/Ticket/321/Timeline/Document"
+        assert params is None
+        assert skip_entity is False
+        return SearchResponse([{"documents_id": 654, "name": "diagnostic.txt"}])
+
+    def fake_get_document_record(document_id: str | int) -> None:
+        metadata_calls.append(str(document_id))
+
+    monkeypatch.setattr(client, "_get_request", fake_get_request)
+    monkeypatch.setattr(client, "get_document_record", fake_get_document_record)
+    try:
+        documents = client.get_document_records(321, enrich_metadata=False)
+
+        assert metadata_calls == []
+        assert documents[0].document_id == "654"
+        assert documents[0].filename == "diagnostic.txt"
+    finally:
+        client.close()
+
+
+def test_get_document_records_logs_metadata_enrichment_failures(
+    client_factory: Callable[..., GlpiClient],
+    monkeypatch: pytest.MonkeyPatch,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    client = client_factory()
+
+    def fake_get_request(
+        endpoint: str,
+        params: dict[str, object] | None = None,
+        skip_entity: bool = False,
+    ) -> SearchResponse:
+        assert endpoint == "Assistance/Ticket/321/Timeline/Document"
+        assert params is None
+        assert skip_entity is False
+        return SearchResponse([{"documents_id": 654, "name": "diagnostic.txt"}])
+
+    def fake_get_document_record(document_id: str | int) -> None:
+        raise ValueError(f"document {document_id} unavailable")
+
+    monkeypatch.setattr(client, "_get_request", fake_get_request)
+    monkeypatch.setattr(client, "get_document_record", fake_get_document_record)
+    caplog.set_level("WARNING", logger="glpi_python_client.clients.v2.sync")
+    try:
+        documents = client.get_document_records(321)
+
+        assert documents[0].document_id == "654"
+        assert "Skipping GLPI document 654 metadata lookup" in caplog.text
+    finally:
+        client.close()
+
+
+def test_delete_document_returns_none(
+    client_factory: Callable[..., GlpiClient],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    client = client_factory()
+
+    def fake_delete_request(
+        endpoint: str,
+        payload: dict[str, object] | None = None,
+        skip_entity: bool = False,
+    ) -> FakeResponse:
+        assert endpoint == "Management/Document/777"
+        assert payload is None
+        assert skip_entity is True
+        return _empty_response()
+
+    monkeypatch.setattr(client, "_delete_request", fake_delete_request)
+    try:
+        client.delete_document(777)
+    finally:
+        client.close()