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

glpi_python_client/__init__.py

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

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/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/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/clients/commons/_async_bridge.py

@@ -33,6 +33,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 +91,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 +136,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"]