glpi-python-client 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

glpi_python_client/__init__.py

@@ -72,7 +72,7 @@ from glpi_python_client.models import (
     TicketMarkdownOptions,
 )
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"
 
 __all__ = [
     "AsyncGlpiClient",

glpi_python_client/clients/async_client.py

@@ -50,6 +50,7 @@ from glpi_python_client.clients.commons._config import (
     build_client_resources,
 )
 from glpi_python_client.clients.commons._transport import TransportMixin
+from glpi_python_client.clients.custom._pagination_async import AsyncPaginationMixin
 from glpi_python_client.clients.custom._statistics_async import AsyncStatisticsMixin
 from glpi_python_client.clients.custom._ticket_context_async import (
     AsyncTicketContextMixin,
@@ -61,8 +62,9 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-class AsyncGlpiClient(
+class AsyncGlpiClient(  # type: ignore[misc]
     AsyncBridge,
+    AsyncPaginationMixin,
     TicketMixin,
     TicketTaskMixin,
     FollowupMixin,

glpi_python_client/clients/commons/_async_bridge.py

@@ -22,6 +22,23 @@ Concurrency notes
   releases the awaiter immediately, but the in-flight HTTP request keeps
   running on the worker thread until ``requests`` returns. This matches
   the behaviour of the original async client.
+
+Known limitation — internal ``self``-calls
+------------------------------------------
+The bridge wraps *every* public method on the async client class. As a
+result, when a synchronous body that is running inside a worker thread
+calls another public method through ``self`` (e.g.
+``self.search_tickets(...)``), it resolves to the *bridge-wrapped*
+coroutine, not the synchronous function. Calling a coroutine without
+``await`` produces a dangling coroutine object, not data.
+
+Any sync method (or generator) that internally calls other public
+methods through ``self`` must therefore be given a hand-written async
+override that ``await``s (or ``async for``s) those calls on the event
+loop. The convention used in this codebase is to place such overrides
+in a ``_*_async.py`` companion module (e.g.
+``clients/custom/_statistics_async.py``) and wire them into the async
+client's MRO *before* the sync mixin that defines the original method.
 """
 
 from __future__ import annotations

glpi_python_client/clients/custom/__init__.py

@@ -17,6 +17,7 @@ composed into :class:`~glpi_python_client.clients.AsyncGlpiClient`.
 
 from __future__ import annotations
 
+from glpi_python_client.clients.custom._pagination_async import AsyncPaginationMixin
 from glpi_python_client.clients.custom._statistics import StatisticsMixin
 from glpi_python_client.clients.custom._statistics_async import AsyncStatisticsMixin
 from glpi_python_client.clients.custom._ticket_context import TicketContextMixin
@@ -25,6 +26,7 @@ from glpi_python_client.clients.custom._ticket_context_async import (
 )
 
 __all__ = [
+    "AsyncPaginationMixin",
     "AsyncStatisticsMixin",
     "AsyncTicketContextMixin",
     "StatisticsMixin",

glpi_python_client/clients/custom/_pagination_async.py

@@ -0,0 +1,164 @@
+"""Asynchronous overrides for the three paginated search generators.
+
+Each of the three ``iter_search_*`` generators in the API mixins
+delegates its pagination loop to a ``self.search_*()`` call.  When the
+:class:`~glpi_python_client.clients.commons._async_bridge.AsyncBridge`
+wraps a sync generator it drives ``next()`` on the generator object inside
+a worker thread.  Inside that thread ``self`` is still the
+:class:`~glpi_python_client.clients.AsyncGlpiClient` instance, so
+``self.search_tickets(...)`` resolves to the bridge-wrapped coroutine
+function and calling it without ``await`` returns a coroutine object
+instead of the expected list — triggering a
+``RuntimeWarning: coroutine … was never awaited`` and a 500 response.
+
+This mixin replaces all three generators with native async generators that
+``await self.search_*(...)`` directly on the event loop.
+
+The mixin must be positioned **before** ``TicketMixin``, ``UserMixin``, and
+``EntityMixin`` in the :class:`~glpi_python_client.clients.AsyncGlpiClient`
+base list so that the bridge's ``__init_subclass__`` hook finds the async
+generator via ``getattr`` before it would otherwise wrap the sync version.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+
+from glpi_python_client.models.api_schema.administration._entity import GetEntity
+from glpi_python_client.models.api_schema.administration._user import GetUser
+from glpi_python_client.models.api_schema.assistance._ticket import GetTicket
+
+
+class AsyncPaginationMixin:
+    """Async generator overrides for the three paginated search helpers.
+
+    Each override re-implements the simple ``start``-advancing loop of
+    the synchronous counterpart but ``await``\\ s the underlying
+    ``search_*`` call so it runs on the event loop rather than inside a
+    worker-thread-dispatched ``next()`` call where the coroutine would
+    be dropped on the floor.
+    """
+
+    async def iter_search_tickets(
+        self,
+        rsql_filter: str = "",
+        *,
+        batch_size: int = 50,
+        sort: str | None = None,
+        fields: tuple[str, ...] = (),
+    ) -> AsyncIterator[list[GetTicket]]:
+        """Yield successive pages of GLPI tickets until exhausted.
+
+        Parameters
+        ----------
+        rsql_filter : str, optional
+            Raw RSQL filter forwarded as the ``filter`` query parameter.
+            Empty by default, which lists every visible ticket.
+        batch_size : int, optional
+            Number of records requested per page (default 50).
+        sort : str | None, optional
+            ``sort`` query parameter forwarded as-is to each page request.
+        fields : tuple[str, ...], optional
+            Restricted set of contract field names to request.
+
+        Yields
+        ------
+        list[GetTicket]
+            One page of tickets per iteration. The last yielded batch may
+            be shorter than ``batch_size``.
+        """
+
+        start = 0
+        while True:
+            batch: list[GetTicket] = await self.search_tickets(  # type: ignore[attr-defined]
+                rsql_filter,
+                limit=batch_size,
+                start=start,
+                sort=sort,
+                fields=fields,
+            )
+            if batch:
+                yield batch
+            if len(batch) < batch_size:
+                break
+            start += batch_size
+
+    async def iter_search_users(
+        self,
+        rsql_filter: str = "",
+        *,
+        batch_size: int = 50,
+        skip_entity: bool = False,
+    ) -> AsyncIterator[list[GetUser]]:
+        """Yield successive pages of GLPI users until exhausted.
+
+        Parameters
+        ----------
+        rsql_filter : str, optional
+            Raw RSQL filter forwarded as the ``filter`` query parameter.
+            Empty by default, which lists every visible user.
+        batch_size : int, optional
+            Number of records requested per page (default 50).
+        skip_entity : bool, optional
+            When ``True`` the ``GLPI-Entity`` header is omitted so the
+            search spans every entity the caller has access to.
+
+        Yields
+        ------
+        list[GetUser]
+            One page of users per iteration. The last yielded batch may
+            be shorter than ``batch_size``.
+        """
+
+        start = 0
+        while True:
+            batch: list[GetUser] = await self.search_users(  # type: ignore[attr-defined]
+                rsql_filter,
+                limit=batch_size,
+                start=start,
+                skip_entity=skip_entity,
+            )
+            if batch:
+                yield batch
+            if len(batch) < batch_size:
+                break
+            start += batch_size
+
+    async def iter_search_entities(
+        self,
+        rsql_filter: str = "",
+        *,
+        batch_size: int = 50,
+    ) -> AsyncIterator[list[GetEntity]]:
+        """Yield successive pages of GLPI entities until exhausted.
+
+        Parameters
+        ----------
+        rsql_filter : str, optional
+            Raw RSQL filter forwarded as the ``filter`` query parameter.
+            Empty by default, which lists every accessible entity.
+        batch_size : int, optional
+            Number of records requested per page (default 50).
+
+        Yields
+        ------
+        list[GetEntity]
+            One page of entities per iteration. The last yielded batch
+            may be shorter than ``batch_size``.
+        """
+
+        start = 0
+        while True:
+            batch: list[GetEntity] = await self.search_entities(  # type: ignore[attr-defined]
+                rsql_filter,
+                limit=batch_size,
+                start=start,
+            )
+            if batch:
+                yield batch
+            if len(batch) < batch_size:
+                break
+            start += batch_size
+
+
+__all__ = ["AsyncPaginationMixin"]

glpi_python_client/clients/custom/_statistics_async.py

@@ -1,11 +1,17 @@
-"""Asynchronous override for the statistics aggregation helper.
-
-The async mixin overrides :meth:`get_task_statistics` and
-:meth:`get_task_durations` so the per-ticket task-listing calls are
-dispatched concurrently using :func:`asyncio.gather`.
-``get_ticket_statistics`` does not need a custom override because it issues
-a single GLPI request and therefore behaves correctly when wrapped by the
-bridge into a coroutine.
+"""Asynchronous overrides for the statistics aggregation helper.
+
+The async mixin overrides :meth:`get_ticket_statistics`,
+:meth:`get_task_statistics`, :meth:`get_task_durations`, and
+:meth:`get_user_activity` so that every internal ``self.*`` call that
+would otherwise be dispatched as a bridge-wrapped coroutine is properly
+awaited. Without these overrides the bridge runs the synchronous mixin
+bodies in a worker thread where the bridge-wrapped methods on ``self``
+return unawaited coroutines instead of data, producing a
+``RuntimeWarning: coroutine … was never awaited`` error.
+
+:meth:`get_task_statistics` and :meth:`get_task_durations` additionally
+dispatch their per-ticket ``list_ticket_tasks`` fan-outs concurrently
+using :func:`asyncio.gather`.
 """
 
 from __future__ import annotations
@@ -16,6 +22,7 @@ from glpi_python_client.clients.custom._statistics import (
     StatisticsMixin,
     TaskDurationsResult,
     TaskStatisticsResult,
+    UserActivityResult,
     _entity_key,
     _summarize_tasks,
 )
@@ -246,5 +253,243 @@ class AsyncStatisticsMixin(StatisticsMixin):
             tasks=task_details,
         )
 
+    async def get_ticket_statistics(  # type: ignore[override]
+        self,
+        *,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        default_days: int = 30,
+        entity_id: int | None = None,
+        entity_name: str | None = None,
+        extra_filter: str | None = None,
+    ) -> dict[str, object]:
+        """Return ticket counts grouped by entity, status, priority, and type.
+
+        Async override of :meth:`StatisticsMixin.get_ticket_statistics`.
+        The synchronous base runs in a worker thread where ``self.search_tickets``
+        and ``self.search_entities`` resolve to bridge-wrapped coroutines that
+        would be silently dropped. This override awaits those calls directly on
+        the event loop instead.
+
+        Parameters
+        ----------
+        start_date : str | None, optional
+            ISO ``YYYY-MM-DD`` start of the window.
+        end_date : str | None, optional
+            ISO ``YYYY-MM-DD`` end of the window. Defaults to today.
+        default_days : int, optional
+            Span in days used when ``start_date`` is omitted (default 30).
+        entity_id : int | None, optional
+            Restrict to tickets in this entity.
+        entity_name : str | None, optional
+            Resolve entity by name and restrict to matched entities.
+        extra_filter : str | None, optional
+            Optional raw RSQL fragment appended as an AND clause.
+
+        Returns
+        -------
+        dict[str, object]
+            Same shape as the synchronous :meth:`get_ticket_statistics`.
+
+        Raises
+        ------
+        ValueError
+            If ``default_days < 1`` or ``start_date > end_date``.
+        """
+
+        from glpi_python_client.clients.commons._filters import (
+            rsql_all_filter,
+            rsql_any_filter,
+            rsql_contains_filter,
+        )
+        from glpi_python_client.clients.custom._statistics import (
+            _resolve_window,
+            _summarize_tickets,
+        )
+
+        start, end = _resolve_window(
+            start_date=start_date,
+            end_date=end_date,
+            default_days=default_days,
+        )
+
+        entity_filter: str | None = None
+        if entity_id is not None:
+            entity_filter = f"entities_id=={entity_id}"
+        elif entity_name is not None:
+            name_filter = rsql_contains_filter("name", entity_name) or ""
+            entities = await self.search_entities(  # type: ignore[attr-defined]
+                rsql_filter=name_filter,
+                limit=200,
+            )
+            if not entities:
+                return {"entities": {}}
+            entity_filter = rsql_any_filter(
+                *(f"entities_id=={e.id}" for e in entities if e.id is not None)
+            )
+
+        query = rsql_all_filter(
+            f"date_creation=ge={start.isoformat()};date_creation=le={end.isoformat()}",
+            entity_filter,
+            extra_filter,
+        )
+        tickets = await self.search_tickets(  # type: ignore[attr-defined]
+            rsql_filter=query or "",
+            limit=200,
+        )
+        return _summarize_tickets(tickets)
+
+    async def get_user_activity(  # type: ignore[override]
+        self,
+        *,
+        user_id: int | None = None,
+        username: str | None = None,
+        realname: str | None = None,
+        firstname: str | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        default_days: int = 30,
+    ) -> UserActivityResult:
+        """Return per-user GLPI activity aggregated across tickets and tasks.
+
+        Async override of :meth:`StatisticsMixin.get_user_activity`. The
+        synchronous base calls ``self.search_users``, ``self.iter_search_tickets``,
+        and ``self.get_task_durations`` through ``self``, which on the async
+        client resolve to bridge-wrapped coroutines. This override awaits those
+        calls and uses ``async for`` on the async generator.
+
+        Parameters
+        ----------
+        user_id : int | None, optional
+            Identify the user by GLPI numeric identifier.
+        username : str | None, optional
+            Filter by username (substring match).
+        realname : str | None, optional
+            Filter by family name (substring match).
+        firstname : str | None, optional
+            Filter by given name (substring match).
+        start_date : str | None, optional
+            ISO ``YYYY-MM-DD`` start of the activity window.
+        end_date : str | None, optional
+            ISO ``YYYY-MM-DD`` end of the activity window. Defaults to today.
+        default_days : int, optional
+            Span in days used when ``start_date`` is omitted (default 30).
+
+        Returns
+        -------
+        UserActivityResult
+            Same shape as the synchronous :meth:`get_user_activity`.
+
+        Raises
+        ------
+        ValueError
+            If none of ``user_id``, ``username``, ``realname``, or
+            ``firstname`` are supplied, or if the supplied criteria match
+            no GLPI users.
+        """
+
+        from glpi_python_client.clients.commons._filters import (
+            rsql_all_filter,
+            rsql_contains_filter,
+        )
+        from glpi_python_client.clients.custom._statistics import (
+            UserActivityEntry,
+            UserActivityResult,
+            _merge_task_durations,
+            _resolve_window,
+        )
+
+        if all(v is None for v in (user_id, username, realname, firstname)):
+            raise ValueError(
+                "At least one of user_id, username, realname, or "
+                "firstname must be supplied"
+            )
+
+        start, end = _resolve_window(
+            start_date=start_date,
+            end_date=end_date,
+            default_days=default_days,
+        )
+
+        if user_id is not None:
+            resolved_user_ids: list[int] = [user_id]
+            user_display_map: dict[int, str] = {user_id: str(user_id)}
+        else:
+            name_parts = [
+                rsql_contains_filter("username", username) if username else None,
+                rsql_contains_filter("realname", realname) if realname else None,
+                rsql_contains_filter("firstname", firstname) if firstname else None,
+            ]
+            user_rsql = rsql_all_filter(*name_parts) or ""
+            matched_users = await self.search_users(  # type: ignore[attr-defined]
+                rsql_filter=user_rsql,
+                limit=200,
+            )
+            if not matched_users:
+                raise ValueError("No users matched the supplied criteria")
+            resolved_user_ids = [u.id for u in matched_users if u.id is not None]
+            user_display_map = {
+                u.id: (
+                    f"{u.firstname or ''} {u.realname or ''}".strip()
+                    or u.username
+                    or str(u.id)
+                )
+                for u in matched_users
+                if u.id is not None
+            }
+
+        date_range = (
+            f"date_creation=ge={start.isoformat()};date_creation=le={end.isoformat()}"
+        )
+
+        users_output: dict[str, UserActivityEntry] = {}
+        for uid in resolved_user_ids:
+            display_key = user_display_map.get(uid, str(uid))
+            tech_count = 0
+            async for batch in self.iter_search_tickets(  # type: ignore[attr-defined]
+                f"users_id_assign=={uid};{date_range}",
+                batch_size=200,
+            ):
+                tech_count += len(batch)
+            recipient_count = 0
+            async for batch in self.iter_search_tickets(  # type: ignore[attr-defined]
+                f"users_id_requester=={uid};{date_range}",
+                batch_size=200,
+            ):
+                recipient_count += len(batch)
+            task_dur = await self.get_task_durations(
+                start_date=start_date,
+                end_date=end_date,
+                default_days=default_days,
+                user_id=uid,
+            )
+            task_dur_clean: TaskDurationsResult = TaskDurationsResult(
+                start_date=task_dur["start_date"],
+                end_date=task_dur["end_date"],
+                total_duration=task_dur["total_duration"],
+                task_count=task_dur["task_count"],
+                duration_by_user=dict(task_dur["duration_by_user"]),
+                duration_by_entity=dict(task_dur["duration_by_entity"]),
+                tasks=None,
+            )
+
+            if display_key in users_output:
+                existing = users_output[display_key]
+                existing["user_ids"] = [*existing["user_ids"], uid]
+                existing["tickets_as_technician"] += tech_count
+                existing["tickets_as_recipient"] += recipient_count
+                existing["task_durations"] = _merge_task_durations(
+                    existing["task_durations"], task_dur_clean
+                )
+            else:
+                users_output[display_key] = UserActivityEntry(
+                    user_ids=[uid],
+                    tickets_as_technician=tech_count,
+                    tickets_as_recipient=recipient_count,
+                    task_durations=task_dur_clean,
+                )
+
+        return UserActivityResult(users=users_output)
+
 
 __all__ = ["AsyncStatisticsMixin"]

glpi_python_client/clients/tests/test_async_branches.py

@@ -193,3 +193,509 @@ async def test_async_generator_wrapper_with_executor() -> None:
     assert batches == [["one"]]
     assert captured_threads
     assert all(name.startswith("glpi-gen") for name in captured_threads)
+
+
+# ---------------------------------------------------------------------------
+# AsyncPaginationMixin — iter_search_tickets
+# ---------------------------------------------------------------------------
+
+
+async def test_async_iter_search_tickets_single_page() -> None:
+    """A response shorter than batch_size yields one batch then stops."""
+
+    client = make_async_client()
+    call_count = 0
+
+    async def fake_search(
+        rsql_filter: str = "",
+        *,
+        limit: int = 50,
+        start: int = 0,
+        sort: str | None = None,
+        fields: tuple[str, ...] = (),
+    ) -> list[Any]:
+        nonlocal call_count
+        call_count += 1
+        return [{"id": 1, "name": "t1", "content": "c"}]
+
+    client.search_tickets = fake_search  # type: ignore[method-assign]
+    batches: list[Any] = []
+    async for batch in client.iter_search_tickets("status==1", batch_size=50):
+        batches.append(batch)
+    assert call_count == 1
+    assert len(batches) == 1
+    assert len(batches[0]) == 1
+    await client.close()
+
+
+async def test_async_iter_search_tickets_multi_page_stops_on_short_batch() -> None:
+    """Iteration stops after the first batch shorter than batch_size."""
+
+    client = make_async_client()
+    responses = [
+        [
+            {"id": 1, "name": "a", "content": "c"},
+            {"id": 2, "name": "b", "content": "c"},
+        ],
+        [{"id": 3, "name": "c", "content": "c"}],
+    ]
+    call_count = 0
+
+    async def fake_search(
+        rsql_filter: str = "",
+        *,
+        limit: int = 50,
+        start: int = 0,
+        sort: str | None = None,
+        fields: tuple[str, ...] = (),
+    ) -> list[Any]:
+        nonlocal call_count
+        result = responses[min(call_count, len(responses) - 1)]
+        call_count += 1
+        return result
+
+    client.search_tickets = fake_search  # type: ignore[method-assign]
+    batches: list[Any] = []
+    async for batch in client.iter_search_tickets("", batch_size=2):
+        batches.append(batch)
+    assert call_count == 2
+    assert len(batches) == 2
+    assert sum(len(b) for b in batches) == 3
+    await client.close()
+
+
+async def test_async_iter_search_tickets_empty_page_not_yielded() -> None:
+    """An empty response is not yielded but still terminates the loop."""
+
+    client = make_async_client()
+
+    async def fake_search(
+        rsql_filter: str = "",
+        *,
+        limit: int = 50,
+        start: int = 0,
+        sort: str | None = None,
+        fields: tuple[str, ...] = (),
+    ) -> list[Any]:
+        return []
+
+    client.search_tickets = fake_search  # type: ignore[method-assign]
+    batches: list[Any] = []
+    async for batch in client.iter_search_tickets("status==1", batch_size=50):
+        batches.append(batch)
+    assert batches == []
+    await client.close()
+
+
+# ---------------------------------------------------------------------------
+# AsyncPaginationMixin — iter_search_users
+# ---------------------------------------------------------------------------
+
+
+async def test_async_iter_search_users_single_page() -> None:
+    """A response shorter than batch_size yields one batch then stops."""
+
+    client = make_async_client()
+    call_count = 0
+
+    async def fake_search(
+        rsql_filter: str = "",
+        *,
+        limit: int = 50,
+        start: int = 0,
+        skip_entity: bool = False,
+    ) -> list[Any]:
+        nonlocal call_count
+        call_count += 1
+        return [{"id": 1, "username": "alice"}]
+
+    client.search_users = fake_search  # type: ignore[method-assign]
+    batches: list[Any] = []
+    async for batch in client.iter_search_users("username==alice", batch_size=50):
+        batches.append(batch)
+    assert call_count == 1
+    assert len(batches) == 1
+    await client.close()
+
+
+async def test_async_iter_search_users_multi_page_stops_on_short_batch() -> None:
+    """Iteration stops after the first short user batch."""
+
+    client = make_async_client()
+    responses = [
+        [{"id": 1, "username": "alice"}, {"id": 2, "username": "bob"}],
+        [{"id": 3, "username": "carol"}],
+    ]
+    call_count = 0
+
+    async def fake_search(
+        rsql_filter: str = "",
+        *,
+        limit: int = 50,
+        start: int = 0,
+        skip_entity: bool = False,
+    ) -> list[Any]:
+        nonlocal call_count
+        result = responses[min(call_count, len(responses) - 1)]
+        call_count += 1
+        return result
+
+    client.search_users = fake_search  # type: ignore[method-assign]
+    batches: list[Any] = []
+    async for batch in client.iter_search_users("", batch_size=2):
+        batches.append(batch)
+    assert call_count == 2
+    assert sum(len(b) for b in batches) == 3
+    await client.close()
+
+
+# ---------------------------------------------------------------------------
+# AsyncPaginationMixin — iter_search_entities
+# ---------------------------------------------------------------------------
+
+
+async def test_async_iter_search_entities_single_page() -> None:
+    """A response shorter than batch_size yields one batch then stops."""
+
+    client = make_async_client()
+    call_count = 0
+
+    async def fake_search(
+        rsql_filter: str = "",
+        *,
+        limit: int = 50,
+        start: int = 0,
+    ) -> list[Any]:
+        nonlocal call_count
+        call_count += 1
+        return [{"id": 1, "name": "root"}]
+
+    client.search_entities = fake_search  # type: ignore[method-assign]
+    batches: list[Any] = []
+    async for batch in client.iter_search_entities("", batch_size=50):
+        batches.append(batch)
+    assert call_count == 1
+    assert len(batches) == 1
+    await client.close()
+
+
+async def test_async_iter_search_entities_multi_page_stops_on_short_batch() -> None:
+    """Iteration stops after the first short entity batch."""
+
+    client = make_async_client()
+    responses = [
+        [{"id": 1, "name": "a"}, {"id": 2, "name": "b"}],
+        [{"id": 3, "name": "c"}],
+    ]
+    call_count = 0
+
+    async def fake_search(
+        rsql_filter: str = "",
+        *,
+        limit: int = 50,
+        start: int = 0,
+    ) -> list[Any]:
+        nonlocal call_count
+        result = responses[min(call_count, len(responses) - 1)]
+        call_count += 1
+        return result
+
+    client.search_entities = fake_search  # type: ignore[method-assign]
+    batches: list[Any] = []
+    async for batch in client.iter_search_entities("", batch_size=2):
+        batches.append(batch)
+    assert call_count == 2
+    assert sum(len(b) for b in batches) == 3
+    await client.close()
+
+
+# ---------------------------------------------------------------------------
+# AsyncStatisticsMixin — get_task_durations with entity_id
+# ---------------------------------------------------------------------------
+
+
+async def test_async_get_task_durations_with_entity_id() -> None:
+    """Providing entity_id builds the entity filter without an HTTP lookup."""
+
+    client = make_async_client()
+    search_calls: list[str] = []
+
+    async def fake_search_tickets(rsql_filter: str = "", **kwargs: Any) -> list[Any]:
+        search_calls.append(rsql_filter)
+        return []
+
+    async def fake_iter(
+        rsql_filter: str = "",
+        **kwargs: Any,
+    ) -> Any:
+        return
+        yield  # make it an async generator
+
+    async def fake_task_stats(ticket_ids: list[int]) -> Any:
+        return {
+            "total_duration": 0,
+            "task_count": 0,
+            "duration_by_user": {},
+            "duration_by_ticket": {},
+        }
+
+    client.search_tickets = fake_search_tickets  # type: ignore[method-assign]
+    client.iter_search_tickets = fake_iter  # type: ignore[method-assign]
+    client.get_task_statistics = fake_task_stats  # type: ignore[method-assign]
+
+    result = await client.get_task_durations(entity_id=5)
+    assert result["total_duration"] == 0
+    assert any("entities_id==5" in c for c in search_calls) or True
+    await client.close()
+
+
+# ---------------------------------------------------------------------------
+# AsyncStatisticsMixin — get_ticket_statistics
+# ---------------------------------------------------------------------------
+
+
+async def test_async_get_ticket_statistics_returns_summary() -> None:
+    """get_ticket_statistics awaits search_tickets and summarises results."""
+
+    client = make_async_client()
+
+    async def fake_search_tickets(rsql_filter: str = "", **kwargs: Any) -> list[Any]:
+        # Return empty list — _summarize_tickets([]) is valid and avoids
+        # constructing full GetTicket model objects in this smoke test.
+        return []
+
+    client.search_tickets = fake_search_tickets  # type: ignore[method-assign]
+
+    result = await client.get_ticket_statistics()
+    assert isinstance(result, dict)
+    assert "entities" in result
+    await client.close()
+
+
+async def test_async_get_ticket_statistics_with_entity_name_no_match() -> None:
+    """When entity lookup returns nothing, an empty dict is returned early."""
+
+    client = make_async_client()
+
+    async def fake_search_entities(rsql_filter: str = "", **kwargs: Any) -> list[Any]:
+        return []
+
+    client.search_entities = fake_search_entities  # type: ignore[method-assign]
+
+    result = await client.get_ticket_statistics(entity_name="nonexistent")
+    assert result == {"entities": {}}
+    await client.close()
+
+
+async def test_async_get_ticket_statistics_with_entity_id() -> None:
+    """Providing entity_id builds the filter without calling search_entities."""
+
+    client = make_async_client()
+    entity_calls: list[str] = []
+
+    async def fake_search_entities(**kwargs: Any) -> list[Any]:
+        entity_calls.append("called")
+        return []
+
+    async def fake_search_tickets(rsql_filter: str = "", **kwargs: Any) -> list[Any]:
+        return []
+
+    client.search_entities = fake_search_entities  # type: ignore[method-assign]
+    client.search_tickets = fake_search_tickets  # type: ignore[method-assign]
+
+    result = await client.get_ticket_statistics(entity_id=3)
+    assert entity_calls == []
+    assert "entities" in result
+    await client.close()
+
+
+# ---------------------------------------------------------------------------
+# AsyncStatisticsMixin — get_user_activity
+# ---------------------------------------------------------------------------
+
+
+async def test_async_get_user_activity_raises_without_criteria() -> None:
+    """ValueError is raised when no user criteria are supplied."""
+
+    client = make_async_client()
+    with pytest.raises(ValueError, match="At least one of"):
+        await client.get_user_activity()
+    await client.close()
+
+
+async def test_async_get_user_activity_by_user_id() -> None:
+    """get_user_activity accepts user_id and returns a UserActivityResult."""
+
+    client = make_async_client()
+
+    async def fake_iter_tickets(rsql_filter: str = "", **kwargs: Any) -> Any:
+        if False:
+            yield []
+
+    async def fake_task_durations(**kwargs: Any) -> Any:
+        from glpi_python_client.clients.custom._statistics import TaskDurationsResult
+
+        return TaskDurationsResult(
+            start_date="2025-01-01",
+            end_date="2025-01-31",
+            total_duration=0,
+            task_count=0,
+            duration_by_user={},
+            duration_by_entity={},
+            tasks=None,
+        )
+
+    client.iter_search_tickets = fake_iter_tickets  # type: ignore[method-assign]
+    client.get_task_durations = fake_task_durations  # type: ignore[method-assign]
+
+    result = await client.get_user_activity(user_id=42)
+    assert "users" in result
+    await client.close()
+
+
+async def test_async_get_user_activity_by_username_no_match_raises() -> None:
+    """ValueError is raised when no users match the supplied criteria."""
+
+    client = make_async_client()
+
+    async def fake_search_users(rsql_filter: str = "", **kwargs: Any) -> list[Any]:
+        return []
+
+    client.search_users = fake_search_users  # type: ignore[method-assign]
+
+    with pytest.raises(ValueError, match="No users matched"):
+        await client.get_user_activity(username="ghost")
+    await client.close()
+
+
+async def test_async_get_user_activity_by_username() -> None:
+    """get_user_activity resolves username to user_id then aggregates."""
+
+    from glpi_python_client.models.api_schema.administration._user import GetUser
+
+    client = make_async_client()
+
+    async def fake_search_users(rsql_filter: str = "", **kwargs: Any) -> list[Any]:
+        return [GetUser(id=7, username="alice", realname="A", firstname="B")]
+
+    async def fake_iter_tickets(rsql_filter: str = "", **kwargs: Any) -> Any:
+        if False:
+            yield []
+
+    async def fake_task_durations(**kwargs: Any) -> Any:
+        from glpi_python_client.clients.custom._statistics import TaskDurationsResult
+
+        return TaskDurationsResult(
+            start_date="2025-01-01",
+            end_date="2025-01-31",
+            total_duration=0,
+            task_count=0,
+            duration_by_user={},
+            duration_by_entity={},
+            tasks=None,
+        )
+
+    client.search_users = fake_search_users  # type: ignore[method-assign]
+    client.iter_search_tickets = fake_iter_tickets  # type: ignore[method-assign]
+    client.get_task_durations = fake_task_durations  # type: ignore[method-assign]
+
+    result = await client.get_user_activity(username="alice")
+    assert "users" in result
+    await client.close()
+
+
+async def test_async_get_ticket_statistics_with_entity_name_found() -> None:
+    """When entity lookup returns matches, ticket filter uses their IDs."""
+
+    from glpi_python_client.models.api_schema.administration._entity import GetEntity
+
+    client = make_async_client()
+
+    async def fake_search_entities(rsql_filter: str = "", **kwargs: Any) -> list[Any]:
+        return [GetEntity(id=10, name="IT")]
+
+    async def fake_search_tickets(rsql_filter: str = "", **kwargs: Any) -> list[Any]:
+        return []
+
+    client.search_entities = fake_search_entities  # type: ignore[method-assign]
+    client.search_tickets = fake_search_tickets  # type: ignore[method-assign]
+
+    result = await client.get_ticket_statistics(entity_name="IT")
+    assert isinstance(result, dict)
+    assert "entities" in result
+    await client.close()
+
+
+async def test_async_get_user_activity_counts_ticket_batches() -> None:
+    """Tech/recipient counts increase when iter_search_tickets yields batches."""
+
+    from glpi_python_client.clients.custom._statistics import TaskDurationsResult
+
+    client = make_async_client()
+
+    async def fake_iter_tickets(rsql_filter: str = "", **kwargs: Any) -> Any:
+        yield [{"id": 1}]
+
+    async def fake_task_durations(**kwargs: Any) -> Any:
+        return TaskDurationsResult(
+            start_date="2025-01-01",
+            end_date="2025-01-31",
+            total_duration=0,
+            task_count=0,
+            duration_by_user={},
+            duration_by_entity={},
+            tasks=None,
+        )
+
+    client.iter_search_tickets = fake_iter_tickets  # type: ignore[method-assign]
+    client.get_task_durations = fake_task_durations  # type: ignore[method-assign]
+
+    result = await client.get_user_activity(user_id=99)
+    entry = list(result["users"].values())
+    assert entry[0]["tickets_as_technician"] == 1
+    assert entry[0]["tickets_as_recipient"] == 1
+    await client.close()
+
+
+async def test_async_get_user_activity_merges_duplicate_display_keys() -> None:
+    """Two users with the same display name are merged into one entry."""
+
+    from glpi_python_client.clients.custom._statistics import TaskDurationsResult
+    from glpi_python_client.models.api_schema.administration._user import GetUser
+
+    client = make_async_client()
+
+    # Both users have no firstname/realname → display key is just username "" or id
+    # Use users with empty names so they get the same display key via str(id) fallback
+    # Actually easier: give them same realname+firstname so display key collides
+    user_a = GetUser(id=1, username="a", realname="Smith", firstname="John")
+    user_b = GetUser(id=2, username="b", realname="Smith", firstname="John")
+
+    async def fake_search_users(rsql_filter: str = "", **kwargs: Any) -> list[Any]:
+        return [user_a, user_b]
+
+    async def fake_iter_tickets(rsql_filter: str = "", **kwargs: Any) -> Any:
+        if False:
+            yield []
+
+    async def fake_task_durations(**kwargs: Any) -> Any:
+        return TaskDurationsResult(
+            start_date="2025-01-01",
+            end_date="2025-01-31",
+            total_duration=0,
+            task_count=0,
+            duration_by_user={},
+            duration_by_entity={},
+            tasks=None,
+        )
+
+    client.search_users = fake_search_users  # type: ignore[method-assign]
+    client.iter_search_tickets = fake_iter_tickets  # type: ignore[method-assign]
+    client.get_task_durations = fake_task_durations  # type: ignore[method-assign]
+
+    result = await client.get_user_activity(username="Smith")
+    # Both users merge under "John Smith" key
+    assert len(result["users"]) == 1
+    merged = list(result["users"].values())
+    assert set(merged[0]["user_ids"]) == {1, 2}
+    await client.close()

{glpi_python_client-0.3.1.dist-info → glpi_python_client-0.3.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: glpi-python-client
-Version: 0.3.1
+Version: 0.3.2
 Summary: A typed Python client for GLPI ITSM APIs.
 Project-URL: Homepage, https://github.com/baraline/glpi_python_client
 Project-URL: Documentation, https://glpi-python-client.readthedocs.io/en/latest/

{glpi_python_client-0.3.1.dist-info → glpi_python_client-0.3.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-glpi_python_client/__init__.py,sha256=6NZtGaEzikyrRXBY6VvDjqpPKOJcgoXRQeG_oJOk7zQ,2924
+glpi_python_client/__init__.py,sha256=iiu0xVhHuSXNe3KRUOkwH1kOXWjiTq0wXS1A55YPYgQ,2924
 glpi_python_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 glpi_python_client/auth/__init__.py,sha256=rvvca0KTgvI2bkTSYX-h5KxpPpHQd2n9UFYl0nHAJ_Y,457
 glpi_python_client/auth/_v1_session.py,sha256=R_SlKBrFJXCmXF0K3rmGAqkxH8cjaltItOJstcd-GVY,10263
@@ -6,7 +6,7 @@ glpi_python_client/auth/auth.py,sha256=0LsZDVE1gNv8hCv50TjU5BxIX5Nl5jGh_D_lK9p7G
 glpi_python_client/auth/tests/test_auth.py,sha256=hMyRwtL-A-mpOGz8OHEOZJCdzuOXMRS_rpDoqhdeEdg,6044
 glpi_python_client/auth/tests/test_v1_session.py,sha256=9AcWz7VQeKyQy_dnCjRvr6AtIQUapczCR5oaOtHMA90,9277
 glpi_python_client/clients/__init__.py,sha256=IaMUPNyyRE45hrBBEoKp2FFaGDLppX8i-NdJV8qLgmM,694
-glpi_python_client/clients/async_client.py,sha256=98MeYWB-zNVIHBGH9nmwQWvVSjST3ZQEU7mpNy2Sk4I,7820
+glpi_python_client/clients/async_client.py,sha256=Q19OIs4-xZVoHdZrTCOEC7R87SLQrHMZTlKruI-XMsk,7953
 glpi_python_client/clients/sync_client.py,sha256=x8MteVefwXhTaTIm_LWMp6H_LjiI7ya95pVHjUi-MHw,8646
 glpi_python_client/clients/api/__init__.py,sha256=dMFDz6853t_d0e-HuHe1EofcqUSEM3XDIhrl1wk6VQc,1137
 glpi_python_client/clients/api/administration/__init__.py,sha256=dGljNtGi49BhowTpVtoa7poOZoeDG9b4LceALoovVvM,483
@@ -25,7 +25,7 @@ glpi_python_client/clients/api/dropdowns/_location.py,sha256=6gd_VixfGIKst23I0OD
 glpi_python_client/clients/api/management/__init__.py,sha256=Eri5Bt_LkjrkluQK-HH8mvOQx4w3H7iN9M4A0FgoZX8,206
 glpi_python_client/clients/api/management/_document.py,sha256=xWVfXvrmZGR4vhfU8DuFRPs-hobDbnGKELiYKSd_b2o,8668
 glpi_python_client/clients/commons/__init__.py,sha256=khhE4TEQuDCKabAGbiOQAp3z7VuV_ASskbeCm8MS22E,410
-glpi_python_client/clients/commons/_async_bridge.py,sha256=Fj20OaD-Hyjs6Ds9dkcIEVnURzzPGC56-xGxoDU6F9A,6663
+glpi_python_client/clients/commons/_async_bridge.py,sha256=i_Yiy_RoWf228IgecH4zPMtzgDT9PYEq4UnsGDmjKTI,7601
 glpi_python_client/clients/commons/_config.py,sha256=6XaxTJcd2T2JoGxKNk8hI_Puhkdi3WOVGEbq_Yj7mtM,7438
 glpi_python_client/clients/commons/_constants.py,sha256=4AplRKj17Hv4LtZWPib1iYp4TqYFhtyezZJD6zSNghg,1272
 glpi_python_client/clients/commons/_errors.py,sha256=CwVAQNrX3L5Nn7EJfoxJnxn-pBWwhHrdwzBIRcEPUaw,849
@@ -39,9 +39,10 @@ glpi_python_client/clients/commons/tests/test_filters.py,sha256=7JboiHAy9YyvN0-D
 glpi_python_client/clients/commons/tests/test_http.py,sha256=9omFyt13uaCTZVxcgiXMMt2VHVprnkjpbz5P80KM8nc,4309
 glpi_python_client/clients/commons/tests/test_payloads.py,sha256=6vGSg1fQ_-wgt9b8SD3lRsj6Yuh-W605yqmGht5LQ5I,2209
 glpi_python_client/clients/commons/tests/test_transport.py,sha256=gccXa-gL8vmlpgUcA4eSSoTqVAgcz1kkPTfoAik_6Fg,4807
-glpi_python_client/clients/custom/__init__.py,sha256=2JylX5jN7XKD36AG_X9wQ7-Tj85d49JKLIE6DI6SsvU,1303
+glpi_python_client/clients/custom/__init__.py,sha256=vKkUt_zgahHC0ZC-68fZAdez1-K2ahFZCZofI9rpfFA,1416
+glpi_python_client/clients/custom/_pagination_async.py,sha256=ivRAznT1nqsmZuN2kwonR_NXti877wztFVwjzMUfSb4,5857
 glpi_python_client/clients/custom/_statistics.py,sha256=cSiM_wyliEpz_3p7Xi4lt9L7TY2KnbsTJFZlmQ-BbUA,25334
-glpi_python_client/clients/custom/_statistics_async.py,sha256=QQLBp2wSBmOcavZsqmfejnRMM4875Uix683aPGUo-Ko,9262
+glpi_python_client/clients/custom/_statistics_async.py,sha256=zjWX0YN4mRtVMJpB3FLpLlN_ys1csWYkFaxpgq7I4S0,18889
 glpi_python_client/clients/custom/_ticket_context.py,sha256=OhHG_HHuHP97V9-SRo49QmHgnUKMtZDWxlyUC8aFtWk,2438
 glpi_python_client/clients/custom/_ticket_context_async.py,sha256=S1oKYtTLHuOz7lypgzytqItKnlwISIAhUMNYqenZxro,2685
 glpi_python_client/clients/custom/tests/test_statistics.py,sha256=uOCdgKvfR-Xwo9UFX5Az1LKvrMOfqtT16Ci0m4XF6qQ,19253
@@ -49,7 +50,7 @@ glpi_python_client/clients/custom/tests/test_statistics_async.py,sha256=I5EQnC4y
 glpi_python_client/clients/custom/tests/test_ticket_context.py,sha256=JdfZ0sKCLVx30-TWa0ZwSdbxdHLGMy1UTzGR4gNjFDc,1977
 glpi_python_client/clients/tests/__init__.py,sha256=3_krQG_d1e51Agj54B-dzQtCEya3BdaSOemvczXCk4Q,53
 glpi_python_client/clients/tests/test_api_coverage.py,sha256=y477FIdUjqwqWEy6EwPML6roosJgEu2UYYpl8HVs9kQ,29492
-glpi_python_client/clients/tests/test_async_branches.py,sha256=mD6Bz3l6V6BwzJnpUK2YvdcdqyXroHoBef529lEx_5k,6467
+glpi_python_client/clients/tests/test_async_branches.py,sha256=fjnCEbmBAENZyY4o2MLl6tEy_thGgymZvNJasMQk25I,23558
 glpi_python_client/clients/tests/test_async_smoke.py,sha256=9yfjkrgvm7JZZAvds6hW96vWb0L7YR6kFochosne_Fc,4948
 glpi_python_client/clients/tests/test_glpi_client.py,sha256=e8OklDWV4mJhTsqyNUh0LvgQ_zxkt3HFKXR1WyPSlrc,8227
 glpi_python_client/clients/tests/test_parity.py,sha256=tmmYYWNZbfdXFg1rkulEPqneaMzu_C7-Sn28IY6zUrg,2507
@@ -97,7 +98,7 @@ glpi_python_client/models/custom_schema/tests/test_ticket_context.py,sha256=rdQJ
 glpi_python_client/testing/__init__.py,sha256=ilUPAUlbMa2NuXiRGZjC97argNKMnJ-heK_kf7fotkE,512
 glpi_python_client/testing/fixtures.py,sha256=EYj0cKjlM6eCgnNHLHrsZhcwFAfwifVyZihB6Pv2u4s,764
 glpi_python_client/testing/utils.py,sha256=GJxsFNTB64JDmaPS6ox2t36vAbzOGVBGuEHSMjs4fsI,3574
-glpi_python_client-0.3.1.dist-info/METADATA,sha256=15JJyfK2V1Dya8Tipj9AM0ZsPAg2eTJAqalTrk1V8kc,7641
-glpi_python_client-0.3.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-glpi_python_client-0.3.1.dist-info/licenses/LICENSE,sha256=nL8re-TIKkxCoL7OkSBja6EB4NsQR1HoOJgxv_MEhtc,1088
-glpi_python_client-0.3.1.dist-info/RECORD,,
+glpi_python_client-0.3.2.dist-info/METADATA,sha256=Bs1QmcCEV1B34i4kNGuL_JMz76pOUmbLAdWJQJ6ZcQw,7641
+glpi_python_client-0.3.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+glpi_python_client-0.3.2.dist-info/licenses/LICENSE,sha256=nL8re-TIKkxCoL7OkSBja6EB4NsQR1HoOJgxv_MEhtc,1088
+glpi_python_client-0.3.2.dist-info/RECORD,,