glpi-python-client 0.4.1__tar.gz → 0.4.3__tar.gz

{glpi_python_client-0.4.1 → glpi_python_client-0.4.3}/CHANGELOG.md

@@ -4,7 +4,178 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## Unreleased
+## 0.4.3 — 2026-08-13
+
+### Changed (breaking)
+
+- **`server_timezone` is now a required client argument** (`GLPI_SERVER_TIMEZONE`
+  for `from_env`). It takes an IANA zone name — `"Europe/Paris"` — or a
+  `tzinfo`.
+
+  GLPI 11 sends most timestamps with the correct historical offset, but not
+  all of them. Measured against a live instance: 19 of the 20 datetime fields
+  across every resource are offset-bearing, and `KBArticle.revisions[].date`
+  is not. One response therefore carries both kinds, and comparing them raises
+  `TypeError: can't compare offset-naive and offset-aware datetimes` — sorting
+  an article's revision history against the article's own dates was enough to
+  trigger it.
+
+  There is deliberately **no default**. Every candidate is wrong somewhere:
+  against a Europe/Paris instance, assuming UTC shifts the affected timestamps
+  by one or two hours *and stops raising*, turning a loud failure into a quiet
+  wrong answer. An IANA name is preferred over a fixed offset because a name
+  follows DST — the same instance emits both `+01:00` and `+02:00`.
+
+  An offset already on the wire always wins over the configured zone, and a
+  model built outside the client (no validation context) keeps its naive values
+  rather than being stamped with a guess.
+
+  Adds `tzdata` as a dependency on Windows, which ships no system timezone
+  database; without it `zoneinfo` resolves on Linux CI and raises on a
+  developer machine.
+
+- **Search endpoints now raise on a 4xx instead of returning `[]`.** The seven
+  `search_*` helpers passed no `failure_message` to `_resource_list`, which
+  skipped the status check entirely, so a 400, 401, 403 or 404 came back as an
+  empty list — indistinguishable from a filter that legitimately matched
+  nothing. (5xx already raised.) It composed badly with the batch iterators:
+  they stop on a page shorter than `batch_size`, so a 403 on the first page
+  ended the walk having yielded nothing and the caller saw a *successful*
+  empty result. This reverses decision D2 of the 0.4.0 error work, which chose
+  tolerance deliberately; the silent-empty failure mode has proved worse than
+  the exception. An empty list now means the server said the result set is
+  empty. **Callers that relied on `[]` after a permission error must catch
+  `GlpiStatusError`.**
+
+### Added
+
+- **`PatchTicket.status`** — ticket status is writable after all, typed
+  `GlpiTicketStatus | None`:
+
+  ```python
+  client.update_ticket(ticket_id, PatchTicket(status=GlpiTicketStatus.PENDING))
+  ```
+
+  The field had been excluded on the grounds that GLPI "manages the ticket
+  lifecycle through dedicated timeline routes", which is what the contract
+  says: it publishes `Ticket.status.id` as `readOnly: true`. Measured against
+  a live GLPI 11 instance, that is wrong — `PATCH` with `{"status": 5}`
+  answers 200 and the ticket moves. Same failure mode as the `Major` priority
+  level the contract omits: observed server behaviour wins.
+
+  It is declared on `PatchTicket` and **not** on `PostTicket`, because the two
+  routes genuinely differ — `POST` with a status answers 201 and creates a
+  *New* ticket, dropping the field. A create argument for it would have done
+  nothing. `status_id` is likewise ignored; `status` is the spelling that
+  works.
+
+  The annotation is the enum rather than `int` deliberately. GLPI validates
+  nothing here: `{"status": 99}` answers 200 and stores it, after which the
+  API reports `{"id": 99, "name": "99"}`, the web form displays the ticket as
+  *New*, and the ticket vanishes from the ticket list while remaining open in
+  the database — only the history records the change. A typo like `55` for
+  `5` would lose a ticket in silence, so this model is the only validation on
+  the path. `GetTicket.status` stays the permissive `IdNameRef`, since a
+  strict enum on the read side would fail a whole search over one bad row.
+
+- **`glpi_python_client.rsql`** — public date builders for the v2 filter
+  grammar: `created_between`, `date_window` and `changed_since`, all exported
+  from the package root. The end-of-day detail on a window's upper bound is
+  easy to get wrong and impossible to notice, since GLPI answers a malformed
+  filter by ignoring it and returning the whole table.
+
+- **`find_user_by_email(email)`** — resolves a person by address. It scans,
+  because GLPI exposes addresses as the nested array `User.emails` and the v2
+  filter engine cannot join a nested array. Narrow it with `rsql_filter` and
+  cache the id; do not hand-roll an RSQL e-mail filter.
+
+- **`stream_document_content(document_id, chunk_size=...)`** — yields a
+  document body in chunks instead of buffering it whole, as
+  `download_document_content` does. Upload still buffers.
+
+- **Batch iterators for the four resources that lacked one**:
+  `iter_search_kb_articles`, `iter_search_kb_categories`,
+  `iter_search_documents` and `iter_search_locations`.
+
+### Fixed
+
+- **Every `datetime` write raised `TypeError`.** `model_to_payload` dumped in
+  Pydantic's python mode, so a request body reached `json.dumps` still holding
+  a live `datetime`. The failure landed at the encoder — after the model had
+  validated and outside any transport stub — which is why the suite never saw
+  it. The dump now runs in JSON mode.
+
+- **GLPI discards the offset on every datetime it is sent, so aware values
+  were written as the wrong moment.** Measured against a live Europe/Paris
+  instance: `2026-08-01T12:30:00` written bare, as `...Z`, and with `+02:00`,
+  `+09:00`, `-08:00` and `+14:00` all store 12:30 Paris. The server reads the
+  naive prefix, interprets it in its own timezone, and throws the rest away —
+  with a 200. It does parse the offset first, since `+99:99` answers HTTP 500,
+  which is the worst combination: a malformed offset crashes, a well-formed
+  wrong one is silent. `12:30-08:00` is 21:30 in Paris and landed nine hours
+  early.
+
+  An aware `datetime` is now converted onto the server's clock and the offset
+  dropped, via a serialisation context mirroring the validation context used
+  on the inbound half. Naive values are untouched — they already mean the
+  server's clock — and no context means no conversion, so a model dumped
+  outside the client is unchanged. This is the second half of the
+  `server_timezone` contract above; `mode="json"` alone would have shipped
+  writes wrong by up to twelve hours.
+
+- **`get_ticket_statistics` silently truncated at 200 tickets**, on an
+  instance whose own docstring records 59,690. It issued one `search_tickets`
+  call with no paging loop, so every statistic was computed over whichever
+  200 tickets came back first and reported as if it covered the corpus. The
+  two entity and one user name-resolution sites had the same shape. All four
+  now page through `iter_search_*`.
+
+- **`from_transport` silently deleted text.** The HTML path was taken whenever
+  the content held both `<` and `>`, so `"use the <Enter> key"` became
+  `"use the  key"` — an unknown tag's markup is dropped and its empty body
+  kept, removing the word with nothing left to show it was ever there.
+  `"cmd </dev/null > out"` and `"if x<y then z>0"` lost text the same way. The
+  decision is now made on the element *name*.
+
+- **Fenced code blocks, tables and prose punctuation were mangled.** Without
+  the `fenced_code` extension a fence rendered as inline `<code>`, which the
+  GLPI web UI shows as one run-on line and which a later read wrote back as
+  inline code — so a pasted log degraded further on every edit. Without
+  `tables`, a table rendered as literal pipes. Inbound, `markdownify` escaped
+  underscores and asterisks, so `snake_case` came back as `snake\_case` and
+  accumulated a backslash on every read-modify-write cycle.
+
+- **`_MAX_DATETIME` was naive, so `to_markdown()` raised on a mixed-awareness
+  timeline.** Sorting events padded absent timestamps with `datetime.max`,
+  which cannot be compared against the offset-bearing values GLPI sends. The
+  sort key now normalises both sides to UTC. The live probe confirmed the
+  mixed population is real, not hypothetical.
+
+- **`require_response_int` rejected create responses GLPI actually returns.**
+  A numeric-string id, an id nested under a `data` envelope, and a create that
+  reports only a `Location` header all raised a protocol error over a
+  perfectly usable identifier. It now probes top-level keys, then the
+  envelope, then the header.
+
+- **`sort="date_mod desc"` — the library's own documented example — is HTTP
+  400.** Found while running the wire-format probe. The accepted syntax is
+  `field:direction`; a bare `date_mod` is accepted but sorts *ascending*, and
+  `order=` is ignored entirely.
+
+- **Three client construction examples had `server_timezone` inserted twice
+  and misindented**, by the sweep that added it. A repeated keyword argument
+  is a `SyntaxError`, so those examples could not be copied at all. Two older
+  documentation defects surfaced alongside them: three lines of expected
+  output stranded inside a `code-block:: python` (they belong to the example
+  above), and an import indented four spaces inside a three-space block. A new
+  test compiles all 77 Python snippets in the skills, the guide and the
+  README.
+
+## 0.4.0 – 0.4.2
+
+These three releases were tagged without the changelog ever being
+sectioned, so their notes accumulated under a single `Unreleased`
+heading. They are grouped here rather than split retroactively.
 
 ### Fixed
 
@@ -314,6 +485,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - The `requests` intersphinx mapping is removed; it survived the transport
   swap and made every docs build fetch an inventory nothing referenced.
 
+## Pre-0.4.0 notes
+
+Kept for history. Written before the httpx and unasync rewrites, so the
+status they describe is superseded by everything above — the transport is
+no longer `requests`, and tolerant searches no longer swallow a 4xx.
+
 ### Unchanged (deliberately)
 
 - Retry semantics: 5xx retried 3 times with a 3-second fixed wait, 4xx never

{glpi_python_client-0.4.1 → glpi_python_client-0.4.3}/CONTRIBUTING.md

@@ -38,7 +38,7 @@ python -m sphinx -W --keep-going -b html docs docs/_build/html
 
 ## GitHub Actions
 
-- `.github/workflows/ci.yml` runs tests for Python 3.10 through 3.13 on pull
+- `.github/workflows/ci.yml` runs tests for Python 3.10 through 3.14 on pull
   requests and pushes to `main`.
 - The same workflow runs `ruff`, `mypy`, and a warning-free Sphinx build on
   Python 3.12.

{glpi_python_client-0.4.1 → glpi_python_client-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: glpi-python-client
-Version: 0.4.1
+Version: 0.4.3
 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/
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
@@ -32,6 +33,7 @@ Requires-Dist: pydantic>=2.8
 Requires-Dist: sniffio>=1.3
 Requires-Dist: tenacity>=8.2
 Requires-Dist: typing-extensions>=4.7; python_version < '3.11'
+Requires-Dist: tzdata>=2024.1; platform_system == 'Windows'
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == 'dev'
 Requires-Dist: mypy>=1.11; extra == 'dev'
@@ -113,6 +115,7 @@ from glpi_python_client import GlpiClient, PostTicket
 
 with GlpiClient(
     glpi_api_url="https://glpi.example.com/api.php/v2",
+    server_timezone="Europe/Paris",
     client_id="oauth-client-id",
     client_secret="oauth-client-secret",
     username="api-user",
@@ -139,6 +142,7 @@ from glpi_python_client import AsyncGlpiClient, PostTicket
 async def main() -> None:
     async with AsyncGlpiClient(
         glpi_api_url="https://glpi.example.com/api.php/v2",
+        server_timezone="Europe/Paris",
         client_id="oauth-client-id",
         client_secret="oauth-client-secret",
         username="api-user",

{glpi_python_client-0.4.1 → glpi_python_client-0.4.3}/README.md

@@ -57,6 +57,7 @@ from glpi_python_client import GlpiClient, PostTicket
 
 with GlpiClient(
     glpi_api_url="https://glpi.example.com/api.php/v2",
+    server_timezone="Europe/Paris",
     client_id="oauth-client-id",
     client_secret="oauth-client-secret",
     username="api-user",
@@ -83,6 +84,7 @@ from glpi_python_client import AsyncGlpiClient, PostTicket
 async def main() -> None:
     async with AsyncGlpiClient(
         glpi_api_url="https://glpi.example.com/api.php/v2",
+        server_timezone="Europe/Paris",
         client_id="oauth-client-id",
         client_secret="oauth-client-secret",
         username="api-user",

{glpi_python_client-0.4.1 → glpi_python_client-0.4.3}/docs/publishing_rtd.rst

@@ -92,7 +92,7 @@ GitHub Actions and Read the Docs
 The repository ships with two GitHub Actions workflows:
 
 * ``.github/workflows/ci.yml`` runs on pull requests and pushes to ``main``.
-   It executes ``pytest`` on Python 3.10 through 3.13, then runs ``ruff``,
+   It executes ``pytest`` on Python 3.10 through 3.14, then runs ``ruff``,
    ``mypy``, and the Sphinx build on Python 3.12.
 * ``.github/workflows/release.yml`` runs on published GitHub releases. It
    repeats the quality checks, builds the source and wheel distributions,

{glpi_python_client-0.4.1 → glpi_python_client-0.4.3}/docs/user_guide.rst

@@ -68,6 +68,7 @@ pair. The OAuth password grant accepts either ``client_id`` /
 
    with GlpiClient(
        glpi_api_url="https://glpi.example.com/api.php/v2",
+       server_timezone="Europe/Paris",
        client_id="oauth-client-id",
        client_secret="oauth-client-secret",
        username="api-user",
@@ -92,6 +93,7 @@ The asynchronous client takes the same arguments and is used inside an
    async def main() -> None:
        async with AsyncGlpiClient(
            glpi_api_url="https://glpi.example.com/api.php/v2",
+           server_timezone="Europe/Paris",
            client_id="oauth-client-id",
            client_secret="oauth-client-secret",
            username="api-user",
@@ -134,6 +136,11 @@ build the client for you:
 * ``GLPI_CLIENT_ID`` and ``GLPI_CLIENT_SECRET``
 * ``GLPI_USERNAME`` and ``GLPI_PASSWORD``
 * ``GLPI_ENTITY``, ``GLPI_PROFILE``, ``GLPI_ENTITY_RECURSIVE``
+* ``GLPI_SERVER_TIMEZONE`` -- **required**. IANA name of the timezone the
+  GLPI server runs in (e.g. ``Europe/Paris``). GLPI does not advertise it,
+  and it is needed to interpret the timestamps the server sends without an
+  offset. There is no default: guessing UTC against a Europe/Paris instance
+  shifts those values by an hour or two and never raises.
 * ``GLPI_LANGUAGE``, ``GLPI_VERIFY_SSL``
 * ``GLPI_V1_BASE_URL``, ``GLPI_V1_USER_TOKEN``, ``GLPI_V1_APP_TOKEN``
 
@@ -628,6 +635,9 @@ so the client sets it through a legacy fallback — see
 Example output::
 
    ['Networking']
+   42 Reset a Wi-Fi controller
+   42 Reset a Wi-Fi controller
+   1 revision(s)
 
 Assigning categories
 ^^^^^^^^^^^^^^^^^^^^^
@@ -659,9 +669,6 @@ article's full category set; passing an empty list clears every category.
    # Or set them explicitly at any time.
    client.set_kb_article_categories(article_id, [14])  # replace the full set
    client.set_kb_article_categories(article_id, [])    # clear all
-   42 Reset a Wi-Fi controller
-   42 Reset a Wi-Fi controller
-   1 revision(s)
 
 Enums
 ~~~~~
@@ -710,10 +717,11 @@ internal container and field names:
 
 .. code-block:: python
 
-    from glpi_python_client import GlpiClient
+   from glpi_python_client import GlpiClient
 
    with GlpiClient(
        glpi_api_url="https://glpi.example.com/api.php/v2",
+       server_timezone="Europe/Paris",
        client_id="oauth-client-id",
        client_secret="oauth-client-secret",
        username="api-user",
@@ -1223,8 +1231,10 @@ Example 4 — Close a ticket with a solution
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 GLPI moves a ticket to the *Solved* status as soon as a solution is
-posted, so adding a solution is the supported way to change the ticket
-status from the v2 API.
+posted, so this both records *how* the ticket was resolved and advances
+its lifecycle in one call. Prefer it over setting the status directly
+whenever there is a resolution to record — a status moved on its own
+leaves no trace of why.
 
 .. code-block:: python
 
@@ -1248,6 +1258,34 @@ Expected Markdown (abridged)::
 
    Replaced the access point firmware.
 
+For the transitions that have no timeline record behind them — putting a
+ticket on hold, planning it, taking it back from *Solved* — set the
+status directly. ``PatchTicket`` carries a ``status`` field and
+``update_ticket`` sends it:
+
+.. code-block:: python
+
+   from glpi_python_client import GlpiTicketStatus, PatchTicket
+
+   client.update_ticket(ticket_id, PatchTicket(status=GlpiTicketStatus.PENDING))
+
+The field lives on ``PatchTicket`` and deliberately not on
+``PostTicket``: GLPI ignores a status sent at creation time and the new
+ticket comes back as *New*, so a create argument for it would do
+nothing.
+
+.. warning::
+
+   ``status`` is typed as :class:`glpi_python_client.GlpiTicketStatus`
+   and rejects anything outside it, because the server accepts
+   everything and its interface hides the result. Writing ``99``
+   answers ``200`` and stores it; the API then reports
+   ``{"id": 99, "name": "99"}``, the web form displays the ticket as
+   *New*, and the ticket disappears from the ticket list while staying
+   open in the database — only the history records the change. A typo
+   such as ``55`` for ``5`` would lose a ticket with no error anywhere,
+   which is why the enum refuses it here.
+
 Example 5 — Upload a document to an existing ticket
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

{glpi_python_client-0.4.1 → glpi_python_client-0.4.3}/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.1"
+__version__ = "0.4.3"
 
 __all__ = [
     "AsyncGlpiClient",
@@ -190,4 +195,7 @@ __all__ = [
     "PostUser",
     "TicketMarkdownOptions",
     "__version__",
+    "changed_since",
+    "created_between",
+    "date_window",
 ]

{glpi_python_client-0.4.1 → glpi_python_client-0.4.3}/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-0.4.1 → glpi_python_client-0.4.3}/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-0.4.1 → glpi_python_client-0.4.3}/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-0.4.1 → glpi_python_client-0.4.3}/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-0.4.1 → glpi_python_client-0.4.3}/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.