glpi-python-client 0.4.2__py3-none-any.whl → 0.4.3__py3-none-any.whl

glpi_python_client/__init__.py

@@ -103,8 +103,13 @@ from glpi_python_client.models import (
     PostUser,
     TicketMarkdownOptions,
 )
+from glpi_python_client.rsql import (
+    changed_since,
+    created_between,
+    date_window,
+)
 
-__version__ = "0.4.2"
+__version__ = "0.4.3"
 
 __all__ = [
     "AsyncGlpiClient",
@@ -190,4 +195,7 @@ __all__ = [
     "PostUser",
     "TicketMarkdownOptions",
     "__version__",
+    "changed_since",
+    "created_between",
+    "date_window",
 ]

glpi_python_client/_async/clients/_base_client.py

@@ -25,10 +25,12 @@ from glpi_python_client._async._concurrency import Lock
 from glpi_python_client._async.clients.commons._config import (
     build_client_env_config,
     build_client_resources,
+    resolve_server_timezone,
 )
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
+    from datetime import tzinfo
 
 logger = logging.getLogger(__name__)
 
@@ -45,6 +47,7 @@ class _BaseGlpiClient:
         self,
         *,
         glpi_api_url: str,
+        server_timezone: str | tzinfo,
         client_id: str | None = None,
         client_secret: str | None = None,
         username: str | None = None,
@@ -66,6 +69,25 @@ class _BaseGlpiClient:
         glpi_api_url : str
             Base URL of the GLPI v2 REST API, e.g.
             ``https://glpi.example.com/api.php/v2``.
+        server_timezone : str | tzinfo
+            IANA name of the timezone the GLPI server runs in (e.g.
+            ``"Europe/Paris"``), or a ``tzinfo``. **Required**: GLPI does
+            not advertise it, and it governs both directions of every
+            timestamp the client exchanges.
+
+            Reading, it interprets the timestamps the server sends without
+            an offset. Writing, it is what makes an aware ``datetime``
+            arrive as the moment it names: GLPI reads the naive prefix of a
+            timestamp and discards the offset, so the value has to be
+            converted onto the server's clock before it is sent. Measured on
+            a live instance, offsets from ``-08:00`` to ``+14:00`` written
+            to one field all stored the same wall clock.
+
+            There is no default because every candidate is wrong somewhere
+            -- guessing UTC against a Europe/Paris instance shifts those
+            timestamps by an hour or two and never raises. Prefer a name
+            over a fixed offset: a name follows DST, and one instance emits
+            both ``+01:00`` and ``+02:00``.
         client_id : str | None, optional
             OAuth client identifier used to obtain access tokens.
         client_secret : str | None, optional
@@ -103,6 +125,7 @@ class _BaseGlpiClient:
             missing OAuth credentials together with no v1 fallback).
         """
 
+        self.server_timezone = resolve_server_timezone(server_timezone)
         resources = build_client_resources(
             glpi_api_url=glpi_api_url,
             client_name=type(self).__name__,
@@ -142,7 +165,8 @@ class _BaseGlpiClient:
         ``GLPI_USERNAME``, ``GLPI_PASSWORD``, ``GLPI_VERIFY_SSL``,
         ``GLPI_V1_BASE_URL``, ``GLPI_V1_USER_TOKEN``, ``GLPI_V1_APP_TOKEN``,
         ``GLPI_ENTITY``, ``GLPI_PROFILE``, ``GLPI_ENTITY_RECURSIVE``,
-        ``GLPI_LANGUAGE``, ``GLPI_AUTH_TOKEN_REFRESH``).
+        ``GLPI_LANGUAGE``, ``GLPI_AUTH_TOKEN_REFRESH``,
+        ``GLPI_SERVER_TIMEZONE``).
 
         Parameters
         ----------

glpi_python_client/_async/clients/api/administration/_user.py

@@ -12,6 +12,7 @@ from collections.abc import AsyncIterator
 
 from glpi_python_client._async.clients.commons._constants import USER_ENDPOINT, GlpiId
 from glpi_python_client._async.clients.commons._transport import TransportMixin
+from glpi_python_client._errors import GlpiValidationError
 from glpi_python_client.models.api_schema.administration._user import (
     DeleteUser,
     GetUser,
@@ -110,6 +111,81 @@ class UserMixin(TransportMixin):
                 break
             start += batch_size
 
+    async def find_user_by_email(
+        self,
+        email: str,
+        *,
+        rsql_filter: str = "",
+        batch_size: int = 100,
+        skip_entity: bool = True,
+    ) -> GetUser | None:
+        """Return the first user holding ``email``, or ``None``.
+
+        **This scans.** GLPI exposes e-mail addresses as ``User.emails``, a
+        nested *array*, and the v2 filter engine cannot join a nested array
+        -- the structurally identical ``Ticket.team`` answers HTTP 500 for
+        its declared subfields and is silently ignored for every other
+        spelling. So there is no server-side e-mail filter to use, and the
+        addresses have to be compared client-side.
+
+        Nothing about that is cheap: the scan costs one request per
+        ``batch_size`` users until it matches, so it is meant for
+        occasional resolution, not for a per-request lookup. Narrow it with
+        ``rsql_filter`` when you can (``"is_active==true"`` is the usual
+        one), and cache the resulting id rather than calling this again.
+
+        A server-side fast path is deliberately *not* attempted. GLPI v2
+        ignores a filter field it does not recognise and answers with the
+        whole unfiltered table, so a guessed e-mail filter would not fail
+        -- it would return a plausible non-empty page whose first row is
+        the wrong person. Guessing is the one thing this helper exists to
+        stop each caller doing separately.
+
+        Parameters
+        ----------
+        email : str
+            Address to look for. Compared case-insensitively after
+            trimming surrounding whitespace, the way mail systems treat it.
+        rsql_filter : str, optional
+            Raw RSQL filter narrowing the population scanned. Empty by
+            default, which scans every visible user.
+        batch_size : int, optional
+            Users fetched per request while scanning (defaults to 100).
+        skip_entity : bool, optional
+            When ``True`` (the default) the ``GLPI-Entity`` header is
+            omitted so the scan spans every entity the caller can see. A
+            user whose account lives outside the client's configured entity
+            is invisible otherwise, and the helper would answer ``None``
+            for somebody who exists.
+
+        Returns
+        -------
+        GetUser | None
+            The first user with a matching address, or ``None`` when the
+            scanned population holds none.
+
+        Raises
+        ------
+        GlpiValidationError
+            If ``email`` is blank -- which would otherwise scan the whole
+            directory and match nothing.
+        """
+
+        needle = email.strip().casefold()
+        if not needle:
+            raise GlpiValidationError("find_user_by_email requires a non-empty address")
+
+        async for batch in self.iter_search_users(
+            rsql_filter,
+            batch_size=batch_size,
+            skip_entity=skip_entity,
+        ):
+            for user in batch:
+                for entry in user.emails or ():
+                    if entry.email and entry.email.strip().casefold() == needle:
+                        return user
+        return None
+
     async def get_user(self, user_id: GlpiId) -> GetUser:
         """Fetch one GLPI user by identifier.
 

glpi_python_client/_async/clients/api/assistance/_team.py

@@ -15,7 +15,6 @@ from glpi_python_client._async.clients.commons._constants import (
     GlpiId,
 )
 from glpi_python_client._async.clients.commons._http import ensure_response_status
-from glpi_python_client._async.clients.commons._payloads import model_to_payload
 from glpi_python_client._async.clients.commons._transport import TransportMixin
 from glpi_python_client.models.api_schema.assistance._team import (
     GetTeamMember,
@@ -79,7 +78,7 @@ class TeamMemberMixin(TransportMixin):
         """
 
         endpoint = f"{TICKET_ENDPOINT}/{ticket_id}/{TEAM_MEMBER_SUFFIX}"
-        response = await self._post_request(endpoint, model_to_payload(member))
+        response = await self._post_request(endpoint, self._body(member))
         ensure_response_status(
             response,
             success_statuses=(200, 201),
@@ -114,7 +113,7 @@ class TeamMemberMixin(TransportMixin):
             f"{TICKET_ENDPOINT}/{ticket_id}/{TEAM_MEMBER_SUFFIX}",
             failure_message=f"Failed to remove team member on ticket {ticket_id}",
             log_message=f"GLPI API removed team member on ticket {ticket_id}",
-            body=model_to_payload(member),
+            body=self._body(member),
         )
 
 

glpi_python_client/_async/clients/api/assistance/_ticket.py

@@ -49,7 +49,11 @@ class TicketMixin(TransportMixin):
         start : int, optional
             Zero-based offset of the first record returned.
         sort : str | None, optional
-            ``sort`` query parameter forwarded as-is, e.g. ``"date_mod desc"``.
+            ``sort`` query parameter, spelled ``field`` or ``field:direction``
+            (e.g. ``"date_mod:desc"``). Measured against GLPI 11: a space
+            before the direction answers **HTTP 400** ("Invalid property for
+            sorting"), a bare ``field`` sorts *ascending*, and a separate
+            ``order`` parameter is ignored.
         fields : tuple[str, ...], optional
             Restricted set of contract field names to request. Empty
             tuple lets the GLPI server pick its default field set.
@@ -94,7 +98,9 @@ class TicketMixin(TransportMixin):
             the ``limit`` parameter on each underlying
             :meth:`search_tickets` call.
         sort : str | None, optional
-            ``sort`` query parameter forwarded as-is to each page request.
+            ``sort`` query parameter forwarded to each page request,
+            spelled ``field`` or ``field:direction`` (e.g. ``"date_mod:desc"``).
+            A space before the direction answers HTTP 400.
         fields : tuple[str, ...], optional
             Restricted set of contract field names to request.
 

glpi_python_client/_async/clients/api/dropdowns/_location.py

@@ -7,6 +7,8 @@ models.
 
 from __future__ import annotations
 
+from collections.abc import AsyncIterator
+
 from glpi_python_client._async.clients.commons._constants import (
     LOCATION_ENDPOINT,
     GlpiId,
@@ -52,6 +54,48 @@ class LocationMixin(TransportMixin):
             params["filter"] = rsql_filter
         return await self._resource_list(LOCATION_ENDPOINT, GetLocation, params=params)
 
+    async def iter_search_locations(
+        self,
+        rsql_filter: str = "",
+        *,
+        batch_size: int = 50,
+    ) -> AsyncIterator[list[GetLocation]]:
+        """Yield successive pages of GLPI locations 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 record.
+        batch_size : int, optional
+            Number of records requested per page (default 50). Acts as the
+            ``limit`` parameter on each underlying :meth:`search_locations`
+            call.
+
+        Yields
+        ------
+        list[GetLocation]
+            One page per iteration. The last yielded batch may be shorter
+            than ``batch_size``.
+        """
+
+        start = 0
+        while True:
+            batch = await self.search_locations(
+                rsql_filter,
+                limit=batch_size,
+                start=start,
+            )
+            if batch:
+                yield batch
+            if len(batch) < batch_size:
+                break
+            start += batch_size
+
     async def get_location(self, location_id: GlpiId) -> GetLocation:
         """Fetch one GLPI location by identifier.
 

glpi_python_client/_async/clients/api/knowledgebase/_article.py

@@ -8,7 +8,7 @@ Markdown through GLPI's HTML wire format transparently.
 
 from __future__ import annotations
 
-from collections.abc import Sequence
+from collections.abc import AsyncIterator, Sequence
 
 from glpi_python_client._async.clients.commons._constants import (
     KB_ARTICLE_ENDPOINT,
@@ -50,7 +50,11 @@ class KBArticleMixin(TransportMixin):
         start : int, optional
             Zero-based offset of the first record returned.
         sort : str | None, optional
-            ``sort`` query parameter forwarded as-is.
+            ``sort`` query parameter, spelled ``field`` or ``field:direction``
+            (e.g. ``"date_mod:desc"``). Measured against GLPI 11: a space
+            before the direction answers **HTTP 400** ("Invalid property for
+            sorting"), a bare ``field`` sorts *ascending*, and a separate
+            ``order`` parameter is ignored.
         language : str | None, optional
             GLPI language code forwarded as the ``language`` query
             parameter to select a translated view.
@@ -72,6 +76,59 @@ class KBArticleMixin(TransportMixin):
             KB_ARTICLE_ENDPOINT, GetKBArticle, params=params
         )
 
+    async def iter_search_kb_articles(
+        self,
+        rsql_filter: str = "",
+        *,
+        batch_size: int = 50,
+        sort: str | None = None,
+        language: str | None = None,
+    ) -> AsyncIterator[list[GetKBArticle]]:
+        """Yield successive pages of GLPI knowledge base articles 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 record.
+        batch_size : int, optional
+            Number of records requested per page (default 50). Acts as the
+            ``limit`` parameter on each underlying :meth:`search_kb_articles`
+            call.
+        sort : str | None, optional
+            ``sort`` query parameter forwarded to each page request,
+            spelled ``field`` or ``field:direction`` (e.g. ``"date_mod:desc"``).
+            A space before the direction answers HTTP 400.
+        language : str | None, optional
+            GLPI language code forwarded to each page request to select
+            a translated view.
+
+        Yields
+        ------
+        list[GetKBArticle]
+            One page per iteration. The last yielded batch may be shorter
+            than ``batch_size``.
+        """
+
+        start = 0
+        while True:
+            batch = await self.search_kb_articles(
+                rsql_filter,
+                limit=batch_size,
+                start=start,
+                sort=sort,
+                language=language,
+            )
+            if batch:
+                yield batch
+            if len(batch) < batch_size:
+                break
+            start += batch_size
+
     async def get_kb_article(self, article_id: GlpiId) -> GetKBArticle:
         """Fetch one knowledge base article by identifier.
 

glpi_python_client/_async/clients/api/knowledgebase/_category.py

@@ -7,6 +7,8 @@ GLPI knowledge base category resource using the contract-aligned
 
 from __future__ import annotations
 
+from collections.abc import AsyncIterator
+
 from glpi_python_client._async.clients.commons._constants import (
     KB_CATEGORY_ENDPOINT,
     GlpiId,
@@ -43,7 +45,11 @@ class KBCategoryMixin(TransportMixin):
         start : int, optional
             Zero-based offset of the first record returned.
         sort : str | None, optional
-            ``sort`` query parameter forwarded as-is, e.g. ``"name asc"``.
+            ``sort`` query parameter, spelled ``field`` or ``field:direction``
+            (e.g. ``"name:asc"``). Measured against GLPI 11: a space
+            before the direction answers **HTTP 400** ("Invalid property for
+            sorting"), a bare ``field`` sorts *ascending*, and a separate
+            ``order`` parameter is ignored.
         language : str | None, optional
             GLPI language code forwarded as the ``language`` query
             parameter to select a translated view.
@@ -65,6 +71,59 @@ class KBCategoryMixin(TransportMixin):
             KB_CATEGORY_ENDPOINT, GetKBCategory, params=params
         )
 
+    async def iter_search_kb_categories(
+        self,
+        rsql_filter: str = "",
+        *,
+        batch_size: int = 50,
+        sort: str | None = None,
+        language: str | None = None,
+    ) -> AsyncIterator[list[GetKBCategory]]:
+        """Yield successive pages of GLPI knowledge base categories 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 record.
+        batch_size : int, optional
+            Number of records requested per page (default 50). Acts as the
+            ``limit`` parameter on each underlying :meth:`search_kb_categories`
+            call.
+        sort : str | None, optional
+            ``sort`` query parameter forwarded to each page request,
+            spelled ``field`` or ``field:direction`` (e.g. ``"date_mod:desc"``).
+            A space before the direction answers HTTP 400.
+        language : str | None, optional
+            GLPI language code forwarded to each page request to select
+            a translated view.
+
+        Yields
+        ------
+        list[GetKBCategory]
+            One page per iteration. The last yielded batch may be shorter
+            than ``batch_size``.
+        """
+
+        start = 0
+        while True:
+            batch = await self.search_kb_categories(
+                rsql_filter,
+                limit=batch_size,
+                start=start,
+                sort=sort,
+                language=language,
+            )
+            if batch:
+                yield batch
+            if len(batch) < batch_size:
+                break
+            start += batch_size
+
     async def get_kb_category(self, category_id: GlpiId) -> GetKBCategory:
         """Fetch one knowledge base category by identifier.
 

glpi_python_client/_async/clients/api/management/_document.py

@@ -8,6 +8,7 @@ the v2 API does not advertise a binary upload endpoint in the contract.
 from __future__ import annotations
 
 import logging
+from collections.abc import AsyncIterator
 
 from glpi_python_client._async.clients.commons._constants import (
     DOCUMENT_ENDPOINT,
@@ -63,6 +64,48 @@ class DocumentMixin(TransportMixin):
             DOCUMENT_ENDPOINT, GetDocument, params=params, skip_entity=True
         )
 
+    async def iter_search_documents(
+        self,
+        rsql_filter: str = "",
+        *,
+        batch_size: int = 50,
+    ) -> AsyncIterator[list[GetDocument]]:
+        """Yield successive pages of GLPI documents 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 record.
+        batch_size : int, optional
+            Number of records requested per page (default 50). Acts as the
+            ``limit`` parameter on each underlying :meth:`search_documents`
+            call.
+
+        Yields
+        ------
+        list[GetDocument]
+            One page per iteration. The last yielded batch may be shorter
+            than ``batch_size``.
+        """
+
+        start = 0
+        while True:
+            batch = await self.search_documents(
+                rsql_filter,
+                limit=batch_size,
+                start=start,
+            )
+            if batch:
+                yield batch
+            if len(batch) < batch_size:
+                break
+            start += batch_size
+
     async def get_document(self, document_id: GlpiId) -> GetDocument:
         """Fetch one GLPI document by identifier.
 
@@ -214,6 +257,55 @@ class DocumentMixin(TransportMixin):
         )
         return response.content
 
+    async def stream_document_content(
+        self,
+        document_id: GlpiId,
+        *,
+        chunk_size: int = 65536,
+    ) -> AsyncIterator[bytes]:
+        """Stream the binary payload of one GLPI document in chunks.
+
+        Use this instead of :meth:`download_document_content` when the file
+        may be large: that method holds the whole body in memory before
+        returning, so a 500 MB attachment costs 500 MB of process memory
+        even if the caller only writes it straight to disk.
+
+        Parameters
+        ----------
+        document_id : GlpiId
+            Numeric identifier of the document whose binary content is
+            requested.
+        chunk_size : int, optional
+            Bytes requested per chunk (defaults to 64 KiB).
+
+        Yields
+        ------
+        bytes
+            Successive chunks of the document body. The final chunk may be
+            shorter than ``chunk_size``.
+
+        Raises
+        ------
+        GlpiStatusError
+            If the GLPI server returns a non-success HTTP status.
+
+        Examples
+        --------
+        Writing a document to disk without buffering it::
+
+            with open("attachment.pdf", "wb") as handle:
+                async for chunk in client.stream_document_content(42):
+                    handle.write(chunk)
+        """
+
+        async for chunk in self._stream_request(
+            f"{DOCUMENT_ENDPOINT}/{document_id}/Download",
+            chunk_size=chunk_size,
+            skip_entity=True,
+            failure_message=f"Failed to download document {document_id}",
+        ):
+            yield chunk
+
     async def upload_document(
         self,
         *,

glpi_python_client/_async/clients/api/plugins/_fields.py

@@ -33,6 +33,7 @@ from __future__ import annotations
 import json
 from typing import Any
 
+from glpi_python_client._async.clients.commons._payloads import model_from_payload
 from glpi_python_client._async.clients.commons._transport import TransportMixin
 from glpi_python_client._errors import GlpiProtocolError, GlpiValidationError
 from glpi_python_client.models.api_schema.plugins import (
@@ -147,7 +148,12 @@ class PluginFieldsMixin(TransportMixin):
             failure_message="Failed to list PluginFieldsContainer",
         )
         rows = payload if isinstance(payload, list) else []
-        containers = [GetPluginFieldsContainer.model_validate(row) for row in rows]
+        containers = [
+            model_from_payload(
+                GetPluginFieldsContainer, row, server_timezone=self.server_timezone
+            )
+            for row in rows
+        ]
         if itemtype is None:
             return containers
         return [c for c in containers if _container_targets_itemtype(c, itemtype)]
@@ -179,7 +185,12 @@ class PluginFieldsMixin(TransportMixin):
             failure_message="Failed to list PluginFieldsField",
         )
         rows = payload if isinstance(payload, list) else []
-        fields = [GetPluginFieldsField.model_validate(row) for row in rows]
+        fields = [
+            model_from_payload(
+                GetPluginFieldsField, row, server_timezone=self.server_timezone
+            )
+            for row in rows
+        ]
         if container_id is None:
             return fields
         return [f for f in fields if f.plugin_fields_containers_id == container_id]
@@ -219,7 +230,12 @@ class PluginFieldsMixin(TransportMixin):
             failure_message=f"Failed to list {endpoint}",
         )
         rows = payload if isinstance(payload, list) else []
-        return [GetPluginFieldsValueRow.model_validate(row) for row in rows]
+        return [
+            model_from_payload(
+                GetPluginFieldsValueRow, row, server_timezone=self.server_timezone
+            )
+            for row in rows
+        ]
 
     async def create_item_plugin_field_row(
         self,