glpi-python-client 0.1.3__py3-none-any.whl → 0.2.1__py3-none-any.whl

glpi_python_client/__init__.py

@@ -1,36 +1,125 @@
 """Public import surface for the GLPI Python client package.
 
-This module re-exports the supported high-level clients and typed GLPI models
-so applications can import them from a single stable package root.
+The package re-exports the asynchronous :class:`GlpiClient` and the
+``api_schema`` and ``custom_schema`` Pydantic models so downstream users
+can import them from a single stable package root.
 """
 
 from __future__ import annotations
 
-from glpi_python_client.clients import AsyncGlpiClient, GlpiClient, GLPIV1Session
+from glpi_python_client.clients import GlpiClient
 from glpi_python_client.models import (
-    GlpiDocument,
-    GlpiFollowup,
-    GlpiLocation,
-    GlpiSolution,
-    GlpiTask,
-    GlpiTeamMember,
-    GlpiTicket,
-    GlpiUser,
+    DeleteDocument,
+    DeleteEntity,
+    DeleteFollowup,
+    DeleteLocation,
+    DeleteSolution,
+    DeleteTeamMember,
+    DeleteTicket,
+    DeleteTicketTask,
+    DeleteTimelineDocument,
+    DeleteUser,
+    GetDocument,
+    GetEntity,
+    GetFollowup,
+    GetLocation,
+    GetSolution,
+    GetTeamMember,
+    GetTicket,
+    GetTicketTask,
+    GetTimelineDocument,
+    GetUser,
+    GlpiEnum,
+    GlpiGlobalValidation,
+    GlpiPriority,
+    GlpiSolutionStatus,
+    GlpiTaskState,
+    GlpiTicketContext,
+    GlpiTicketStatus,
+    GlpiTicketType,
+    GlpiTimelinePosition,
+    GlpiUserAuthType,
+    IdNameCompletenameRef,
+    IdNameRef,
+    IdRef,
+    PatchDocument,
+    PatchEntity,
+    PatchFollowup,
+    PatchLocation,
+    PatchSolution,
+    PatchTeamMember,
+    PatchTicket,
+    PatchTicketTask,
+    PatchTimelineDocument,
+    PatchUser,
+    PostDocument,
+    PostEntity,
+    PostFollowup,
+    PostLocation,
+    PostSolution,
+    PostTeamMember,
+    PostTicket,
+    PostTicketTask,
+    PostTimelineDocument,
+    PostUser,
 )
 
-__version__ = "0.1.3"
+__version__ = "0.2.1"
 
 __all__ = [
-    "AsyncGlpiClient",
-    "GLPIV1Session",
+    "DeleteDocument",
+    "DeleteEntity",
+    "DeleteFollowup",
+    "DeleteLocation",
+    "DeleteSolution",
+    "DeleteTeamMember",
+    "DeleteTicket",
+    "DeleteTicketTask",
+    "DeleteTimelineDocument",
+    "DeleteUser",
+    "GetDocument",
+    "GetEntity",
+    "GetFollowup",
+    "GetLocation",
+    "GetSolution",
+    "GetTeamMember",
+    "GetTicket",
+    "GetTicketTask",
+    "GetTimelineDocument",
+    "GetUser",
     "GlpiClient",
-    "GlpiDocument",
-    "GlpiFollowup",
-    "GlpiLocation",
-    "GlpiSolution",
-    "GlpiTask",
-    "GlpiTeamMember",
-    "GlpiTicket",
-    "GlpiUser",
+    "GlpiEnum",
+    "GlpiGlobalValidation",
+    "GlpiPriority",
+    "GlpiSolutionStatus",
+    "GlpiTaskState",
+    "GlpiTicketContext",
+    "GlpiTicketStatus",
+    "GlpiTicketType",
+    "GlpiTimelinePosition",
+    "GlpiUserAuthType",
+    "IdNameCompletenameRef",
+    "IdNameRef",
+    "IdRef",
+    "PatchDocument",
+    "PatchEntity",
+    "PatchFollowup",
+    "PatchLocation",
+    "PatchSolution",
+    "PatchTeamMember",
+    "PatchTicket",
+    "PatchTicketTask",
+    "PatchTimelineDocument",
+    "PatchUser",
+    "PostDocument",
+    "PostEntity",
+    "PostFollowup",
+    "PostLocation",
+    "PostSolution",
+    "PostTeamMember",
+    "PostTicket",
+    "PostTicketTask",
+    "PostTimelineDocument",
+    "PostUser",
     "__version__",
 ]

glpi_python_client/auth/__init__.py

@@ -1,11 +1,13 @@
 """Public authentication exports for the GLPI client package.
 
-The authentication package stays small on purpose and currently exposes the
-token manager used by the synchronous and asynchronous high-level clients.
+The authentication package owns the OAuth2 token manager used by the
+asynchronous ``GlpiClient`` and the legacy v1 session wrapper used solely by
+the management document upload mixin.
 """
 
 from __future__ import annotations
 
+from glpi_python_client.auth._v1_session import GLPIV1Session
 from glpi_python_client.auth.auth import GLPITokenManager
 
-__all__ = ["GLPITokenManager"]
+__all__ = ["GLPITokenManager", "GLPIV1Session"]

glpi_python_client/{clients/api_v1_session.py → auth/_v1_session.py}

@@ -1,8 +1,10 @@
-"""Legacy GLPI v1 session management and document operations.
+"""GLPI v1 REST session used exclusively for document uploads.
 
-The high-level package still relies on selected v1 endpoints for document
-upload and linking workflows, so this module owns the authenticated v1 HTTP
-session and the retry logic around it.
+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.
 """
 
 from __future__ import annotations
@@ -22,20 +24,11 @@ _AUTH_FAILURE_STATUS_CODES = frozenset({401, 403})
 
 
 class GLPIV1Session:
-    """Session manager for the GLPI v1 REST API.
-
-    Parameters
-    ----------
-    base_url : str
-        The v1 API base URL.
-    user_token : str
-        The ``user_token`` credential for v1 authentication.
-    app_token : str
-        The ``App-Token`` value.
-    verify_ssl : bool, optional
-        Whether to verify SSL certificates.
-    session_refresh_interval_seconds : int, optional
-        Maximum age of a v1 session token before it is renewed.
+    """Authenticated GLPI v1 REST session limited to document upload.
+
+    The session takes care of token initialisation, periodic refresh, retry on
+    auth failure, and best-effort cleanup. Only the upload endpoint is exposed
+    because the rest of the high-level client uses the v2 API exclusively.
     """
 
     def __init__(
@@ -68,17 +61,10 @@ class GLPIV1Session:
 
     @retry(stop=stop_after_attempt(3), wait=wait_fixed(3))
     def _init_session(self) -> None:
-        """Call ``GET /initSession`` to obtain a session token.
-
-        Returns
-        -------
-        None
-            Stores the session token.
+        """Acquire one fresh GLPI v1 session token via ``GET /initSession``.
 
-        Raises
-        ------
-        ValueError
-            If the server does not return a valid session token.
+        The call replaces any existing session state and stores the
+        authentication timestamp used by the refresh-interval check.
         """
 
         headers: dict[str, str] = {
@@ -109,12 +95,10 @@ class GLPIV1Session:
         logger.info("GLPI v1 session initialised.")
 
     def _ensure_session(self) -> None:
-        """Lazily initialise or renew the v1 session if needed.
+        """Lazily initialise or renew the v1 session when the token is stale.
 
-        Returns
-        -------
-        None
-            Ensures the session token exists.
+        The helper is called by every authenticated request before any header
+        construction so callers never have to manage the lifecycle directly.
         """
 
         if self._session_token is None:
@@ -125,13 +109,10 @@ class GLPIV1Session:
             self._renew_session()
 
     def _is_session_stale(self) -> bool:
-        """Return whether the current v1 session should be renewed.
+        """Return whether the current v1 session token must be renewed.
 
-        Returns
-        -------
-        bool
-            ``True`` when the session age is beyond the configured refresh
-            interval.
+        Stale tokens are determined by the configured refresh interval relative
+        to the timestamp the current token was acquired.
         """
 
         if self._session_started_at is None:
@@ -141,12 +122,10 @@ class GLPIV1Session:
         )
 
     def _session_headers(self) -> dict[str, str]:
-        """Return headers for the current v1 session token.
+        """Return the GLPI v1 headers carrying the current session token.
 
-        Returns
-        -------
-        dict[str, str]
-            Headers including the current session token.
+        The helper assumes ``_ensure_session`` has already been called so the
+        session token state is valid.
         """
 
         headers: dict[str, str] = {
@@ -158,12 +137,10 @@ class GLPIV1Session:
         return headers
 
     def _renew_session(self) -> None:
-        """Close the current v1 session token and initialise a new one.
+        """Drop the current GLPI v1 session token and acquire a new one.
 
-        Returns
-        -------
-        None
-            Mutates the stored session token.
+        The previous token is best-effort killed so the GLPI server can release
+        the associated session state immediately.
         """
 
         old_token = self._session_token
@@ -181,12 +158,10 @@ class GLPIV1Session:
         self._init_session()
 
     def _headers(self) -> dict[str, str]:
-        """Return headers for an authenticated v1 request.
+        """Return ready-to-use authenticated GLPI v1 request headers.
 
-        Returns
-        -------
-        dict[str, str]
-            Headers including the session token.
+        The helper is the single header entry-point used by all authenticated
+        v1 calls so token lifecycle handling stays centralised.
         """
 
         self._ensure_session()
@@ -200,23 +175,10 @@ class GLPIV1Session:
         headers: dict[str, str] | None = None,
         **kwargs: object,
     ) -> requests.Response:
-        """Execute one v1 request and retry once after auth rejection.
-
-        Parameters
-        ----------
-        method : str
-            HTTP method.
-        url : str
-            Absolute request URL.
-        headers : dict[str, str] | None, optional
-            Additional request headers.
-        **kwargs : object
-            Additional ``requests`` keyword arguments.
-
-        Returns
-        -------
-        requests.Response
-            Raw response from GLPI.
+        """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.
         """
 
         request_headers = {**self._headers(), **(headers or {})}
@@ -239,63 +201,11 @@ class GLPIV1Session:
             request_method(url, headers=request_headers, **kwargs),
         )
 
-    @retry(stop=stop_after_attempt(3), wait=wait_fixed(3))
-    def get_sub_items(
-        self,
-        itemtype: str,
-        item_id: str | int,
-        sub_itemtype: str,
-    ) -> list[dict[str, object]]:
-        """Fetch legacy GLPI sub-items for one parent item.
-
-        Parameters
-        ----------
-        itemtype : str
-            Parent GLPI itemtype.
-        item_id : str | int
-            Parent item identifier.
-        sub_itemtype : str
-            Child itemtype to fetch.
-
-        Returns
-        -------
-        list[dict[str, object]]
-            Raw sub-item payloads.
-
-        Raises
-        ------
-        ValueError
-            If the request fails or returns an unexpected payload shape.
-        """
-
-        response = self._authenticated_request(
-            "GET",
-            f"{self._base_url}/{itemtype}/{item_id}/{sub_itemtype}",
-            timeout=30,
-        )
-        if response.status_code not in (200, 206):
-            raise ValueError(
-                "GLPI v1 sub-item fetch failed: "
-                f"{response.status_code} {response.text[:300]}"
-            )
-
-        payload = response.json()
-        if isinstance(payload, list):
-            return [item for item in payload if isinstance(item, dict)]
-        if isinstance(payload, dict):
-            return [payload]
-        raise ValueError(
-            "GLPI v1 sub-item fetch returned unexpected payload: "
-            f"{type(payload).__name__}"
-        )
-
     def close(self) -> None:
-        """Kill the v1 session and release resources.
+        """Kill the v1 session token and release the underlying HTTP session.
 
-        Returns
-        -------
-        None
-            Best-effort cleanup.
+        Cleanup is best-effort: any failure during ``killSession`` is logged
+        and the local session state is still cleared.
         """
 
         try:
@@ -324,32 +234,11 @@ class GLPIV1Session:
         ticket_id: int | None = None,
         entity_id: int | None = None,
     ) -> dict[str, object]:
-        """Upload a document via ``POST /Document``.
-
-        Parameters
-        ----------
-        filename : str
-            File name.
-        content : bytes
-            Raw file bytes.
-        mime_type : str
-            MIME type.
-        document_name : str | None, optional
-            GLPI display name.
-        ticket_id : int | None, optional
-            GLPI ticket ID used to link the document during creation.
-        entity_id : int | None, optional
-            GLPI entity ID assigned to the created document.
-
-        Returns
-        -------
-        dict[str, object]
-            GLPI response payload.
-
-        Raises
-        ------
-        ValueError
-            If upload fails.
+        """Upload one binary document via ``POST /Document``.
+
+        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.
         """
 
         manifest_input: dict[str, object] = {
@@ -386,75 +275,17 @@ class GLPIV1Session:
         logger.info("GLPI v1 document uploaded: id=%s", payload.get("id"))
         return cast(dict[str, object], payload)
 
-    @retry(stop=stop_after_attempt(3), wait=wait_fixed(3))
-    def link_document_to_ticket(
-        self, document_id: int, ticket_id: int
-    ) -> dict[str, object]:
-        """Link an existing document to a ticket.
-
-        Parameters
-        ----------
-        document_id : int
-            GLPI document ID.
-        ticket_id : int
-            GLPI ticket ID.
-
-        Returns
-        -------
-        dict[str, object]
-            GLPI response payload.
-
-        Raises
-        ------
-        ValueError
-            If the link creation fails.
-        """
-
-        payload = json.dumps(
-            {
-                "input": {
-                    "documents_id": document_id,
-                    "itemtype": "Ticket",
-                    "items_id": ticket_id,
-                }
-            }
-        )
-        response = self._authenticated_request(
-            "POST",
-            f"{self._base_url}/Document_Item",
-            headers={"Content-Type": "application/json"},
-            data=payload,
-            timeout=30,
-        )
-        if response.status_code not in (200, 201):
-            raise ValueError(
-                "GLPI v1 Document_Item link failed: "
-                f"{response.status_code} {response.text[:300]}"
-            )
-        result = response.json()
-        if not isinstance(result, dict):
-            raise ValueError(
-                "GLPI v1 Document_Item link returned unexpected payload: "
-                f"{type(result).__name__}"
-            )
-        logger.info("GLPI v1 document %d linked to ticket %d", document_id, ticket_id)
-        return cast(dict[str, object], result)
-
 
 def _is_auth_failure_response(response: requests.Response) -> bool:
-    """Return whether one GLPI v1 response means the session is invalid.
-
-    Parameters
-    ----------
-    response : requests.Response
-        Raw GLPI response.
+    """Return whether one GLPI v1 response means the session token is invalid.
 
-    Returns
-    -------
-    bool
-        ``True`` when the response indicates an expired or rejected v1 session.
+    Both HTTP-level rejection and the ``ERROR_SESSION_TOKEN_INVALID`` payload
+    marker emitted by the GLPI v1 API are considered auth failures.
     """
 
     if response.status_code in _AUTH_FAILURE_STATUS_CODES:
         return True
     return "ERROR_SESSION_TOKEN_INVALID" in str(response.text or "")
+
+
+__all__ = ["GLPIV1Session"]