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

glpi_python_client/__init__.py

@@ -30,6 +30,9 @@ from glpi_python_client.models import (
     GetEntity,
     GetFollowup,
     GetLocation,
+    GetPluginFieldsContainer,
+    GetPluginFieldsField,
+    GetPluginFieldsValueRow,
     GetSolution,
     GetTeamMember,
     GetTicket,
@@ -63,6 +66,7 @@ from glpi_python_client.models import (
     PostEntity,
     PostFollowup,
     PostLocation,
+    PostPluginFieldsValueRow,
     PostSolution,
     PostTeamMember,
     PostTicket,
@@ -72,7 +76,7 @@ from glpi_python_client.models import (
     TicketMarkdownOptions,
 )
 
-__version__ = "0.3.2"
+__version__ = "0.3.4"
 
 __all__ = [
     "AsyncGlpiClient",
@@ -90,6 +94,9 @@ __all__ = [
     "GetEntity",
     "GetFollowup",
     "GetLocation",
+    "GetPluginFieldsContainer",
+    "GetPluginFieldsField",
+    "GetPluginFieldsValueRow",
     "GetSolution",
     "GetTeamMember",
     "GetTicket",
@@ -124,6 +131,7 @@ __all__ = [
     "PostEntity",
     "PostFollowup",
     "PostLocation",
+    "PostPluginFieldsValueRow",
     "PostSolution",
     "PostTeamMember",
     "PostTicket",

glpi_python_client/auth/_v1_session.py

@@ -1,10 +1,27 @@
-"""GLPI v1 REST session used exclusively for document uploads.
-
-The high-level async ``GlpiClient`` only relies on the legacy v1 API for the
-``POST /Document`` multipart upload endpoint. The session wrapper below owns
-the authenticated v1 lifecycle (init, refresh, kill) and exposes a single
-``upload_document`` operation that the management mixin calls through
-``asyncio.to_thread`` at the blocking HTTP boundary.
+"""GLPI v1 REST session used for legacy endpoints not exposed by v2.
+
+Two consumers currently share this session:
+
+* the management :class:`DocumentMixin` for the multipart
+  ``POST /Document`` upload (the v2 API does not advertise a binary
+  upload route), and
+* the :class:`PluginFieldsMixin` for the GLPI "Fields" plugin endpoints
+  (``PluginFieldsContainer``, ``PluginFieldsField`` and the per-item
+  value itemtypes), which the v2 contract does not surface at all.
+
+The session wrapper owns the authenticated v1 lifecycle (init, refresh,
+kill) and exposes the typed ``upload_document`` helper plus the generic
+``request_json`` JSON-only HTTP helper that newer mixins build on.
+
+Retry policy
+------------
+Every public dispatch helper (``_init_session``, ``request_json``,
+``upload_document``) carries the same :mod:`tenacity` retry decorator
+used by the v2 transport: three attempts spaced by three seconds,
+triggered exclusively by :class:`requests.RequestException` (which
+:func:`finalize_request_response` raises for 5xx server errors).
+:class:`ValueError` raised by status-code or payload checks does not
+trigger a retry — client-side or 4xx failures are surfaced immediately.
 """
 
 from __future__ import annotations
@@ -12,15 +29,26 @@ from __future__ import annotations
 import json
 import logging
 from datetime import datetime, timedelta, timezone
-from typing import cast
+from typing import Any, cast
 
 import requests
-from tenacity import retry, stop_after_attempt, wait_fixed
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_fixed
+
+from glpi_python_client.clients.commons._http import (
+    ensure_response_status,
+    finalize_request_response,
+    response_json_or_empty,
+)
 
 logger = logging.getLogger(__name__)
 
 _DEFAULT_SESSION_REFRESH_INTERVAL_SECONDS = 15 * 60
 _AUTH_FAILURE_STATUS_CODES = frozenset({401, 403})
+_RETRY_ON_NETWORK_ERRORS = retry(
+    retry=retry_if_exception_type(requests.RequestException),
+    stop=stop_after_attempt(3),
+    wait=wait_fixed(3),
+)
 
 
 class GLPIV1Session:
@@ -36,7 +64,7 @@ class GLPIV1Session:
         *,
         base_url: str,
         user_token: str,
-        app_token: str,
+        app_token: str | None = None,
         verify_ssl: bool = True,
         session_refresh_interval_seconds: int = (
             _DEFAULT_SESSION_REFRESH_INTERVAL_SECONDS
@@ -59,12 +87,14 @@ class GLPIV1Session:
         self._session_token: str | None = None
         self._session_started_at: datetime | None = None
 
-    @retry(stop=stop_after_attempt(3), wait=wait_fixed(3))
+    @_RETRY_ON_NETWORK_ERRORS
     def _init_session(self) -> None:
         """Acquire one fresh GLPI v1 session token via ``GET /initSession``.
 
         The call replaces any existing session state and stores the
         authentication timestamp used by the refresh-interval check.
+        Network errors and 5xx responses are retried; 4xx and payload
+        errors propagate immediately as :class:`ValueError`.
         """
 
         headers: dict[str, str] = {
@@ -75,16 +105,20 @@ class GLPIV1Session:
         if self._app_token:
             headers["App-Token"] = self._app_token
 
-        response = self._http.get(
-            f"{self._base_url}/initSession",
-            headers=headers,
-            timeout=30,
+        url = f"{self._base_url}/initSession"
+        response = self._http.get(url, headers=headers, timeout=30)
+        finalize_request_response(
+            response,
+            method="get",
+            url=url,
+            success_statuses=(200,),
+            logger=logger,
+        )
+        ensure_response_status(
+            response,
+            success_statuses=(200,),
+            failure_message="GLPI v1 initSession failed",
         )
-        if response.status_code != 200:
-            raise ValueError(
-                "GLPI v1 initSession failed: "
-                f"{response.status_code} {response.text[:300]}"
-            )
 
         token = response.json().get("session_token")
         if not token:
@@ -140,11 +174,12 @@ class GLPIV1Session:
         """Drop the current GLPI v1 session token and acquire a new one.
 
         The previous token is best-effort killed so the GLPI server can release
-        the associated session state immediately.
+        the associated session state immediately. ``_init_session`` will set
+        the new token on success or raise, leaving the existing state
+        untouched on failure (the retry decorator handles transients).
         """
 
-        old_token = self._session_token
-        if old_token is not None:
+        if self._session_token is not None:
             try:
                 self._http.get(
                     f"{self._base_url}/killSession",
@@ -153,8 +188,6 @@ class GLPIV1Session:
                 )
             except Exception:
                 logger.warning("Failed to kill stale GLPI v1 session.", exc_info=True)
-        self._session_token = None
-        self._session_started_at = None
         self._init_session()
 
     def _headers(self) -> dict[str, str]:
@@ -172,13 +205,19 @@ class GLPIV1Session:
         method: str,
         url: str,
         *,
+        success_statuses: tuple[int, ...],
         headers: dict[str, str] | None = None,
-        **kwargs: object,
+        **kwargs: Any,
     ) -> requests.Response:
-        """Send one authenticated GLPI v1 request with one auth-failure retry.
-
-        When the GLPI server rejects the current token, the helper renews the
-        session and retries the request once before returning the response.
+        """Send one authenticated GLPI v1 request and finalize the response.
+
+        When the GLPI server rejects the current token the helper renews
+        the session and retries the request once. The returned response
+        has already been passed through :func:`finalize_request_response`
+        so 5xx errors surface as :class:`requests.HTTPError` for the
+        outer tenacity retry to catch; non-success statuses outside the
+        ``success_statuses`` set are logged but otherwise returned for
+        the caller to validate with :func:`ensure_response_status`.
         """
 
         request_headers = {**self._headers(), **(headers or {})}
@@ -187,18 +226,23 @@ class GLPIV1Session:
             requests.Response,
             request_method(url, headers=request_headers, **kwargs),
         )
-        if not _is_auth_failure_response(response):
-            return response
-
-        logger.warning(
-            "GLPI v1 session token was rejected; refreshing session and retrying "
-            "request once."
-        )
-        self._renew_session()
-        request_headers = {**self._headers(), **(headers or {})}
-        return cast(
-            requests.Response,
-            request_method(url, headers=request_headers, **kwargs),
+        if _is_auth_failure_response(response):
+            logger.warning(
+                "GLPI v1 session token was rejected; refreshing session and "
+                "retrying request once."
+            )
+            self._renew_session()
+            request_headers = {**self._headers(), **(headers or {})}
+            response = cast(
+                requests.Response,
+                request_method(url, headers=request_headers, **kwargs),
+            )
+        return finalize_request_response(
+            response,
+            method=method,
+            url=url,
+            success_statuses=success_statuses,
+            logger=logger,
         )
 
     def close(self) -> None:
@@ -223,7 +267,84 @@ class GLPIV1Session:
             self._session_started_at = None
             self._http.close()
 
-    @retry(stop=stop_after_attempt(3), wait=wait_fixed(3))
+    @_RETRY_ON_NETWORK_ERRORS
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, object] | None = None,
+        json_body: dict[str, object] | None = None,
+        success_statuses: tuple[int, ...] = (200, 201, 204, 206),
+        failure_message: str | None = None,
+    ) -> object:
+        """Send one JSON-only authenticated request to the GLPI v1 API.
+
+        The helper centralises session-token handling, the one-shot retry
+        on token rejection, status validation and JSON parsing so callers
+        can stay focused on their endpoint semantics. Network errors and
+        5xx responses are retried; 4xx and payload errors propagate
+        immediately as :class:`ValueError`.
+
+        Parameters
+        ----------
+        method : str
+            HTTP verb (``"GET"``, ``"POST"``, ``"PUT"``, ``"DELETE"``).
+        path : str
+            Resource path appended to the v1 base URL (without leading
+            slash, e.g. ``"PluginFieldsContainer"``).
+        params : dict[str, object] | None, optional
+            Query-string parameters forwarded to ``requests``.
+        json_body : dict[str, object] | None, optional
+            JSON body serialised into the request when set. The
+            ``Content-Type: application/json`` header is added
+            automatically.
+        success_statuses : tuple[int, ...], optional
+            HTTP status codes considered successful (default covers the
+            CRUD codes returned by the v1 API).
+        failure_message : str | None, optional
+            Prefix used in the :class:`ValueError` raised on a
+            non-success status. Defaults to ``"GLPI v1 {METHOD} {path}
+            failed"``.
+
+        Returns
+        -------
+        object
+            Parsed JSON body for non-empty responses; an empty ``dict``
+            when the body is empty or contains only whitespace.
+
+        Raises
+        ------
+        ValueError
+            If the v1 server returns a non-success HTTP status outside
+            the 5xx range (which surfaces as :class:`requests.HTTPError`
+            and is retried).
+        """
+
+        url = f"{self._base_url}/{path.lstrip('/')}"
+        kwargs: dict[str, Any] = {"timeout": 30}
+        if params is not None:
+            kwargs["params"] = params
+        headers: dict[str, str] = {}
+        if json_body is not None:
+            kwargs["data"] = json.dumps(json_body)
+            headers["Content-Type"] = "application/json"
+        response = self._authenticated_request(
+            method,
+            url,
+            success_statuses=success_statuses,
+            headers=headers or None,
+            **kwargs,
+        )
+        ensure_response_status(
+            response,
+            success_statuses=success_statuses,
+            failure_message=failure_message
+            or f"GLPI v1 {method.upper()} {path} failed",
+        )
+        return response_json_or_empty(response)
+
+    @_RETRY_ON_NETWORK_ERRORS
     def upload_document(
         self,
         filename: str,
@@ -238,7 +359,9 @@ class GLPIV1Session:
 
         The legacy v1 endpoint uses a multipart upload manifest so the GLPI
         server can create the document, link it to the optional parent ticket,
-        and assign it to the provided entity in a single round-trip.
+        and assign it to the provided entity in a single round-trip. Network
+        errors and 5xx responses are retried; 4xx and payload errors
+        propagate immediately as :class:`ValueError`.
         """
 
         manifest_input: dict[str, object] = {
@@ -255,17 +378,18 @@ class GLPIV1Session:
         response = self._authenticated_request(
             "POST",
             f"{self._base_url}/Document",
+            success_statuses=(200, 201),
             files=[
                 ("uploadManifest", (None, manifest, "application/json")),
                 ("filename[]", (filename, content, mime_type)),
             ],
             timeout=60,
         )
-        if response.status_code not in (200, 201):
-            raise ValueError(
-                "GLPI v1 document upload failed: "
-                f"{response.status_code} {response.text[:300]}"
-            )
+        ensure_response_status(
+            response,
+            success_statuses=(200, 201),
+            failure_message="GLPI v1 document upload failed",
+        )
         payload = response.json()
         if not isinstance(payload, dict):
             raise ValueError(

glpi_python_client/auth/tests/test_v1_session.py

@@ -32,22 +32,35 @@ class _FakeV1Http:
     def _next(self, key: str) -> FakeResponse:
         return self._responses[key].pop(0)
 
-    def get(self, url: str, headers: dict[str, str], timeout: int) -> FakeResponse:
+    def get(
+        self,
+        url: str,
+        headers: dict[str, str],
+        timeout: int,
+        **kwargs: Any,
+    ) -> FakeResponse:
         self.calls.append(
-            {"method": "GET", "url": url, "headers": headers, "timeout": timeout}
+            {
+                "method": "GET",
+                "url": url,
+                "headers": headers,
+                "timeout": timeout,
+                **kwargs,
+            }
         )
         if url.endswith("/initSession"):
             return self._next("init")
         if url.endswith("/killSession"):
             return self._next("kill")
-        raise AssertionError(f"Unexpected GET {url}")
+        return self._next("json")
 
     def post(
         self,
         url: str,
         headers: dict[str, str],
-        files: list[Any],
         timeout: int,
+        files: list[Any] | None = None,
+        **kwargs: Any,
     ) -> FakeResponse:
         self.calls.append(
             {
@@ -56,9 +69,48 @@ class _FakeV1Http:
                 "headers": headers,
                 "files": files,
                 "timeout": timeout,
+                **kwargs,
+            }
+        )
+        if files is not None:
+            return self._next("upload")
+        return self._next("json")
+
+    def put(
+        self,
+        url: str,
+        headers: dict[str, str],
+        timeout: int,
+        **kwargs: Any,
+    ) -> FakeResponse:
+        self.calls.append(
+            {
+                "method": "PUT",
+                "url": url,
+                "headers": headers,
+                "timeout": timeout,
+                **kwargs,
             }
         )
-        return self._next("upload")
+        return self._next("json")
+
+    def delete(
+        self,
+        url: str,
+        headers: dict[str, str],
+        timeout: int,
+        **kwargs: Any,
+    ) -> FakeResponse:
+        self.calls.append(
+            {
+                "method": "DELETE",
+                "url": url,
+                "headers": headers,
+                "timeout": timeout,
+                **kwargs,
+            }
+        )
+        return self._next("json")
 
     def close(self) -> None:
         self.closed = True
@@ -161,8 +213,8 @@ def test_v1_upload_renews_session_on_401() -> None:
     ]
 
 
-def test_v1_upload_raises_on_non_success() -> None:
-    """Non-success upload responses raise ``ValueError`` (after retries)."""
+def test_v1_upload_raises_on_5xx_after_retries() -> None:
+    """5xx upload responses surface as ``HTTPError`` after retries exhaust."""
 
     http = _FakeV1Http(
         responses={
@@ -175,28 +227,44 @@ def test_v1_upload_raises_on_non_success() -> None:
     with pytest.raises(tenacity.RetryError) as excinfo:
         session.upload_document("a.txt", b"x", "text/plain")
     inner = excinfo.value.last_attempt.exception()
-    assert isinstance(inner, ValueError) and "document upload failed" in str(inner)
+    assert isinstance(inner, requests.HTTPError)
+
+
+def test_v1_upload_raises_on_4xx_without_retry() -> None:
+    """Non-5xx non-success upload responses raise ``ValueError`` without retry."""
+
+    http = _FakeV1Http(
+        responses={
+            "init": [FakeResponse(status_code=200, payload={"session_token": "tk"})],
+            "upload": [FakeResponse(status_code=400, payload={"err": "bad"})],
+            "kill": [FakeResponse(status_code=200, payload={})],
+        }
+    )
+    session = _make(http)
+    with pytest.raises(ValueError, match="document upload failed"):
+        session.upload_document("a.txt", b"x", "text/plain")
+    # A single attempt was performed (init + one upload).
+    upload_calls = [c for c in http.calls if c["url"].endswith("/Document")]
+    assert len(upload_calls) == 1
 
 
 def test_v1_upload_raises_on_unexpected_payload() -> None:
-    """A non-mapping JSON payload raises ``ValueError`` (after retries)."""
+    """A non-mapping JSON payload raises ``ValueError`` without retry."""
 
     http = _FakeV1Http(
         responses={
             "init": [FakeResponse(status_code=200, payload={"session_token": "tk"})],
-            "upload": [FakeResponse(status_code=200, payload=["unexpected"])] * 3,
+            "upload": [FakeResponse(status_code=200, payload=["unexpected"])],
             "kill": [FakeResponse(status_code=200, payload={})],
         }
     )
     session = _make(http)
-    with pytest.raises(tenacity.RetryError) as excinfo:
+    with pytest.raises(ValueError, match="unexpected payload"):
         session.upload_document("a.txt", b"x", "text/plain")
-    inner = excinfo.value.last_attempt.exception()
-    assert isinstance(inner, ValueError) and "unexpected payload" in str(inner)
 
 
-def test_v1_init_raises_on_failure() -> None:
-    """``initSession`` failure raises ``ValueError`` after retries exhaust."""
+def test_v1_init_raises_on_5xx_after_retries() -> None:
+    """5xx ``initSession`` responses surface as ``HTTPError`` after retries."""
 
     http = _FakeV1Http(
         responses={
@@ -207,20 +275,31 @@ def test_v1_init_raises_on_failure() -> None:
     with pytest.raises(tenacity.RetryError) as excinfo:
         session._init_session()
     inner = excinfo.value.last_attempt.exception()
-    assert isinstance(inner, ValueError) and "initSession failed" in str(inner)
+    assert isinstance(inner, requests.HTTPError)
+
+
+def test_v1_init_raises_on_4xx_without_retry() -> None:
+    """Non-5xx ``initSession`` responses raise ``ValueError`` immediately."""
+
+    http = _FakeV1Http(
+        responses={
+            "init": [FakeResponse(status_code=401, payload={"err": "denied"})],
+        }
+    )
+    session = _make(http)
+    with pytest.raises(ValueError, match="initSession failed"):
+        session._init_session()
 
 
 def test_v1_init_raises_when_token_missing() -> None:
-    """``initSession`` returning no token raises ``ValueError`` after retries."""
+    """``initSession`` returning no token raises ``ValueError`` without retry."""
 
     http = _FakeV1Http(
-        responses={"init": [FakeResponse(status_code=200, payload={})] * 3},
+        responses={"init": [FakeResponse(status_code=200, payload={})]},
     )
     session = _make(http)
-    with pytest.raises(tenacity.RetryError) as excinfo:
+    with pytest.raises(ValueError, match="no session_token"):
         session._init_session()
-    inner = excinfo.value.last_attempt.exception()
-    assert isinstance(inner, ValueError) and "no session_token" in str(inner)
 
 
 def test_v1_close_kills_session_and_closes_http() -> None:
@@ -260,6 +339,90 @@ def test_v1_close_tolerates_kill_failure() -> None:
     assert http.closed is True
 
 
+def test_request_json_sends_body_and_returns_parsed_payload() -> None:
+    """``request_json`` serialises the body and decodes the JSON response."""
+
+    http = _FakeV1Http(
+        responses={
+            "init": [FakeResponse(status_code=200, payload={"session_token": "tk"})],
+            "json": [FakeResponse(status_code=200, payload={"ok": True})],
+            "kill": [FakeResponse(status_code=200, payload={})],
+        }
+    )
+    session = _make(http)
+    result = session.request_json(
+        "POST",
+        "PluginFieldsContainer",
+        json_body={"input": {"name": "x"}},
+    )
+    assert result == {"ok": True}
+    post_call = next(call for call in http.calls if call["method"] == "POST")
+    assert post_call["url"].endswith("/PluginFieldsContainer")
+    assert post_call["data"] == jsonlib.dumps({"input": {"name": "x"}})
+    assert post_call["headers"]["Content-Type"] == "application/json"
+
+
+def test_request_json_supports_get_with_params() -> None:
+    """``request_json`` forwards query params on GET calls."""
+
+    http = _FakeV1Http(
+        responses={
+            "init": [FakeResponse(status_code=200, payload={"session_token": "tk"})],
+            "json": [FakeResponse(status_code=200, payload=[{"id": 1}])],
+        }
+    )
+    session = _make(http)
+    out = session.request_json("GET", "PluginFieldsContainer", params={"range": "0-1"})
+    assert out == [{"id": 1}]
+    get_call = next(
+        call for call in http.calls if call["url"].endswith("/PluginFieldsContainer")
+    )
+    assert get_call["params"] == {"range": "0-1"}
+
+
+def test_request_json_returns_empty_dict_on_empty_body() -> None:
+    """An empty response body decodes as an empty dict instead of raising."""
+
+    http = _FakeV1Http(
+        responses={
+            "init": [FakeResponse(status_code=200, payload={"session_token": "tk"})],
+            "json": [FakeResponse(status_code=204, payload={}, content=b"")],
+        }
+    )
+    session = _make(http)
+    assert session.request_json("DELETE", "Some/Resource/1") == {}
+
+
+def test_request_json_raises_on_4xx_without_retry() -> None:
+    """Non-5xx non-success statuses raise ``ValueError`` without retry."""
+
+    http = _FakeV1Http(
+        responses={
+            "init": [FakeResponse(status_code=200, payload={"session_token": "tk"})],
+            "json": [FakeResponse(status_code=404, payload={"err": "missing"})],
+        }
+    )
+    session = _make(http)
+    with pytest.raises(ValueError, match="failed"):
+        session.request_json("GET", "PluginFieldsContainer")
+
+
+def test_request_json_retries_on_5xx() -> None:
+    """5xx responses surface as ``HTTPError`` after retries exhaust."""
+
+    http = _FakeV1Http(
+        responses={
+            "init": [FakeResponse(status_code=200, payload={"session_token": "tk"})],
+            "json": [FakeResponse(status_code=500, payload={"err": "boom"})] * 3,
+        }
+    )
+    session = _make(http)
+    with pytest.raises(tenacity.RetryError) as excinfo:
+        session.request_json("GET", "PluginFieldsContainer")
+    inner = excinfo.value.last_attempt.exception()
+    assert isinstance(inner, requests.HTTPError)
+
+
 def test_session_token_invalid_marker_triggers_renew() -> None:
     """An ``ERROR_SESSION_TOKEN_INVALID`` body marker counts as an auth failure."""