glpi-python-client 0.3.0__tar.gz → 0.3.2__tar.gz

glpi_python_client-0.3.2/.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+default_install_hook_types: [pre-commit, pre-push]
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.13
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy (strict)
+        entry: python -m mypy glpi_python_client
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: pytest-coverage
+        name: pytest with coverage (>=95%)
+        entry: python -m pytest -m "not integration" --cov=glpi_python_client --cov-fail-under=95 -q
+        language: system
+        pass_filenames: false
+        stages: [pre-push]
+
+      - id: sphinx-build
+        name: sphinx build (warnings as errors)
+        entry: python -m sphinx -b html -W --keep-going docs docs/_build/html_check
+        language: system
+        pass_filenames: false
+        stages: [pre-push]

{glpi_python_client-0.3.0 → glpi_python_client-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: glpi-python-client
-Version: 0.3.0
+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.0 → glpi_python_client-0.3.2}/docs/user_guide.rst

@@ -179,13 +179,51 @@ fan-outs cannot race the auth manager, while the HTTP requests
 themselves execute outside the lock through the thread-safe
 :class:`requests.Session`.
 
-A small number of helpers exist in async-only variants because they
-need real concurrency:
+A number of helpers ship with hand-written async overrides rather than
+relying solely on the bridge. There are two reasons a method needs its
+own async variant:
+
+1. **Concurrency** — the method benefits from fanning multiple GLPI
+   calls out concurrently with :func:`asyncio.gather`.
+2. **Internal self-calls** — the method calls another public method
+   through ``self`` (e.g. ``self.search_tickets(...)`` inside a
+   pagination loop). When the bridge runs the synchronous body in a
+   worker thread, ``self.method`` resolves to the bridge-wrapped
+   *coroutine*, which returns a coroutine object instead of data when
+   called without ``await``. The async override replaces the body so
+   every internal call is properly awaited on the event loop.
+
+Helpers with async overrides:
+
+* :meth:`AsyncGlpiClient.get_ticket_context` — fans the five underlying
+  GLPI calls out concurrently (reason: concurrency).
+* :meth:`AsyncGlpiClient.get_task_statistics` — fans the per-ticket
+  task-list calls out concurrently (reason: concurrency).
+* :meth:`AsyncGlpiClient.get_task_durations` — fans the per-ticket task
+  fetches out concurrently when ``return_task_details=True``, and
+  properly awaits ``iter_search_tickets`` and ``search_entities``
+  internally (reasons: concurrency + internal self-calls).
+* :meth:`AsyncGlpiClient.get_ticket_statistics` — properly awaits
+  ``search_tickets`` and ``search_entities`` internally (reason:
+  internal self-calls).
+* :meth:`AsyncGlpiClient.get_user_activity` — properly awaits
+  ``search_users``, ``iter_search_tickets``, and ``get_task_durations``
+  internally (reason: internal self-calls).
+* ``iter_search_tickets``, ``iter_search_users``,
+  ``iter_search_entities`` — each pagination loop body calls
+  ``self.search_*(...)``; the async variants are native async generators
+  that ``await`` those calls directly (reason: internal self-calls).
+
+Pagination helpers (``iter_search_tickets``, ``iter_search_users``,
+``iter_search_entities``) are exposed as **async generators** on the
+async client. Iterate them with ``async for`` to walk every page
+without blocking the event loop:
 
-* :meth:`AsyncGlpiClient.get_ticket_context` fans the five underlying
-  GLPI calls out concurrently with :func:`asyncio.gather`.
-* :meth:`AsyncGlpiClient.get_task_statistics` fans the per-ticket task
-  list calls out concurrently with :func:`asyncio.gather`.
+.. code-block:: python
+
+   async for batch in client.iter_search_tickets("status==1", batch_size=200):
+       for ticket in batch:
+           ...
 
 The synchronous versions of the same helpers issue the calls
 sequentially.
@@ -710,25 +748,79 @@ Example — description and timeline only, no metadata fields:
 Reporting helpers
 ~~~~~~~~~~~~~~~~~
 
-The custom statistics mixin exposes two helpers that aggregate the
+The custom statistics mixin exposes several helpers that aggregate the
 ticket and ticket-task records returned by the contract-aligned mixins.
-Both return plain Python dictionaries so they can be serialised or
+They all return plain Python dictionaries so they can be serialised or
 forwarded as-is.
 
+Streaming pagination with ``iter_search_*``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``search_*`` helpers return one page at a time and require the
+caller to manage the ``start`` cursor. The companion ``iter_search_*``
+generators handle pagination automatically by yielding successive
+batches until the API returns fewer rows than the requested
+``batch_size`` (the natural end-of-stream signal):
+
+* :meth:`GlpiClient.iter_search_tickets`
+* :meth:`GlpiClient.iter_search_users`
+* :meth:`GlpiClient.iter_search_entities`
+
+.. code-block:: python
+
+   # Walk every "open" ticket without loading the full result set in memory.
+   total = 0
+   for batch in client.iter_search_tickets("status==1", batch_size=200):
+       total += len(batch)
+       for ticket in batch:
+           print(ticket.id, ticket.name)
+   print(f"processed {total} tickets")
+
+On the asynchronous client the same helpers are exposed as **async
+generators** through the bridge, so each ``next()`` call runs off the
+event loop and the consumer uses ``async for``:
+
+.. code-block:: python
+
+   async for batch in async_client.iter_search_users("", batch_size=100):
+       for user in batch:
+           print(user.id, user.username)
+
 ``get_ticket_statistics``
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Counts tickets created within an ISO date window and groups them by
-entity, status, priority, and type.
+entity, status, priority, and type. Optional filters restrict the
+result set on the server side:
+
+* ``entity_id`` — restrict to a single entity by numeric identifier.
+* ``entity_name`` — substring match against the entity ``name`` column;
+  the helper resolves matching IDs via ``search_entities`` and ORs
+  them together. Ignored when ``entity_id`` is provided.
+* ``extra_filter`` — raw RSQL fragment AND-joined with the date window.
 
 .. code-block:: python
 
+   # Tickets created in January 2026 on a specific entity, restricted to
+   # priority "HIGH" (5) via an extra raw RSQL fragment.
    stats = client.get_ticket_statistics(
        start_date="2026-01-01",
        end_date="2026-01-31",
+       entity_id=3,
+       extra_filter="priority==5",
    )
    print(stats)
 
+   # Resolve the entity by (partial) name instead of by ID:
+   stats = client.get_ticket_statistics(
+       start_date="2026-01-01",
+       end_date="2026-01-31",
+       entity_name="Helpdesk",
+   )
+
+When ``entity_name`` matches no entity the helper short-circuits and
+returns ``{"entities": {}}`` without issuing any ticket search.
+
 Returned shape (the outer key is always ``"entities"``; entity keys are
 the GLPI numeric identifier as a string, ``"unknown"`` when missing)::
 
@@ -790,6 +882,115 @@ needed (for example
 ``client.get_user(22)`` to turn user key ``"22"`` into a full
 :class:`GetUser` model).
 
+``get_task_durations``
+^^^^^^^^^^^^^^^^^^^^^^
+
+Aggregates task durations over a date window with rich server-side
+filters and an optional per-task detail list. Internally the helper
+iterates :meth:`iter_search_tickets` to collect every matching ticket,
+then computes per-user and per-entity totals.
+
+Available filters:
+
+* ``start_date`` / ``end_date`` / ``default_days`` — ISO ``YYYY-MM-DD``
+  date window; ``default_days`` is used when ``start_date`` is omitted.
+* ``entity_id`` — restrict to a single entity by identifier.
+* ``entity_name`` — substring match resolved through ``search_entities``;
+  ignored when ``entity_id`` is given.
+* ``user_id`` — tickets where the user is **either** assignee or
+  requester (OR semantics).
+* ``user_editor_id`` — tickets last updated by this user.
+* ``user_recipient_id`` — tickets where this user is the requester.
+* ``extra_filter`` — raw RSQL fragment AND-joined with everything else.
+* ``return_task_details`` — when ``True``, fetch every non-zero ticket's
+  task list and include them as ``tasks`` in the result.
+
+.. code-block:: python
+
+   # Sum durations for a tech on a specific entity over the last 30 days.
+   summary = client.get_task_durations(
+       entity_id=3,
+       user_id=42,
+   )
+   print(summary["total_duration"], summary["task_count"])
+   print(summary["duration_by_entity"])  # {"3": 7200}
+
+   # Same query but ask for the per-task breakdown.
+   detailed = client.get_task_durations(
+       entity_id=3,
+       user_id=42,
+       return_task_details=True,
+   )
+   for task in detailed["tasks"] or []:
+       print(task["task_id"], task["ticket_id"], task["duration"])
+
+Returned shape::
+
+   {
+       "start_date": "2026-01-01",
+       "end_date": "2026-01-31",
+       "total_duration": 7200,
+       "task_count": 4,
+       "duration_by_user": {"42": 7200},
+       "duration_by_entity": {"3": 7200},
+       "tasks": None,  # or a list[dict] when return_task_details=True
+   }
+
+On the async client the same method is overridden to run the per-ticket
+task fetches concurrently with :func:`asyncio.gather` when
+``return_task_details=True``.
+
+``get_user_activity``
+^^^^^^^^^^^^^^^^^^^^^
+
+Aggregates per-user activity over a date window: tickets where the
+user appears as technician (``users_id_assign``), tickets where the
+user appears as requester (``users_id_requester``), and the user's
+task duration totals. Multiple users that resolve to the same display
+key (``"<firstname> <realname>"``) are merged into a single bucket.
+
+The helper raises ``ValueError`` when no identifier is supplied or
+when the search criteria match no users in the directory.
+
+.. code-block:: python
+
+   # Activity for a single user identified by username (substring match).
+   report = client.get_user_activity(
+       username="alice",
+       start_date="2026-01-01",
+       end_date="2026-01-31",
+   )
+   for display_name, data in report["users"].items():
+       print(
+           display_name,
+           data["tickets_as_technician"],
+           data["tickets_as_recipient"],
+           data["task_durations"]["total_duration"],
+       )
+
+   # Activity for every user whose last name contains "Smith".
+   report = client.get_user_activity(realname="Smith", default_days=90)
+
+Returned shape::
+
+   {
+       "users": {
+           "Alice Smith": {
+               "user_ids": [42],
+               "tickets_as_technician": 7,
+               "tickets_as_recipient": 2,
+               "task_durations": {
+                   "start_date": "2026-01-01",
+                   "end_date": "2026-01-31",
+                   "total_duration": 7200,
+                   "task_count": 4,
+                   "duration_by_user": {"42": 7200},
+                   "duration_by_entity": {"3": 7200},
+               },
+           }
+       }
+   }
+
 .. _end-to-end-examples:
 
 6. End-to-end examples

{glpi_python_client-0.3.0 → glpi_python_client-0.3.2}/glpi_python_client/__init__.py

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

{glpi_python_client-0.3.0 → glpi_python_client-0.3.2}/glpi_python_client/clients/api/administration/_entity.py

@@ -7,6 +7,8 @@ client's ``GLPI-Entity`` header so cross-entity lookups remain possible.
 
 from __future__ import annotations
 
+from collections.abc import Iterator
+
 from glpi_python_client.clients.commons._constants import ENTITY_ENDPOINT, GlpiId
 from glpi_python_client.clients.commons._transport import TransportMixin
 from glpi_python_client.models.api_schema.administration._entity import (
@@ -54,6 +56,48 @@ class EntityMixin(TransportMixin):
             ENTITY_ENDPOINT, GetEntity, params=params, skip_entity=True
         )
 
+    def iter_search_entities(
+        self,
+        rsql_filter: str = "",
+        *,
+        batch_size: int = 50,
+    ) -> Iterator[list[GetEntity]]:
+        """Yield successive pages of GLPI entities until exhausted.
+
+        The generator drives pagination automatically by advancing the
+        ``start`` offset after each batch. Iteration stops when the server
+        returns fewer items than ``batch_size``, which signals the last page.
+        Entity calls bypass the ``GLPI-Entity`` header so cross-entity
+        lookups remain possible.
+
+        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 = self.search_entities(
+                rsql_filter,
+                limit=batch_size,
+                start=start,
+            )
+            if batch:
+                yield batch
+            if len(batch) < batch_size:
+                break
+            start += batch_size
+
     def get_entity(self, entity_id: GlpiId) -> GetEntity:
         """Fetch one GLPI entity by identifier.
 

{glpi_python_client-0.3.0 → glpi_python_client-0.3.2}/glpi_python_client/clients/api/administration/_user.py

@@ -8,6 +8,8 @@ the Synchronous transport mixin for HTTP dispatch.
 
 from __future__ import annotations
 
+from collections.abc import Iterator
+
 from glpi_python_client.clients.commons._constants import USER_ENDPOINT, GlpiId
 from glpi_python_client.clients.commons._transport import TransportMixin
 from glpi_python_client.models.api_schema.administration._user import (
@@ -63,6 +65,51 @@ class UserMixin(TransportMixin):
             USER_ENDPOINT, GetUser, params=params, skip_entity=skip_entity
         )
 
+    def iter_search_users(
+        self,
+        rsql_filter: str = "",
+        *,
+        batch_size: int = 50,
+        skip_entity: bool = False,
+    ) -> Iterator[list[GetUser]]:
+        """Yield successive pages of GLPI users until exhausted.
+
+        The generator drives pagination automatically by advancing the
+        ``start`` offset after each batch. Iteration stops when the server
+        returns fewer items than ``batch_size``, which signals the last page.
+
+        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 = self.search_users(
+                rsql_filter,
+                limit=batch_size,
+                start=start,
+                skip_entity=skip_entity,
+            )
+            if batch:
+                yield batch
+            if len(batch) < batch_size:
+                break
+            start += batch_size
+
     def get_user(self, user_id: GlpiId) -> GetUser:
         """Fetch one GLPI user by identifier.
 

{glpi_python_client-0.3.0 → glpi_python_client-0.3.2}/glpi_python_client/clients/api/assistance/_ticket.py

@@ -6,6 +6,8 @@ GLPI ticket resource using the ``api_schema`` Pydantic models.
 
 from __future__ import annotations
 
+from collections.abc import Iterator
+
 from glpi_python_client.clients.commons._constants import TICKET_ENDPOINT, GlpiId
 from glpi_python_client.clients.commons._transport import TransportMixin
 from glpi_python_client.models.api_schema.assistance._ticket import (
@@ -68,6 +70,56 @@ class TicketMixin(TransportMixin):
             params["fields"] = ",".join(fields)
         return self._resource_list(TICKET_ENDPOINT, GetTicket, params=params)
 
+    def iter_search_tickets(
+        self,
+        rsql_filter: str = "",
+        *,
+        batch_size: int = 50,
+        sort: str | None = None,
+        fields: tuple[str, ...] = (),
+    ) -> Iterator[list[GetTicket]]:
+        """Yield successive pages of GLPI tickets until exhausted.
+
+        The generator drives pagination automatically by advancing the
+        ``start`` offset after each batch. Iteration stops when the server
+        returns fewer items than ``batch_size``, which signals the last page.
+
+        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). Acts as
+            the ``limit`` parameter on each underlying
+            :meth:`search_tickets` call.
+        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 = self.search_tickets(
+                rsql_filter,
+                limit=batch_size,
+                start=start,
+                sort=sort,
+                fields=fields,
+            )
+            if batch:
+                yield batch
+            if len(batch) < batch_size:
+                break
+            start += batch_size
+
     def get_ticket(self, ticket_id: GlpiId) -> GetTicket:
         """Fetch one GLPI ticket by identifier.
 

{glpi_python_client-0.3.0 → glpi_python_client-0.3.2}/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-0.3.0 → glpi_python_client-0.3.2}/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
@@ -33,6 +50,19 @@ from collections.abc import Callable
 from concurrent.futures import Executor
 from typing import Any
 
+# Sentinel used by the async-generator bridge to signal exhaustion without
+# propagating StopIteration through a coroutine (which PEP 479 forbids).
+_STOPPED: object = object()
+
+
+def _next_or_stopped(gen: Any) -> Any:
+    """Return the next item from *gen* or ``_STOPPED`` when exhausted."""
+
+    try:
+        return next(gen)
+    except StopIteration:
+        return _STOPPED
+
 
 class AsyncBridge:
     """Base class that converts inherited sync methods into coroutines.
@@ -78,14 +108,22 @@ class AsyncBridge:
                     continue
                 if not callable(member) or inspect.iscoroutinefunction(member):
                     continue
+                if inspect.isasyncgenfunction(member):
+                    continue
                 # Skip if the subclass already overrides the method with
-                # a coroutine function (for example async fan-outs).
+                # a coroutine function or async generator (for example async fan-outs).
                 existing = getattr(cls, name, None)
-                if existing is not None and inspect.iscoroutinefunction(existing):
+                if existing is not None and (
+                    inspect.iscoroutinefunction(existing)
+                    or inspect.isasyncgenfunction(existing)
+                ):
                     seen.add(name)
                     continue
                 seen.add(name)
-                setattr(cls, name, _make_async_wrapper(member))
+                if inspect.isgeneratorfunction(member):
+                    setattr(cls, name, _make_async_generator_wrapper(member))
+                else:
+                    setattr(cls, name, _make_async_wrapper(member))
 
 
 def _make_async_wrapper(sync_func: Callable[..., Any]) -> Callable[..., Any]:
@@ -115,4 +153,39 @@ def _make_async_wrapper(sync_func: Callable[..., Any]) -> Callable[..., Any]:
     return wrapper
 
 
+def _make_async_generator_wrapper(sync_func: Callable[..., Any]) -> Callable[..., Any]:
+    """Return an async generator wrapper for a synchronous generator function.
+
+    Each call to ``next()`` on the underlying sync generator is dispatched
+    to a worker thread so that the blocking HTTP call inside the generator
+    body does not block the event loop.
+
+    Parameters
+    ----------
+    sync_func : Callable[..., Any]
+        Synchronous generator function inherited from a sync mixin.
+
+    Returns
+    -------
+    Callable[..., Any]
+        Async generator function that yields the same items as the
+        synchronous generator, one batch at a time, off the event loop.
+    """
+
+    @functools.wraps(sync_func)
+    async def wrapper(self: AsyncBridge, *args: Any, **kwargs: Any) -> Any:
+        gen = sync_func(self, *args, **kwargs)
+        while True:
+            if self._executor is not None:
+                loop = asyncio.get_running_loop()
+                item = await loop.run_in_executor(self._executor, _next_or_stopped, gen)
+            else:
+                item = await asyncio.to_thread(_next_or_stopped, gen)
+            if item is _STOPPED:
+                return
+            yield item
+
+    return wrapper
+
+
 __all__ = ["AsyncBridge"]

{glpi_python_client-0.3.0 → glpi_python_client-0.3.2}/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",