glpi-python-client 0.1.0__py3-none-any.whl

glpi_python_client/__init__.py

@@ -0,0 +1,36 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+from glpi_python_client.clients import AsyncGlpiClient, GlpiClient, GLPIV1Session
+from glpi_python_client.models import (
+    GlpiDocument,
+    GlpiFollowup,
+    GlpiLocation,
+    GlpiSolution,
+    GlpiTask,
+    GlpiTeamMember,
+    GlpiTicket,
+    GlpiUser,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncGlpiClient",
+    "GLPIV1Session",
+    "GlpiClient",
+    "GlpiDocument",
+    "GlpiFollowup",
+    "GlpiLocation",
+    "GlpiSolution",
+    "GlpiTask",
+    "GlpiTeamMember",
+    "GlpiTicket",
+    "GlpiUser",
+    "__version__",
+]

glpi_python_client/auth/__init__.py

@@ -0,0 +1,11 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+from glpi_python_client.auth.auth import GLPITokenManager
+
+__all__ = ["GLPITokenManager"]

glpi_python_client/auth/auth.py

@@ -0,0 +1,310 @@
+"""OAuth2 token management for the high-level GLPI clients.
+
+The token manager centralizes credential validation, token acquisition,
+refresh behavior, and lifecycle cleanup so both sync and async clients can
+share the same authenticated session state.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta, timezone
+
+import requests
+from tenacity import retry, stop_after_attempt, wait_fixed
+
+logger = logging.getLogger(__name__)
+
+
+class GLPITokenManager:
+    """OAuth2 token manager for the GLPI API.
+
+    Parameters
+    ----------
+    token_url : str
+        Full URL of the GLPI token endpoint.
+    client_id : str | None, optional
+        OAuth2 client ID. Provide it together with ``client_secret`` when the
+        GLPI instance requires client authentication.
+    client_secret : str | None, optional
+        OAuth2 client secret. Provide it together with ``client_id``.
+    username : str | None, optional
+        Username for the password grant flow. Provide it together with
+        ``password``.
+    password : str | None, optional
+        Password for the password grant flow. Provide it together with
+        ``username``.
+    session : requests.Session | None, optional
+        Existing session to reuse.
+    auth_token_refresh : int | None, optional
+        Maximum token age in seconds before a refresh is attempted. ``None``
+        disables interval-based refreshes.
+    """
+
+    def __init__(
+        self,
+        token_url: str,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        username: str | None = None,
+        password: str | None = None,
+        session: requests.Session | None = None,
+        auth_token_refresh: int | None = None,
+    ) -> None:
+        self._token_url = token_url
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._username = username
+        self._password = password
+        self._owns_session = session is None
+        self._session = session or requests.Session()
+        self._auth_token_refresh_interval = _refresh_interval(auth_token_refresh)
+
+        self._validate_credentials()
+
+        self.access_token: str | None = None
+        self.refresh_token: str | None = None
+        self.token_expires_at: datetime | None = None
+        self.token_updated_at: datetime | None = None
+
+    @property
+    def auth_token_refresh(self) -> int | None:
+        """Return the proactive refresh delay configured for this manager.
+
+        The public property keeps the original integer value used at
+        construction time instead of exposing the internal ``timedelta``
+        representation.
+        """
+
+        if self._auth_token_refresh_interval is None:
+            return None
+        return int(self._auth_token_refresh_interval.total_seconds())
+
+    def _validate_credentials(self) -> None:
+        """Validate that the configured OAuth credential sets are complete.
+
+        GLPI authentication supports either client credentials, user
+        credentials, or both together. Partial pairs are rejected here so the
+        token request path does not fail later with a less actionable error.
+        """
+
+        missing_client_fields = [
+            name
+            for name, value in {
+                "client_id": self._client_id,
+                "client_secret": self._client_secret,
+            }.items()
+            if value is None
+        ]
+        missing_user_fields = [
+            name
+            for name, value in {
+                "username": self._username,
+                "password": self._password,
+            }.items()
+            if value is None
+        ]
+
+        has_client_fields = len(missing_client_fields) < 2
+        has_user_fields = len(missing_user_fields) < 2
+
+        if has_client_fields and missing_client_fields:
+            raise ValueError(
+                "GLPI OAuth client credentials must include both client_id "
+                "and client_secret."
+            )
+        if has_user_fields and missing_user_fields:
+            raise ValueError(
+                "GLPI user credentials must include both username and password."
+            )
+        if not self._has_client_credentials and not self._has_user_credentials:
+            raise ValueError(
+                "GLPI authentication requires either client_id/client_secret, "
+                "username/password, or both."
+            )
+
+    @property
+    def _has_client_credentials(self) -> bool:
+        return self._client_id is not None and self._client_secret is not None
+
+    @property
+    def _has_user_credentials(self) -> bool:
+        return self._username is not None and self._password is not None
+
+    def _build_token_request_data(self) -> dict[str, str]:
+        """Build the form payload sent to the OAuth token endpoint.
+
+        The payload shape depends on whether the manager is using the password
+        grant or pure client-credentials flow, and it includes client
+        credentials when that pair is configured.
+        """
+
+        data: dict[str, str] = {"scope": "api"}
+        if self._has_user_credentials:
+            assert self._username is not None
+            assert self._password is not None
+            data["grant_type"] = "password"
+            data["username"] = self._username
+            data["password"] = self._password
+        else:
+            data["grant_type"] = "client_credentials"
+
+        if self._has_client_credentials:
+            assert self._client_id is not None
+            assert self._client_secret is not None
+            data["client_id"] = self._client_id
+            data["client_secret"] = self._client_secret
+
+        return data
+
+    def _store_token_data(
+        self, token_data: dict[str, object], label: str = "acquired"
+    ) -> None:
+        """Store token data from an OAuth2 response.
+
+        Parameters
+        ----------
+        token_data : dict[str, object]
+            Token endpoint JSON response.
+        label : str, optional
+            Label for log messages.
+
+        Returns
+        -------
+        None
+            Mutates instance state.
+        """
+
+        self.access_token = str(token_data.get("access_token") or "") or None
+        refresh_token = str(token_data.get("refresh_token") or "").strip()
+        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)
+        self.token_updated_at = now
+        self.token_expires_at = now + timedelta(seconds=expires_in)
+        logger.info("GLPI OAuth token %s successfully.", label)
+
+    def logout(self) -> None:
+        """Discard the currently cached OAuth tokens.
+
+        Returns
+        -------
+        None
+            Clears in-memory token state.
+        """
+
+        self.access_token = None
+        self.refresh_token = None
+        self.token_expires_at = None
+        self.token_updated_at = None
+
+    def close(self) -> None:
+        """Release token-manager resources.
+
+        Returns
+        -------
+        None
+            Performs a local logout and closes any owned HTTP session.
+        """
+
+        self.logout()
+        if self._owns_session:
+            self._session.close()
+
+    def _should_refresh_by_interval(self, now: datetime) -> bool:
+        """Return whether the configured proactive refresh interval elapsed.
+
+        This check supplements token-expiry handling so long-lived clients can
+        refresh credentials before the server-side expiry timestamp is reached.
+        """
+
+        if self._auth_token_refresh_interval is None or self.token_updated_at is None:
+            return False
+        return now >= self.token_updated_at + self._auth_token_refresh_interval
+
+    @retry(stop=stop_after_attempt(3), wait=wait_fixed(3))
+    def _acquire_token(self) -> None:
+        """Acquire an OAuth2 access token using the configured auth flow.
+
+        Returns
+        -------
+        None
+            Stores the new access token.
+
+        Raises
+        ------
+        ValueError
+            If token acquisition fails.
+        """
+
+        data = self._build_token_request_data()
+        response = self._session.post(self._token_url, data=data, timeout=30)
+        if 200 <= response.status_code < 300:
+            self._store_token_data(response.json())
+            return
+        try:
+            error_detail = response.json()
+        except Exception:
+            error_detail = response.text
+        raise ValueError(
+            f"GLPI OAuth token returned {response.status_code}: {error_detail}"
+        )
+
+    @retry(stop=stop_after_attempt(3), wait=wait_fixed(3))
+    def _refresh_access_token(self) -> None:
+        """Refresh the OAuth2 access token using the stored refresh token.
+
+        Returns
+        -------
+        None
+            Stores the refreshed token or acquires a new one.
+        """
+
+        if not self.refresh_token:
+            self._acquire_token()
+            return
+
+        data = {
+            "grant_type": "refresh_token",
+            "refresh_token": self.refresh_token,
+        }
+        if self._has_client_credentials:
+            assert self._client_id is not None
+            assert self._client_secret is not None
+            data["client_id"] = self._client_id
+            data["client_secret"] = self._client_secret
+        response = self._session.post(self._token_url, data=data, timeout=30)
+        if 200 <= response.status_code < 300:
+            self._store_token_data(response.json(), label="refreshed")
+            return
+        logger.warning("Token refresh failed, acquiring new token...")
+        self._acquire_token()
+
+    def ensure_token(self) -> None:
+        """Ensure a valid OAuth2 access token is available.
+
+        Returns
+        -------
+        None
+            Updates token state when needed.
+        """
+
+        if not self.access_token:
+            self._acquire_token()
+            return
+
+        now = datetime.now(tz=timezone.utc)
+        token_expired = (
+            self.token_expires_at is not None and now >= self.token_expires_at
+        )
+        if token_expired or self._should_refresh_by_interval(now):
+            self._refresh_access_token()
+
+
+def _refresh_interval(value: int | None) -> timedelta | None:
+    if value is None:
+        return None
+    if value < 1:
+        raise ValueError("auth_token_refresh must be a positive integer or None")
+    return timedelta(seconds=value)

glpi_python_client/auth/tests/test_auth.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import cast
+
+import pytest
+import requests
+
+from glpi_python_client.auth.auth import GLPITokenManager
+from glpi_python_client.testing.utils import FakeResponse, TokenResponse
+
+
+class _FakeSession:
+    def __init__(self, response: FakeResponse | None = None):
+        self.response = response or TokenResponse()
+        self.calls: list[dict[str, object]] = []
+
+    def post(
+        self,
+        url: str,
+        data: dict[str, str],
+        timeout: int,
+    ) -> FakeResponse:
+        self.calls.append({"url": url, "data": data, "timeout": timeout})
+        return self.response
+
+
+def test_token_manager_uses_password_grant_with_user_credentials_only() -> None:
+    session = _FakeSession()
+    auth = GLPITokenManager(
+        token_url="https://glpi.example.test/api.php/token",
+        username="api-user",
+        password="api-password",
+        session=cast(requests.Session, session),
+    )
+
+    auth._acquire_token()
+
+    assert session.calls[0]["data"] == {
+        "grant_type": "password",
+        "username": "api-user",
+        "password": "api-password",
+        "scope": "api",
+    }
+    assert auth.access_token == "token"
+
+
+def test_token_manager_uses_client_credentials_grant() -> None:
+    session = _FakeSession(response=TokenResponse(status_code=201))
+    auth = GLPITokenManager(
+        token_url="https://glpi.example.test/api.php/token",
+        client_id="client-id",
+        client_secret="client-secret",
+        session=cast(requests.Session, session),
+    )
+
+    auth._acquire_token()
+
+    assert session.calls[0]["data"] == {
+        "grant_type": "client_credentials",
+        "client_id": "client-id",
+        "client_secret": "client-secret",
+        "scope": "api",
+    }
+    assert auth.access_token == "token"
+
+
+def test_token_manager_preserves_raw_credential_text() -> None:
+    session = _FakeSession(response=TokenResponse(status_code=201))
+    auth = GLPITokenManager(
+        token_url="https://glpi.example.test/api.php/token",
+        client_id="  client-id  ",
+        client_secret="  client-secret  ",
+        session=cast(requests.Session, session),
+    )
+
+    auth._acquire_token()
+
+    assert session.calls[0]["data"] == {
+        "grant_type": "client_credentials",
+        "client_id": "  client-id  ",
+        "client_secret": "  client-secret  ",
+        "scope": "api",
+    }
+
+
+def test_token_manager_uses_password_grant_with_both_credential_sets() -> None:
+    session = _FakeSession()
+    auth = GLPITokenManager(
+        token_url="https://glpi.example.test/api.php/token",
+        client_id="client-id",
+        client_secret="client-secret",
+        username="api-user",
+        password="api-password",
+        session=cast(requests.Session, session),
+    )
+
+    auth._acquire_token()
+
+    assert session.calls[0]["data"] == {
+        "grant_type": "password",
+        "client_id": "client-id",
+        "client_secret": "client-secret",
+        "username": "api-user",
+        "password": "api-password",
+        "scope": "api",
+    }
+
+
+def test_token_manager_refreshes_when_configured_interval_elapses() -> None:
+    session = _FakeSession()
+    auth = GLPITokenManager(
+        token_url="https://glpi.example.test/api.php/token",
+        client_id="client-id",
+        client_secret="client-secret",
+        session=cast(requests.Session, session),
+        auth_token_refresh=60,
+    )
+    auth.access_token = "old-token"
+    auth.refresh_token = "refresh-token"
+    auth.token_updated_at = datetime.now(tz=timezone.utc) - timedelta(seconds=61)
+    auth.token_expires_at = datetime.now(tz=timezone.utc) + timedelta(hours=1)
+
+    auth.ensure_token()
+
+    assert auth.auth_token_refresh == 60
+    assert session.calls[0]["data"] == {
+        "grant_type": "refresh_token",
+        "refresh_token": "refresh-token",
+        "client_id": "client-id",
+        "client_secret": "client-secret",
+    }
+    assert auth.access_token == "token"
+
+
+@pytest.mark.parametrize("refresh_interval", [0, -1])
+def test_token_manager_rejects_non_positive_refresh_interval(
+    refresh_interval: int,
+) -> None:
+    with pytest.raises(ValueError, match="auth_token_refresh"):
+        GLPITokenManager(
+            token_url="https://glpi.example.test/api.php/token",
+            client_id="client-id",
+            client_secret="client-secret",
+            auth_token_refresh=refresh_interval,
+        )
+
+
+def test_token_manager_logout_clears_cached_tokens() -> None:
+    auth = GLPITokenManager(
+        token_url="https://glpi.example.test/api.php/token",
+        client_id="client-id",
+        client_secret="client-secret",
+    )
+    auth.access_token = "access-token"
+    auth.refresh_token = "refresh-token"
+    auth.token_updated_at = datetime.now(tz=timezone.utc)
+    auth.token_expires_at = auth.token_updated_at + timedelta(hours=1)
+
+    auth.logout()
+
+    assert cast(str | None, auth.access_token) is None
+    assert cast(str | None, auth.refresh_token) is None
+    assert cast(datetime | None, auth.token_updated_at) is None
+    assert cast(datetime | None, auth.token_expires_at) is None
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "message"),
+    [
+        ({}, "either client_id/client_secret, username/password, or both"),
+        ({"client_id": "client-id"}, "both client_id and client_secret"),
+        ({"client_secret": "client-secret"}, "both client_id and client_secret"),
+        ({"username": "api-user"}, "both username and password"),
+        ({"password": "api-password"}, "both username and password"),
+    ],
+)
+def test_token_manager_rejects_incomplete_credentials(
+    kwargs: dict[str, str],
+    message: str,
+) -> None:
+    with pytest.raises(ValueError, match=message):
+        GLPITokenManager(
+            token_url="https://glpi.example.test/api.php/token",
+            client_id=kwargs.get("client_id"),
+            client_secret=kwargs.get("client_secret"),
+            username=kwargs.get("username"),
+            password=kwargs.get("password"),
+        )

glpi_python_client/clients/__init__.py

@@ -0,0 +1,18 @@
+"""Public client exports for the GLPI package.
+
+This package entrypoint exposes the supported synchronous client,
+asynchronous client, and legacy v1 session wrapper without re-exporting the
+internal mixin hierarchy used to implement them.
+"""
+
+from __future__ import annotations
+
+from glpi_python_client.clients.api_v1_session import GLPIV1Session
+from glpi_python_client.clients.api_v2_client import GlpiClient
+from glpi_python_client.clients.async_api_v2_client import AsyncGlpiClient
+
+__all__ = [
+    "AsyncGlpiClient",
+    "GLPIV1Session",
+    "GlpiClient",
+]