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

glpi_python_client/clients/v2/async_/directory.py

@@ -0,0 +1,88 @@
+"""Asynchronous user and location lookup operations for GLPI v2 clients.
+
+This module contains the directory-style async 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 AsyncTransportMixin
+
+
+class AsyncDirectoryMixin(AsyncTransportMixin):
+    """Asynchronous GLPI user and location lookup helpers.
+
+    The methods in this mixin return typed directory models while awaiting the
+    async transport helpers for remote execution.
+    """
+
+    async 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 async helper preserves the same filtering and empty-result behavior
+        as the synchronous implementation while awaiting the remote request.
+        """
+
+        params: dict[str, object] = {"limit": limit, "start": start}
+        if rsql_filter:
+            params["filter"] = rsql_filter
+        response = await 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
+            ),
+        )
+
+    async def search_locations(self, name: str) -> list[GlpiLocation]:
+        """Search GLPI locations by name.
+
+        Blank names are rejected locally by returning an empty list, and remote
+        non-success statuses are normalized to empty results.
+        """
+
+        location_filter = rsql_contains_filter("name", name)
+        if location_filter is None:
+            return []
+
+        response = await 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/async_/documents.py

@@ -0,0 +1,144 @@
+"""Asynchronous document operations for GLPI v2 clients.
+
+This module covers async 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 AsyncTransportMixin
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncDocumentMixin(AsyncTransportMixin):
+    """Asynchronous GLPI ticket document helpers.
+
+    These helpers keep document parsing and optional metadata enrichment aligned
+    with the synchronous client while exposing awaitable operations.
+    """
+
+    async 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
+        async lookups and logs skipped enrichments without failing the whole
+        batch.
+        """
+
+        endpoint = f"{TICKET_ENDPOINT}/{ticket_id}/{DOCUMENT_SUFFIX}"
+        response = await 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 = await 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
+
+    async 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 = await 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)
+
+    async def download_document_content(self, document_id: GlpiId) -> bytes:
+        """Download the raw binary payload for one GLPI document.
+
+        This helper returns raw response bytes and keeps the async content
+        retrieval workflow aligned with the synchronous client.
+        """
+
+        response = await 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
+
+    async def delete_document(self, document_id: GlpiId) -> None:
+        """Delete one GLPI document by identifier.
+
+        Successful deletes return ``None`` and are logged for traceability.
+        """
+
+        response = await 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/async_/team.py

@@ -0,0 +1,125 @@
+"""Asynchronous team member operations for GLPI v2 clients.
+
+This module provides the async 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 AsyncTransportMixin
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncTeamMixin(AsyncTransportMixin):
+    """Asynchronous GLPI ticket team member helpers.
+
+    The mixin keeps team-member payload construction and response handling out
+    of the public async client class.
+    """
+
+    async 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 logged and normalized to an empty result
+        list rather than raising immediately.
+        """
+
+        endpoint = f"{TICKET_ENDPOINT}/{ticket_id}/{TEAM_MEMBER_SUFFIX}"
+        response = await 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,
+        )
+
+    async def add_team_member(
+        self,
+        ticket_id: GlpiId,
+        member: GlpiTeamMember,
+    ) -> None:
+        """Add one team member to a GLPI ticket.
+
+        The typed member object is converted into the payload expected by GLPI,
+        and the successful mutation is logged with the affected ticket.
+        """
+
+        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 = await 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
+
+    async def remove_team_member(
+        self,
+        ticket_id: GlpiId,
+        member: GlpiTeamMember,
+    ) -> None:
+        """Remove one team member from a GLPI ticket.
+
+        The payload mirrors team-member creation so the same member model can be
+        reused for 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 = await 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/async_/tests/__init__.py

@@ -0,0 +1,5 @@
+"""Async v2 client tests colocated with async implementation modules.
+
+Each test module mirrors the async client file it exercises so sync and async
+coverage can evolve alongside their respective implementations.
+"""

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

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from glpi_python_client import AsyncGlpiClient
+from glpi_python_client.testing.utils import SearchResponse
+
+
+def test_async_search_locations_escapes_query_text(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    async def run_test() -> None:
+        client = AsyncGlpiClient(
+            glpi_api_url="https://glpi.example.test/api.php/",
+            client_id="client-id",
+            client_secret="client-secret",
+        )
+        observed_params: dict[str, object] | None = None
+
+        async 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:
+            await client.search_locations('Paris "HQ" *East\\West')
+
+            assert observed_params == {
+                "filter": 'name=like="*Paris \\"HQ\\" \\*East\\\\West*"'
+            }
+        finally:
+            await client.close()
+
+    asyncio.run(run_test())

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

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from glpi_python_client import AsyncGlpiClient
+from glpi_python_client.testing.utils import FakeResponse
+
+
+def _empty_response() -> FakeResponse:
+    return FakeResponse(status_code=204, payload={}, text="", content=b"")
+
+
+def test_async_delete_document_returns_none(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    async def run_test() -> None:
+        client = AsyncGlpiClient(
+            glpi_api_url="https://glpi.example.test/api.php/",
+            client_id="client-id",
+            client_secret="client-secret",
+        )
+
+        async 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:
+            await client.delete_document(777)
+        finally:
+            await client.close()
+
+    asyncio.run(run_test())

glpi_python_client/clients/v2/async_/tests/test_team.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from glpi_python_client import AsyncGlpiClient, GlpiTeamMember
+from glpi_python_client.testing.utils import FakeResponse
+
+
+def _empty_response() -> FakeResponse:
+    return FakeResponse(status_code=204, payload={}, text="", content=b"")
+
+
+def test_async_remove_team_member_returns_none(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    async def run_test() -> None:
+        client = AsyncGlpiClient(
+            glpi_api_url="https://glpi.example.test/api.php/",
+            client_id="client-id",
+            client_secret="client-secret",
+        )
+
+        async def fake_delete_request(
+            endpoint: str,
+            payload: dict[str, object] | None = None,
+            skip_entity: bool = False,
+        ) -> FakeResponse:
+            assert endpoint == "Assistance/Ticket/321/TeamMember"
+            assert payload == {"type": "User", "id": 99, "role": "1"}
+            assert skip_entity is False
+            return _empty_response()
+
+        monkeypatch.setattr(client, "_delete_request", fake_delete_request)
+        try:
+            await client.remove_team_member(
+                321,
+                GlpiTeamMember(member_type="User", member_id=99, role="1"),
+            )
+        finally:
+            await client.close()
+
+    asyncio.run(run_test())

glpi_python_client/clients/v2/async_/tests/test_tickets.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from glpi_python_client import AsyncGlpiClient, GlpiTicket
+from glpi_python_client.testing.utils import (
+    FakeResponse,
+    SearchResponse,
+    TicketResponse,
+    make_ticket_record,
+)
+
+
+def _empty_response() -> FakeResponse:
+    return FakeResponse(status_code=204, payload={}, text="", content=b"")
+
+
+def test_async_get_ticket_record_can_include_deleted_ticket(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    async def run_test() -> None:
+        client = AsyncGlpiClient(
+            glpi_api_url="https://glpi.example.test/api.php/",
+            client_id="client-id",
+            client_secret="client-secret",
+        )
+
+        async def fake_get_request(
+            endpoint: str,
+            params: dict[str, object] | None = None,
+            skip_entity: bool = False,
+        ) -> TicketResponse:
+            assert endpoint == "Assistance/Ticket/123"
+            assert params is None
+            assert skip_entity is False
+            return TicketResponse(make_ticket_record(id=123, is_deleted=1))
+
+        monkeypatch.setattr(client, "_get_request", fake_get_request)
+        try:
+            ticket = await client.get_ticket_record(
+                "123",
+                include_deleted_ticket=True,
+            )
+
+            assert ticket.id == "123"
+        finally:
+            await client.close()
+
+    asyncio.run(run_test())
+
+
+def test_async_create_ticket_accepts_public_extra_payload(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    async def run_test() -> None:
+        client = AsyncGlpiClient(
+            glpi_api_url="https://glpi.example.test/api.php/",
+            client_id="client-id",
+            client_secret="client-secret",
+        )
+        payload_data: dict[str, object] | None = None
+
+        async def fake_post_request(
+            endpoint: str,
+            payload: dict[str, object] | None = None,
+            skip_entity: bool = False,
+        ) -> FakeResponse:
+            nonlocal payload_data
+            assert endpoint == "Assistance/Ticket"
+            assert skip_entity is False
+            assert payload is not None
+            payload_data = payload
+            return FakeResponse()
+
+        monkeypatch.setattr(client, "_post_request", fake_post_request)
+        try:
+            created = await client.create_ticket(
+                GlpiTicket(
+                    name="Need help",
+                    extra_payload={"_room_code": "PAR-3F-12"},
+                )
+            )
+
+            assert created == "321"
+            assert payload_data == {
+                "name": "Need help",
+                "_room_code": "PAR-3F-12",
+            }
+        finally:
+            await client.close()
+
+    asyncio.run(run_test())
+
+
+def test_async_delete_ticket_returns_none(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    async def run_test() -> None:
+        client = AsyncGlpiClient(
+            glpi_api_url="https://glpi.example.test/api.php/",
+            client_id="client-id",
+            client_secret="client-secret",
+        )
+
+        async def fake_delete_request(
+            endpoint: str,
+            payload: dict[str, object] | None = None,
+            skip_entity: bool = False,
+        ) -> FakeResponse:
+            assert endpoint == "Assistance/Ticket/321"
+            assert payload is None
+            assert skip_entity is False
+            return _empty_response()
+
+        monkeypatch.setattr(client, "_delete_request", fake_delete_request)
+        try:
+            await client.delete_ticket(321)
+        finally:
+            await client.close()
+
+    asyncio.run(run_test())
+
+
+def test_async_search_ticket_records_returns_full_list_by_default(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    async def run_test() -> None:
+        client = AsyncGlpiClient(
+            glpi_api_url="https://glpi.example.test/api.php/",
+            client_id="client-id",
+            client_secret="client-secret",
+        )
+        requests: list[dict[str, object]] = []
+        responses = iter(
+            [
+                SearchResponse(
+                    [
+                        make_ticket_record(id=1, name="Ticket 1"),
+                        make_ticket_record(id=2, name="Ticket 2"),
+                    ],
+                    status_code=206,
+                    headers={"Content-Range": "0-1/3"},
+                ),
+                SearchResponse(
+                    [make_ticket_record(id=3, name="Ticket 3")],
+                    status_code=200,
+                    headers={"Content-Range": "2-2/3"},
+                ),
+            ]
+        )
+
+        async def fake_get_request(
+            endpoint: str,
+            params: dict[str, object] | None = None,
+            skip_entity: bool = False,
+        ) -> SearchResponse:
+            assert endpoint == "Assistance/Ticket"
+            assert skip_entity is False
+            requests.append(dict(params or {}))
+            return next(responses)
+
+        monkeypatch.setattr(client, "_get_request", fake_get_request)
+        try:
+            tickets = await client.search_ticket_records()
+
+            assert [ticket.id for ticket in tickets] == ["1", "2", "3"]
+            assert [request["start"] for request in requests] == [0, 2]
+            assert all("limit" not in request for request in requests)
+        finally:
+            await client.close()
+
+    asyncio.run(run_test())