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

glpi_python_client/__init__.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 from glpi_python_client._async.clients import AsyncGlpiClient
 from glpi_python_client._errors import (
     GlpiAuthError,
+    GlpiContentError,
     GlpiError,
     GlpiNotFoundError,
     GlpiProtocolError,
@@ -31,6 +32,11 @@ from glpi_python_client._errors import (
 )
 from glpi_python_client._sync.clients import GlpiClient
 from glpi_python_client.models import (
+    DeleteComputer,
+    DeleteContract,
+    DeleteContractCost,
+    DeleteContractItem,
+    DeleteContractType,
     DeleteDocument,
     DeleteEntity,
     DeleteFollowup,
@@ -44,6 +50,11 @@ from glpi_python_client.models import (
     DeleteTicketTask,
     DeleteTimelineDocument,
     DeleteUser,
+    GetComputer,
+    GetContract,
+    GetContractCost,
+    GetContractItem,
+    GetContractType,
     GetDocument,
     GetEntity,
     GetFollowup,
@@ -61,6 +72,7 @@ from glpi_python_client.models import (
     GetTicketTask,
     GetTimelineDocument,
     GetUser,
+    GlpiContractRenewalType,
     GlpiEnum,
     GlpiGlobalValidation,
     GlpiPriority,
@@ -74,6 +86,11 @@ from glpi_python_client.models import (
     IdNameCompletenameRef,
     IdNameRef,
     IdRef,
+    PatchComputer,
+    PatchContract,
+    PatchContractCost,
+    PatchContractItem,
+    PatchContractType,
     PatchDocument,
     PatchEntity,
     PatchFollowup,
@@ -87,6 +104,11 @@ from glpi_python_client.models import (
     PatchTicketTask,
     PatchTimelineDocument,
     PatchUser,
+    PostComputer,
+    PostContract,
+    PostContractCost,
+    PostContractItem,
+    PostContractType,
     PostDocument,
     PostEntity,
     PostFollowup,
@@ -109,10 +131,15 @@ from glpi_python_client.rsql import (
     date_window,
 )
 
-__version__ = "0.4.3"
+__version__ = "0.6.0"
 
 __all__ = [
     "AsyncGlpiClient",
+    "DeleteComputer",
+    "DeleteContract",
+    "DeleteContractCost",
+    "DeleteContractItem",
+    "DeleteContractType",
     "DeleteDocument",
     "DeleteEntity",
     "DeleteFollowup",
@@ -126,6 +153,11 @@ __all__ = [
     "DeleteTicketTask",
     "DeleteTimelineDocument",
     "DeleteUser",
+    "GetComputer",
+    "GetContract",
+    "GetContractCost",
+    "GetContractItem",
+    "GetContractType",
     "GetDocument",
     "GetEntity",
     "GetFollowup",
@@ -145,6 +177,8 @@ __all__ = [
     "GetUser",
     "GlpiAuthError",
     "GlpiClient",
+    "GlpiContentError",
+    "GlpiContractRenewalType",
     "GlpiEnum",
     "GlpiError",
     "GlpiGlobalValidation",
@@ -166,6 +200,11 @@ __all__ = [
     "IdNameCompletenameRef",
     "IdNameRef",
     "IdRef",
+    "PatchComputer",
+    "PatchContract",
+    "PatchContractCost",
+    "PatchContractItem",
+    "PatchContractType",
     "PatchDocument",
     "PatchEntity",
     "PatchFollowup",
@@ -179,6 +218,11 @@ __all__ = [
     "PatchTicketTask",
     "PatchTimelineDocument",
     "PatchUser",
+    "PostComputer",
+    "PostContract",
+    "PostContractCost",
+    "PostContractItem",
+    "PostContractType",
     "PostDocument",
     "PostEntity",
     "PostFollowup",

glpi_python_client/_async/auth/_v1_session.py

@@ -37,7 +37,7 @@ from __future__ import annotations
 
 import json
 import logging
-from datetime import datetime, timedelta, timezone
+from datetime import UTC, datetime, timedelta
 from typing import Any, cast
 
 import httpx
@@ -170,7 +170,7 @@ class GLPIV1Session:
             raise GlpiProtocolError("GLPI v1 initSession returned no session_token")
 
         self._session_token = str(token)
-        self._session_started_at = datetime.now(tz=timezone.utc)
+        self._session_started_at = datetime.now(tz=UTC)
         logger.info("GLPI v1 session initialised.")
 
     async def _ensure_session(self) -> None:
@@ -196,7 +196,7 @@ class GLPIV1Session:
 
         if self._session_started_at is None:
             return True
-        return datetime.now(tz=timezone.utc) >= (
+        return datetime.now(tz=UTC) >= (
             self._session_started_at + self._session_refresh_interval
         )
 

glpi_python_client/_async/auth/auth.py

@@ -8,7 +8,7 @@ share the same authenticated session state.
 from __future__ import annotations
 
 import logging
-from datetime import datetime, timedelta, timezone
+from datetime import UTC, datetime, timedelta
 
 import httpx
 from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_fixed
@@ -241,7 +241,7 @@ class GLPITokenManager:
         if refresh_token:
             self.refresh_token = refresh_token
         expires_in = int(str(token_data.get("expires_in") or 3600))
-        now = datetime.now(tz=timezone.utc)
+        now = datetime.now(tz=UTC)
         self.token_updated_at = now
         self.token_expires_at = now + timedelta(seconds=expires_in)
         logger.info("GLPI OAuth token %s successfully.", label)
@@ -399,7 +399,7 @@ class GLPITokenManager:
             await self._acquire_token()
             return
 
-        now = datetime.now(tz=timezone.utc)
+        now = datetime.now(tz=UTC)
         token_expired = (
             self.token_expires_at is not None and now >= self.token_expires_at
         )

glpi_python_client/_async/clients/_base_client.py

@@ -13,13 +13,7 @@ from __future__ import annotations
 
 import logging
 import os
-import sys
-from typing import TYPE_CHECKING
-
-if sys.version_info >= (3, 11):
-    from typing import Self
-else:  # pragma: no cover - fallback for Python 3.10
-    from typing_extensions import Self
+from typing import TYPE_CHECKING, Self
 
 from glpi_python_client._async._concurrency import Lock
 from glpi_python_client._async.clients.commons._config import (

glpi_python_client/_async/clients/api/__init__.py

@@ -1,7 +1,7 @@
 """Per-endpoint API mixins backed by the ``api_schema`` Pydantic models.
 
 The mixins under this package mirror the endpoints documented in
-``docs/glpi_api_contract.json`` one for one. They wrap the
+``docs/api_contract/api.json`` one for one. They wrap the
 transport helpers from :mod:`glpi_python_client._async.clients.commons` and exchange
 typed ``Get<Name>``, ``Post<Name>``, ``Patch<Name>``, and ``Delete<Name>``
 models with the GLPI API.
@@ -13,6 +13,7 @@ from glpi_python_client._async.clients.api.administration import (
     EntityMixin,
     UserMixin,
 )
+from glpi_python_client._async.clients.api.assets import ComputerMixin
 from glpi_python_client._async.clients.api.assistance import (
     TeamMemberMixin,
     TicketMixin,
@@ -23,19 +24,28 @@ from glpi_python_client._async.clients.api.assistance.timeline import (
     TicketTaskMixin,
     TimelineDocumentMixin,
 )
-from glpi_python_client._async.clients.api.dropdowns import LocationMixin
+from glpi_python_client._async.clients.api.dropdowns import (
+    ContractTypeMixin,
+    LocationMixin,
+)
 from glpi_python_client._async.clients.api.knowledgebase import (
     KBArticleCommentMixin,
     KBArticleMixin,
     KBArticleRevisionMixin,
     KBCategoryMixin,
 )
-from glpi_python_client._async.clients.api.management import DocumentMixin
+from glpi_python_client._async.clients.api.management import (
+    ContractMixin,
+    DocumentMixin,
+)
 from glpi_python_client._async.clients.api.plugins import (
     PluginFieldsMixin,
 )
 
 __all__ = [
+    "ComputerMixin",
+    "ContractMixin",
+    "ContractTypeMixin",
     "DocumentMixin",
     "EntityMixin",
     "FollowupMixin",

glpi_python_client/_async/clients/api/assets/__init__.py

@@ -0,0 +1,7 @@
+"""GLPI ``/Assets`` mixins for the GLPI client."""
+
+from __future__ import annotations
+
+from glpi_python_client._async.clients.api.assets._computer import ComputerMixin
+
+__all__ = ["ComputerMixin"]

glpi_python_client/_async/clients/api/assets/_computer.py

@@ -0,0 +1,427 @@
+"""GLPI ``/Assets/Computer`` mixin.
+
+The mixin exposes search, fetch, create, update, and delete helpers for the
+GLPI computer resource using the contract-aligned ``api_schema`` models. It
+also exposes CRUD helpers for the ``/Assets/Computer/{id}/Contract``
+sub-resource, the join answering which contracts cover a given computer.
+
+``link_computer_contract`` and ``update_computer_contract`` set ``itemtype``
+and ``items_id`` themselves rather than trusting the caller-supplied values
+on the request body; see ``models/api_schema/assets/_contract_item.py`` for
+why.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+
+from glpi_python_client._async.clients.commons._constants import (
+    COMPUTER_ENDPOINT,
+    GlpiId,
+)
+from glpi_python_client._async.clients.commons._transport import TransportMixin
+from glpi_python_client.models.api_schema.assets._computer import (
+    DeleteComputer,
+    GetComputer,
+    PatchComputer,
+    PostComputer,
+)
+from glpi_python_client.models.api_schema.assets._contract_item import (
+    DeleteContractItem,
+    GetContractItem,
+    PatchContractItem,
+    PostContractItem,
+)
+
+
+class ComputerMixin(TransportMixin):
+    """CRUD helpers for ``/Assets/Computer``."""
+
+    async def search_computers(
+        self,
+        rsql_filter: str = "",
+        *,
+        limit: int = 50,
+        start: int = 0,
+        sort: str | None = None,
+    ) -> list[GetComputer]:
+        """Search GLPI computers with an optional RSQL filter.
+
+        Parameters
+        ----------
+        rsql_filter : str, optional
+            Raw RSQL filter forwarded as the ``filter`` query parameter.
+        limit : int, optional
+            Maximum number of records returned by the GLPI server.
+        start : int, optional
+            Zero-based offset of the first record returned.
+        sort : str | None, optional
+            Server-side ordering expressed as ``"<field>:<direction>"``,
+            for example ``"date_mod:desc"``. Omitted when :data:`None`,
+            leaving the server default ordering in place.
+
+        Returns
+        -------
+        list[GetComputer]
+            Computers matching the filter.
+        """
+
+        params: dict[str, object] = {"limit": limit, "start": start}
+        if rsql_filter:
+            params["filter"] = rsql_filter
+        if sort is not None:
+            params["sort"] = sort
+        return await self._resource_list(COMPUTER_ENDPOINT, GetComputer, params=params)
+
+    async def iter_search_computers(
+        self,
+        rsql_filter: str = "",
+        *,
+        batch_size: int = 50,
+        sort: str | None = None,
+    ) -> AsyncIterator[list[GetComputer]]:
+        """Yield successive pages of GLPI computers 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_computers`
+            call.
+        sort : str | None, optional
+            Server-side ordering expressed as ``"<field>:<direction>"``,
+            for example ``"date_mod:desc"``. Forwarded to each page
+            request; omitted when :data:`None`, leaving the server default
+            ordering in place.
+
+        Yields
+        ------
+        list[GetComputer]
+            One page per iteration. The last yielded batch may be shorter
+            than ``batch_size``.
+        """
+
+        start = 0
+        while True:
+            batch = await self.search_computers(
+                rsql_filter,
+                limit=batch_size,
+                start=start,
+                sort=sort,
+            )
+            if batch:
+                yield batch
+            if len(batch) < batch_size:
+                break
+            start += batch_size
+
+    async def get_computer(self, computer_id: GlpiId) -> GetComputer:
+        """Fetch one GLPI computer by identifier.
+
+        Parameters
+        ----------
+        computer_id : GlpiId
+            Numeric identifier of the computer to retrieve.
+
+        Returns
+        -------
+        GetComputer
+            Validated computer payload.
+
+        Raises
+        ------
+        GlpiStatusError
+            If the GLPI server returns a non-success HTTP status.
+        """
+
+        return await self._resource_get(
+            f"{COMPUTER_ENDPOINT}/{computer_id}",
+            GetComputer,
+            failure_message=f"Failed to get computer {computer_id}",
+        )
+
+    async def create_computer(self, computer: PostComputer) -> int:
+        """Create one GLPI computer.
+
+        Parameters
+        ----------
+        computer : PostComputer
+            Request body describing the computer to create.
+
+        Returns
+        -------
+        int
+            Identifier assigned by the GLPI server.
+
+        Raises
+        ------
+        GlpiStatusError
+            If the GLPI server returns a non-success HTTP status.
+        GlpiProtocolError
+            If the create response is missing the ``id`` field.
+        """
+
+        return await self._resource_create(
+            COMPUTER_ENDPOINT,
+            computer,
+            failure_message="Failed to create computer",
+            missing_message="GLPI computer create response did not include an ID",
+            log_message_factory=(lambda new_id: f"GLPI API created computer {new_id}"),
+        )
+
+    async def update_computer(
+        self, computer_id: GlpiId, computer: PatchComputer
+    ) -> None:
+        """Update one GLPI computer with a partial body.
+
+        Parameters
+        ----------
+        computer_id : GlpiId
+            Numeric identifier of the computer to update.
+        computer : PatchComputer
+            Partial request body.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        GlpiStatusError
+            If the GLPI server returns a non-success HTTP status.
+        """
+
+        await self._resource_update(
+            f"{COMPUTER_ENDPOINT}/{computer_id}",
+            computer,
+            failure_message=f"Failed to update computer {computer_id}",
+            log_message=f"GLPI API updated computer {computer_id}",
+        )
+
+    async def delete_computer(
+        self, computer_id: GlpiId, *, force: bool | None = None
+    ) -> None:
+        """Delete one GLPI computer by identifier.
+
+        Parameters
+        ----------
+        computer_id : GlpiId
+            Numeric identifier of the computer to delete.
+        force : bool | None, optional
+            When ``True`` the computer is permanently deleted instead of
+            being moved to the trash.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        GlpiStatusError
+            If the GLPI server returns a non-success HTTP status.
+        """
+
+        await self._resource_delete(
+            f"{COMPUTER_ENDPOINT}/{computer_id}",
+            failure_message=f"Failed to delete computer {computer_id}",
+            log_message=f"GLPI API deleted computer {computer_id}",
+            force=force,
+            delete_model_cls=DeleteComputer,
+        )
+
+    async def list_computer_contracts(
+        self,
+        computer_id: GlpiId,
+        *,
+        limit: int = 50,
+        start: int = 0,
+    ) -> list[GetContractItem]:
+        """List the contracts linked to one GLPI computer.
+
+        Parameters
+        ----------
+        computer_id : GlpiId
+            Numeric identifier of the owning computer.
+        limit : int, optional
+            Maximum number of records returned by the GLPI server.
+        start : int, optional
+            Zero-based offset of the first record returned.
+
+        Returns
+        -------
+        list[GetContractItem]
+            Contract links belonging to the computer.
+        """
+
+        params: dict[str, object] = {"limit": limit, "start": start}
+        return await self._resource_list(
+            f"{COMPUTER_ENDPOINT}/{computer_id}/Contract",
+            GetContractItem,
+            params=params,
+        )
+
+    async def get_computer_contract(
+        self, computer_id: GlpiId, link_id: GlpiId
+    ) -> GetContractItem:
+        """Fetch one contract link recorded against a GLPI computer.
+
+        Parameters
+        ----------
+        computer_id : GlpiId
+            Numeric identifier of the owning computer.
+        link_id : GlpiId
+            Numeric identifier of the contract link to retrieve.
+
+        Returns
+        -------
+        GetContractItem
+            Validated contract link payload.
+
+        Raises
+        ------
+        GlpiStatusError
+            If the GLPI server returns a non-success HTTP status.
+        """
+
+        return await self._resource_get(
+            f"{COMPUTER_ENDPOINT}/{computer_id}/Contract/{link_id}",
+            GetContractItem,
+            failure_message=(
+                f"Failed to get contract link {link_id} for computer {computer_id}"
+            ),
+        )
+
+    async def link_computer_contract(
+        self, computer_id: GlpiId, link: PostContractItem
+    ) -> int:
+        """Link one GLPI contract to one computer.
+
+        The ``itemtype`` and ``items_id`` fields are set from
+        ``computer_id`` rather than taken from ``link``. The GLPI contract
+        types ``itemtype`` as a free string, so a caller-supplied value is
+        a silent mis-link waiting to happen; this helper already knows
+        which asset it is working on.
+
+        Parameters
+        ----------
+        computer_id : GlpiId
+            Numeric identifier of the computer the contract covers.
+        link : PostContractItem
+            Request body naming the contract to link. Any ``itemtype`` or
+            ``items_id`` set on it is replaced.
+
+        Returns
+        -------
+        int
+            Identifier assigned to the new link by the GLPI server.
+
+        Raises
+        ------
+        GlpiStatusError
+            If the GLPI server returns a non-success HTTP status.
+        GlpiProtocolError
+            If the create response is missing the ``id`` field.
+        """
+
+        body = link.model_copy(update={"itemtype": "Computer", "items_id": computer_id})
+        return await self._resource_create(
+            f"{COMPUTER_ENDPOINT}/{computer_id}/Contract",
+            body,
+            failure_message=f"Failed to link a contract to computer {computer_id}",
+            missing_message=(
+                "GLPI contract link create response did not include an ID"
+            ),
+            log_message_factory=(
+                lambda new_id: (
+                    f"GLPI API linked contract item {new_id} to computer {computer_id}"
+                )
+            ),
+        )
+
+    async def update_computer_contract(
+        self, computer_id: GlpiId, link_id: GlpiId, link: PatchContractItem
+    ) -> None:
+        """Update one computer-contract link with a partial body.
+
+        The ``itemtype`` and ``items_id`` fields are set from
+        ``computer_id`` rather than taken from ``link``, for the same
+        reason as :meth:`link_computer_contract`.
+
+        Parameters
+        ----------
+        computer_id : GlpiId
+            Numeric identifier of the owning computer.
+        link_id : GlpiId
+            Numeric identifier of the contract link to update.
+        link : PatchContractItem
+            Partial request body. Any ``itemtype`` or ``items_id`` set on
+            it is replaced.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        GlpiStatusError
+            If the GLPI server returns a non-success HTTP status.
+        """
+
+        body = link.model_copy(update={"itemtype": "Computer", "items_id": computer_id})
+        await self._resource_update(
+            f"{COMPUTER_ENDPOINT}/{computer_id}/Contract/{link_id}",
+            body,
+            failure_message=(
+                f"Failed to update contract link {link_id} for computer {computer_id}"
+            ),
+            log_message=(
+                f"GLPI API updated contract link {link_id} for computer {computer_id}"
+            ),
+        )
+
+    async def unlink_computer_contract(
+        self, computer_id: GlpiId, link_id: GlpiId, *, force: bool | None = None
+    ) -> None:
+        """Remove one contract link from a GLPI computer.
+
+        Parameters
+        ----------
+        computer_id : GlpiId
+            Numeric identifier of the owning computer.
+        link_id : GlpiId
+            Numeric identifier of the contract link to remove.
+        force : bool | None, optional
+            When ``True`` the link is permanently deleted instead of
+            being moved to the trash.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        GlpiStatusError
+            If the GLPI server returns a non-success HTTP status.
+        """
+
+        await self._resource_delete(
+            f"{COMPUTER_ENDPOINT}/{computer_id}/Contract/{link_id}",
+            failure_message=(
+                f"Failed to unlink contract link {link_id} from computer {computer_id}"
+            ),
+            log_message=(
+                f"GLPI API unlinked contract link {link_id} from computer {computer_id}"
+            ),
+            force=force,
+            delete_model_cls=DeleteContractItem,
+        )
+
+
+__all__ = ["ComputerMixin"]

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

@@ -2,6 +2,9 @@
 
 from __future__ import annotations
 
+from glpi_python_client._async.clients.api.dropdowns._contract_type import (
+    ContractTypeMixin,
+)
 from glpi_python_client._async.clients.api.dropdowns._location import LocationMixin
 
-__all__ = ["LocationMixin"]
+__all__ = ["ContractTypeMixin", "LocationMixin"]