glpi-python-client 0.3.3__tar.gz → 0.3.4__tar.gz

{glpi_python_client-0.3.3 → glpi_python_client-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: glpi-python-client
-Version: 0.3.3
+Version: 0.3.4
 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.3 → glpi_python_client-0.3.4}/docs/api_reference.rst

@@ -289,6 +289,36 @@ Entities
    :undoc-members:
    :show-inheritance:
 
+Plugin: Fields (custom fields)
+------------------------------
+
+Schemas returned by the GLPI ``Fields`` plugin (legacy v1 REST endpoints).
+The companion mixin methods are exposed on :class:`GlpiClient` /
+:class:`AsyncGlpiClient` as ``list_plugin_fields_containers``,
+``list_plugin_fields_fields``, ``list_item_plugin_field_rows``,
+``create_item_plugin_field_row``, ``update_item_plugin_field_row``,
+``get_ticket_custom_fields`` and ``set_ticket_custom_fields``.
+
+.. autoclass:: GetPluginFieldsContainer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: GetPluginFieldsField
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: GetPluginFieldsValueRow
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: PostPluginFieldsValueRow
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Enums
 -----
 

{glpi_python_client-0.3.3 → glpi_python_client-0.3.4}/docs/user_guide.rst

@@ -11,8 +11,10 @@ whose surface is built from contract-aligned per-endpoint mixins:
   it to a worker thread via :func:`asyncio.to_thread`.
 
 Both clients speak the GLPI **v2** high-level API and fall back to the
-legacy v1 endpoint only for binary document uploads. They expose the
-exact same endpoint methods and accept the same constructor arguments.
+legacy v1 API for features that are not exposed by v2, currently
+binary document uploads and the ``Fields`` plugin custom-field
+helpers. They expose the exact same endpoint methods and accept the
+same constructor arguments.
 Public methods always return Pydantic models (or simple Python types)
 and never raw dictionaries.
 
@@ -36,7 +38,8 @@ The guide is split into the following sections:
    one-to-one to GLPI v2 endpoints (tickets, timeline, team members,
    users, locations, entities, documents).
 5. **Added functionalities** — helpers built on top of the API mixins:
-   the aggregated ticket context view and the reporting helpers.
+    the ``Fields`` plugin custom-field helpers, the aggregated ticket
+    context view, and the reporting helpers.
 6. **End-to-end examples** — full workflows that combine the previous
    building blocks.
 
@@ -111,7 +114,9 @@ Optional constructor arguments
 * ``auth_token_refresh`` — number of seconds before token expiry at
   which the auth manager proactively refreshes the OAuth access token.
 * ``v1_base_url`` and ``v1_user_token`` — together enable the legacy v1
-  fallback used by :meth:`GlpiClient.upload_document`.
+    fallback used by :meth:`GlpiClient.upload_document` and the
+    ``Fields`` plugin helpers such as
+    :meth:`GlpiClient.get_ticket_custom_fields`.
 * ``executor`` (:class:`AsyncGlpiClient` only) — an explicit
   :class:`concurrent.futures.Executor` used to dispatch the wrapped
   synchronous calls. Defaults to the standard library thread pool
@@ -616,6 +621,55 @@ Example output::
 The helpers in this section are not part of the GLPI contract. They are
 small utilities the client builds on top of the API mixins.
 
+Ticket custom fields via the Fields plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `Fields plugin <https://github.com/pluginsGLPI/fields>`_ exposes
+ticket custom fields through the legacy v1 API rather than the GLPI v2
+contract. Configure the client with ``v1_base_url`` and
+``v1_user_token`` (or the matching ``GLPI_V1_*`` environment
+variables), then use the discovery helpers when you need the plugin's
+internal container and field names:
+
+.. code-block:: python
+
+    from glpi_python_client import GlpiClient
+
+   with GlpiClient(
+       glpi_api_url="https://glpi.example.com/api.php/v2",
+       client_id="oauth-client-id",
+       client_secret="oauth-client-secret",
+       username="api-user",
+       password="api-password",
+       v1_base_url="https://glpi.example.com/apirest.php",
+       v1_user_token="legacy-user-token",
+   ) as client:
+       containers = client.list_plugin_fields_containers(itemtype="Ticket")
+       for container in containers:
+           print(container.id, container.name)
+           fields = client.list_plugin_fields_fields(container_id=container.id)
+           print([field.name for field in fields])
+
+       custom_fields = client.get_ticket_custom_fields(ticket_id)
+       print(custom_fields)
+
+       client.set_ticket_custom_fields(
+           ticket_id,
+           {
+               "aidelarsolution": {
+                   "aidelarsolutionfield": "<p>Handled by the NOC shift</p>",
+               }
+           },
+       )
+
+The high-level ``get_ticket_custom_fields`` /
+``set_ticket_custom_fields`` pair uses the mapping
+``{container_name: {field_name: value}}`` and automatically decides
+whether the v1 plugin needs a row creation or an in-place update. Drop
+to ``list_item_plugin_field_rows``, ``create_item_plugin_field_row``,
+or ``update_item_plugin_field_row`` only when you need the raw v1 row
+shape.
+
 Aggregated ticket context
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -780,9 +834,7 @@ batches until the API returns fewer rows than the requested
 
    Always pass an RSQL filter to ``iter_search_tickets``. Querying
    without any filter can return very large result sets and may cause
-   the GLPI server to return a 500 error on busy instances. The other
-   two generators (``iter_search_users``, ``iter_search_entities``) are
-   not affected because those collections are typically much smaller.
+   the GLPI server to return a 500 errors.
 
 On the asynchronous client the same helpers are exposed as **async
 generators** through the bridge, so each ``next()`` call runs off the

{glpi_python_client-0.3.3 → glpi_python_client-0.3.4}/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.3"
+__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-0.3.3 → glpi_python_client-0.3.4}/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(