Skip to content

GlpiOAuthClient

OAuth2 Clients Clients for the GLPI 11 high-level API (/api.php).

GlpiOAuthClient

glpi_utils.oauth.GlpiOAuthClient

Synchronous OAuth2 client for the GLPI 11/12 High-level API (/api.php).

Parameters:

Name Type Description Default
url str or None

Base URL, e.g. "https://glpi.example.com". Falls back to GLPI_URL.

None
client_id str or None

OAuth2 client ID. Falls back to GLPI_OAUTH_CLIENT_ID.

None
client_secret str or None

OAuth2 client secret. Falls back to GLPI_OAUTH_CLIENT_SECRET.

None
verify_ssl bool

Verify TLS certificates (default: True).

True
timeout int

HTTP timeout in seconds (default: 30).

30
api_version str or None

High-Level API version to pin, e.g. "2.3" or "3.0" (/api.php/v2.3, /api.php/v3.0). None sends unversioned requests, which the server answers with its newest version: 2.3 on GLPI 11, 3.0 on GLPI 12. Pin it in production so a GLPI upgrade does not change response schemas under you. Falls back to GLPI_API_VERSION.

None
Source code in glpi_utils/oauth.py
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
class GlpiOAuthClient:
    """Synchronous OAuth2 client for the GLPI 11/12 High-level API (``/api.php``).

    Parameters
    ----------
    url : str or None
        Base URL, e.g. ``"https://glpi.example.com"``.
        Falls back to ``GLPI_URL``.
    client_id : str or None
        OAuth2 client ID. Falls back to ``GLPI_OAUTH_CLIENT_ID``.
    client_secret : str or None
        OAuth2 client secret. Falls back to ``GLPI_OAUTH_CLIENT_SECRET``.
    verify_ssl : bool
        Verify TLS certificates (default: ``True``).
    timeout : int
        HTTP timeout in seconds (default: ``30``).
    api_version : str or None
        High-Level API version to pin, e.g. ``"2.3"`` or ``"3.0"``
        (``/api.php/v2.3``, ``/api.php/v3.0``). ``None`` sends unversioned
        requests, which the server answers with its newest version: 2.3 on
        GLPI 11, **3.0 on GLPI 12**. Pin it in production so a GLPI upgrade
        does not change response schemas under you.
        Falls back to ``GLPI_API_VERSION``.
    """

    def __init__(
        self,
        url: Optional[str] = None,
        client_id: Optional[str] = None,
        client_secret: Optional[str] = None,
        username: Optional[str] = None,
        password: Optional[str] = None,
        verify_ssl: bool = True,
        timeout: int = 30,
        api_version: Optional[str] = None,
    ) -> None:
        self._url = (url or os.environ.get("GLPI_URL", "")).rstrip("/")
        if not self._url:
            raise ValueError("A GLPI URL is required. Pass url= or set GLPI_URL.")

        self._client_id = client_id or os.environ.get("GLPI_OAUTH_CLIENT_ID")
        self._client_secret = client_secret or os.environ.get("GLPI_OAUTH_CLIENT_SECRET")
        self._username = username or os.environ.get("GLPI_OAUTH_USERNAME")
        self._password = password or os.environ.get("GLPI_OAUTH_PASSWORD")
        self._api_version = _normalize_api_version(
            api_version or os.environ.get("GLPI_API_VERSION")
        )
        self._verify_ssl = verify_ssl
        self._timeout = timeout

        self._token = _TokenStore()
        self._http = Session()
        self._version: Optional[GLPIVersion] = None
        self._proxies: dict[str, Any] = {}

    # ------------------------------------------------------------------
    # Context manager
    # ------------------------------------------------------------------

    def __enter__(self) -> GlpiOAuthClient:
        return self

    def __exit__(self, *_: Any) -> None:
        self.close()

    def close(self) -> None:
        """Close the underlying HTTP session."""
        self._http.close()
        self._token.clear()

    # ------------------------------------------------------------------
    # Fluent accessors
    # ------------------------------------------------------------------

    def __getattr__(self, name: str) -> ItemProxy:
        # Use object.__getattribute__ to avoid recursive __getattr__ calls
        # when _proxies itself hasn't been set yet.
        try:
            proxies = object.__getattribute__(self, "_proxies")
        except AttributeError:
            proxies = {}
            object.__setattr__(self, "_proxies", proxies)

        lower = name.lower()
        if lower in _ITEMTYPE_MAP:
            if lower not in proxies:
                proxies[lower] = ItemProxy(self, _ITEMTYPE_MAP[lower])  # type: ignore[arg-type]
            return proxies[lower]
        raise AttributeError(
            f"{self.__class__.__name__!r} has no attribute {name!r}. "
            "Use api.item('YourItemtype') for non-standard item types."
        )

    def item(self, itemtype: str) -> ItemProxy:
        """Return an :class:`~glpi_utils._resource.ItemProxy` for any itemtype."""
        try:
            proxies = object.__getattribute__(self, "_proxies")
        except AttributeError:
            proxies = {}
            object.__setattr__(self, "_proxies", proxies)
        if itemtype not in proxies:
            proxies[itemtype] = ItemProxy(self, itemtype)  # type: ignore[arg-type]
        return proxies[itemtype]

    # ------------------------------------------------------------------
    # URL helpers
    # ------------------------------------------------------------------

    @property
    def _token_url(self) -> str:
        return f"{self._url}/api.php/token"

    @property
    def _api_url(self) -> str:
        if self._api_version:
            return f"{self._url}/api.php/{self._api_version}"
        return f"{self._url}/api.php"

    @property
    def api_version(self) -> Optional[str]:
        """Pinned HL API version prefix (e.g. ``"v3.0"``), or ``None``."""
        return self._api_version

    def _auth_headers(self, with_content_type: bool = False) -> dict[str, Any]:
        token = self._token.access_token
        if not token:
            raise GlpiAuthError("Not authenticated. Call authenticate() first.")
        headers = {"Authorization": f"Bearer {token}"}
        if with_content_type:
            headers["Content-Type"] = "application/json"
        return headers

    # ------------------------------------------------------------------
    # Authentication
    # ------------------------------------------------------------------

    def authenticate(
        self,
        username: Optional[str] = None,
        password: Optional[str] = None,
    ) -> None:
        """Obtain an OAuth2 Bearer token.

        Parameters
        ----------
        username : str or None
            If provided (along with *password*), uses the ``password`` grant.
            Otherwise uses ``client_credentials``.
            Falls back to constructor username or ``GLPI_OAUTH_USERNAME``.
        password : str or None
        """
        if not self._client_id:
            raise GlpiAuthError(
                "client_id is required. Pass it or set GLPI_OAUTH_CLIENT_ID."
            )

        username = username or self._username
        password = password or self._password

        if username and password:
            payload = {
                "grant_type": "password",
                "client_id": self._client_id,
                "client_secret": self._client_secret or "",
                "username": username,
                "password": password,
                "scope": "api",
            }
            grant = "password"
        else:
            if not self._client_secret:
                raise GlpiAuthError(
                    "client_secret is required for client_credentials grant. "
                    "Set GLPI_OAUTH_CLIENT_SECRET or pass client_secret=."
                )
            payload = {
                "grant_type": "client_credentials",
                "client_id": self._client_id,
                "client_secret": self._client_secret,
                "scope": "api",
            }
            grant = "client_credentials"

        log.debug("OAuth2 token request (grant=%s)", grant)

        try:
            resp = self._http.post(
                self._token_url,
                data=payload,
                verify=self._verify_ssl,
                timeout=self._timeout,
            )
        except requests.exceptions.ConnectionError as exc:
            raise GlpiConnectionError(f"Cannot reach GLPI at {self._url}: {exc}") from exc
        except requests.exceptions.Timeout as exc:
            raise GlpiConnectionError(f"Token request timed out: {exc}") from exc

        body = resp.json()
        if resp.status_code not in (200, 201) or "access_token" not in body:
            error = body.get("error", str(resp.status_code))
            desc  = body.get("error_description", resp.text)
            raise GlpiAuthError(
                f"OAuth2 token request failed ({error}): {desc}",
                status_code=resp.status_code,
                error_code=error,
            )

        self._token.store(body["access_token"], int(body.get("expires_in", 3600)))
        log.debug("OAuth2 token obtained (expires_in=%s).", body.get("expires_in"))

    def _ensure_token(
        self,
        username: Optional[str] = None,
        password: Optional[str] = None,
    ) -> None:
        """Re-authenticate automatically if the token has expired."""
        if not self._token.is_valid():
            log.debug("Token expired or missing — re-authenticating.")
            self.authenticate(username=username, password=password)

    # ------------------------------------------------------------------
    # Internal HTTP helpers
    # ------------------------------------------------------------------

    def _request(
        self,
        method: str,
        path: str,
        *,
        params: Optional[dict[str, Any]] = None,
        json: Any = None,
    ) -> Any:
        body, _ = self._request_with_headers(method, path, params=params, json=json)
        return body

    def _request_with_headers(
        self,
        method: str,
        path: str,
        *,
        params: Optional[dict[str, Any]] = None,
        json: Any = None,
    ) -> tuple[Any, Any]:
        self._ensure_token()
        url = f"{self._api_url}/{path.lstrip('/')}"
        log.debug("%s %s params=%s", method.upper(), url, params)

        try:
            resp = self._http.request(
                method, url,
                headers=self._auth_headers(with_content_type=json is not None),
                params=params,
                json=json,
                verify=self._verify_ssl,
                timeout=self._timeout,
            )
        except requests.exceptions.ConnectionError as exc:
            raise GlpiConnectionError(f"Cannot reach GLPI at {self._url}: {exc}") from exc
        except requests.exceptions.Timeout as exc:
            raise GlpiConnectionError(f"Request timed out: {exc}") from exc

        log.debug("Response %s from %s", resp.status_code, url)

        if resp.status_code == 204 or not resp.content:
            return None, dict(resp.headers)

        try:
            body = resp.json()
        except Exception:
            body = resp.text

        _raise_for_oauth_error(resp.status_code, body, resp.text)
        return body, dict(resp.headers)

    # ------------------------------------------------------------------
    # Version
    # ------------------------------------------------------------------

    @property
    def version(self) -> Optional[GLPIVersion]:
        """Return cached server version."""
        return self._version

    def get_version(self) -> GLPIVersion:
        """Fetch and cache the GLPI server version.

        Reads ``GET /Setup/Config/core/version`` (needs read access to the
        general setup); the API root does not expose the GLPI version.
        """
        data = self._request("GET", "Setup/Config/core/version")
        raw = data.get("value") if isinstance(data, dict) else None
        self._version = GLPIVersion(raw or "0.0.0")
        return self._version

    def get_api_versions(self) -> list[Any]:
        """Return the API versions the server offers (``GET /api.php/``).

        Each entry has ``api_version`` (major), ``version`` and ``endpoint``.
        GLPI 11 lists 1.0.0 and 2.0.0-2.3.0; GLPI 12 lists 1.0.0, 2.3.0 and 3.0.0.
        """
        self._ensure_token()
        try:
            resp = self._http.get(
                f"{self._url}/api.php/",
                headers=self._auth_headers(),
                verify=self._verify_ssl,
                timeout=self._timeout,
            )
        except requests.exceptions.RequestException as exc:
            raise GlpiConnectionError(f"Cannot reach GLPI at {self._url}: {exc}") from exc
        body = resp.json()
        _raise_for_oauth_error(resp.status_code, body, resp.text)
        return list(body.get("api_versions", []))

    # ------------------------------------------------------------------
    # Item CRUD
    # ------------------------------------------------------------------

    def get_item(self, itemtype: str, item_id: int, **kwargs: Any) -> dict[str, Any]:
        """Return a single item by ID."""
        params = _boolify_params(kwargs)
        return self._request("GET", f"{_hl_route(itemtype)}/{item_id}", params=params)

    def get_all_items(self, itemtype: str, **kwargs: Any) -> list[Any]:
        """Return a single page of items (``start``/``limit``; ``range="a-b"`` is translated)."""
        params = _page_params(_boolify_params(kwargs), DEFAULT_PAGE_SIZE)
        return self._request("GET", _hl_route(itemtype), params=params)

    def get_all_pages(
        self,
        itemtype: str,
        page_size: int = DEFAULT_PAGE_SIZE,
        **kwargs: Any,
    ) -> list[Any]:
        """Fetch all items across all pages automatically."""
        return list(item for page in self.iter_pages(itemtype, page_size=page_size, **kwargs) for item in page)

    def iter_pages(
        self,
        itemtype: str,
        page_size: int = DEFAULT_PAGE_SIZE,
        **kwargs: Any,
    ) -> Iterator[list[Any]]:
        """Yield one page of items at a time."""
        base = _boolify_params(kwargs)
        base.pop("range", None)
        start = 0
        fetched = 0

        while True:
            params = {**base, "start": start, "limit": page_size}
            page_items, resp_headers = self._request_with_headers("GET", _hl_route(itemtype), params=params)

            if not page_items:
                return

            fetched += len(page_items)
            yield page_items

            total = _parse_content_range(resp_headers.get("Content-Range", ""))
            if total is not None and fetched >= total:
                return
            if len(page_items) < page_size:
                return

            start += page_size

    def search(self, itemtype: str, filter: Optional[str] = None, **kwargs: Any) -> list[Any]:
        """Search a collection with an RSQL *filter*, e.g. ``"name=like=*srv*;status.id==1"``.

        Extra kwargs (``start``, ``limit``, ``sort``) are passed as query parameters.
        """
        params = _boolify_params(kwargs)
        if filter:
            params["filter"] = filter
        return self._request("GET", _hl_route(itemtype), params=params)

    def create_item(self, itemtype: str, input_data: Any, **kwargs: Any) -> Any:
        """Create one or several items."""
        # HL API v2: POST body is the object directly, no {input:} wrapper
        if isinstance(input_data, dict):
            body = dict(input_data)
            body.update(kwargs)
        else:
            body = input_data
        return self._request("POST", _hl_route(itemtype), json=body)

    def update_item(self, itemtype: str, input_data: Any, **kwargs: Any) -> list[Any]:
        """Update one or several items."""
        # HL API v2: PUT /{route}/{id} with fields in body (no wrapper)
        if isinstance(input_data, dict) and "id" in input_data:
            item_id = input_data["id"]
            body = {k: v for k, v in input_data.items() if k != "id"}
            body.update(kwargs)
            return self._request("PATCH", f"{_hl_route(itemtype)}/{item_id}", json=body)
        # Fallback for list input (bulk) - not natively supported in HL API
        payload: dict[str, Any] = {"input": input_data}
        payload.update(kwargs)
        return self._request("PATCH", _hl_route(itemtype), json=payload)

    def delete_item(
        self,
        itemtype: str,
        input_data: Any,
        force_purge: bool = False,
        history: bool = True,
    ) -> list[Any]:
        """Delete one or several items."""
        # HL API v2: DELETE /{route}/{id}
        if isinstance(input_data, dict) and "id" in input_data:
            item_id = input_data["id"]
            return self._request("DELETE", f"{_hl_route(itemtype)}/{item_id}")
        payload: dict[str, Any] = {"input": input_data}
        return self._request("DELETE", _hl_route(itemtype), json=payload)

    def get_sub_items(
        self, itemtype: str, item_id: int, sub_itemtype: str, **kwargs: Any
    ) -> list[Any]:
        """Return sub-items of a parent item."""
        params = _boolify_params(kwargs)
        return self._request("GET", f"{_hl_route(itemtype)}/{item_id}/{_hl_subitem_route(sub_itemtype)}", params=params)

    def add_sub_item(
        self, itemtype: str, item_id: int, sub_itemtype: str, input_data: dict[str, Any], **kwargs: Any
    ) -> dict[str, Any]:
        """Add a sub-item to a parent resource."""
        # HL API v2: body is the object directly, no {"input":...} wrapper
        body = dict(input_data)
        body.update(kwargs)
        return self._request("POST", f"{_hl_route(itemtype)}/{item_id}/{_hl_subitem_route(sub_itemtype)}", json=body)

api_version property

api_version: Optional[str]

Pinned HL API version prefix (e.g. "v3.0"), or None.

version property

version: Optional[GLPIVersion]

Return cached server version.

close

close() -> None

Close the underlying HTTP session.

Source code in glpi_utils/oauth.py
def close(self) -> None:
    """Close the underlying HTTP session."""
    self._http.close()
    self._token.clear()

item

item(itemtype: str) -> ItemProxy

Return an :class:~glpi_utils._resource.ItemProxy for any itemtype.

Source code in glpi_utils/oauth.py
def item(self, itemtype: str) -> ItemProxy:
    """Return an :class:`~glpi_utils._resource.ItemProxy` for any itemtype."""
    try:
        proxies = object.__getattribute__(self, "_proxies")
    except AttributeError:
        proxies = {}
        object.__setattr__(self, "_proxies", proxies)
    if itemtype not in proxies:
        proxies[itemtype] = ItemProxy(self, itemtype)  # type: ignore[arg-type]
    return proxies[itemtype]

authenticate

authenticate(username: Optional[str] = None, password: Optional[str] = None) -> None

Obtain an OAuth2 Bearer token.

Parameters:

Name Type Description Default
username str or None

If provided (along with password), uses the password grant. Otherwise uses client_credentials. Falls back to constructor username or GLPI_OAUTH_USERNAME.

None
password str or None
None
Source code in glpi_utils/oauth.py
def authenticate(
    self,
    username: Optional[str] = None,
    password: Optional[str] = None,
) -> None:
    """Obtain an OAuth2 Bearer token.

    Parameters
    ----------
    username : str or None
        If provided (along with *password*), uses the ``password`` grant.
        Otherwise uses ``client_credentials``.
        Falls back to constructor username or ``GLPI_OAUTH_USERNAME``.
    password : str or None
    """
    if not self._client_id:
        raise GlpiAuthError(
            "client_id is required. Pass it or set GLPI_OAUTH_CLIENT_ID."
        )

    username = username or self._username
    password = password or self._password

    if username and password:
        payload = {
            "grant_type": "password",
            "client_id": self._client_id,
            "client_secret": self._client_secret or "",
            "username": username,
            "password": password,
            "scope": "api",
        }
        grant = "password"
    else:
        if not self._client_secret:
            raise GlpiAuthError(
                "client_secret is required for client_credentials grant. "
                "Set GLPI_OAUTH_CLIENT_SECRET or pass client_secret=."
            )
        payload = {
            "grant_type": "client_credentials",
            "client_id": self._client_id,
            "client_secret": self._client_secret,
            "scope": "api",
        }
        grant = "client_credentials"

    log.debug("OAuth2 token request (grant=%s)", grant)

    try:
        resp = self._http.post(
            self._token_url,
            data=payload,
            verify=self._verify_ssl,
            timeout=self._timeout,
        )
    except requests.exceptions.ConnectionError as exc:
        raise GlpiConnectionError(f"Cannot reach GLPI at {self._url}: {exc}") from exc
    except requests.exceptions.Timeout as exc:
        raise GlpiConnectionError(f"Token request timed out: {exc}") from exc

    body = resp.json()
    if resp.status_code not in (200, 201) or "access_token" not in body:
        error = body.get("error", str(resp.status_code))
        desc  = body.get("error_description", resp.text)
        raise GlpiAuthError(
            f"OAuth2 token request failed ({error}): {desc}",
            status_code=resp.status_code,
            error_code=error,
        )

    self._token.store(body["access_token"], int(body.get("expires_in", 3600)))
    log.debug("OAuth2 token obtained (expires_in=%s).", body.get("expires_in"))

get_version

get_version() -> GLPIVersion

Fetch and cache the GLPI server version.

Reads GET /Setup/Config/core/version (needs read access to the general setup); the API root does not expose the GLPI version.

Source code in glpi_utils/oauth.py
def get_version(self) -> GLPIVersion:
    """Fetch and cache the GLPI server version.

    Reads ``GET /Setup/Config/core/version`` (needs read access to the
    general setup); the API root does not expose the GLPI version.
    """
    data = self._request("GET", "Setup/Config/core/version")
    raw = data.get("value") if isinstance(data, dict) else None
    self._version = GLPIVersion(raw or "0.0.0")
    return self._version

get_api_versions

get_api_versions() -> list[Any]

Return the API versions the server offers (GET /api.php/).

Each entry has api_version (major), version and endpoint. GLPI 11 lists 1.0.0 and 2.0.0-2.3.0; GLPI 12 lists 1.0.0, 2.3.0 and 3.0.0.

Source code in glpi_utils/oauth.py
def get_api_versions(self) -> list[Any]:
    """Return the API versions the server offers (``GET /api.php/``).

    Each entry has ``api_version`` (major), ``version`` and ``endpoint``.
    GLPI 11 lists 1.0.0 and 2.0.0-2.3.0; GLPI 12 lists 1.0.0, 2.3.0 and 3.0.0.
    """
    self._ensure_token()
    try:
        resp = self._http.get(
            f"{self._url}/api.php/",
            headers=self._auth_headers(),
            verify=self._verify_ssl,
            timeout=self._timeout,
        )
    except requests.exceptions.RequestException as exc:
        raise GlpiConnectionError(f"Cannot reach GLPI at {self._url}: {exc}") from exc
    body = resp.json()
    _raise_for_oauth_error(resp.status_code, body, resp.text)
    return list(body.get("api_versions", []))

get_item

get_item(itemtype: str, item_id: int, **kwargs: Any) -> dict[str, Any]

Return a single item by ID.

Source code in glpi_utils/oauth.py
def get_item(self, itemtype: str, item_id: int, **kwargs: Any) -> dict[str, Any]:
    """Return a single item by ID."""
    params = _boolify_params(kwargs)
    return self._request("GET", f"{_hl_route(itemtype)}/{item_id}", params=params)

get_all_items

get_all_items(itemtype: str, **kwargs: Any) -> list[Any]

Return a single page of items (start/limit; range="a-b" is translated).

Source code in glpi_utils/oauth.py
def get_all_items(self, itemtype: str, **kwargs: Any) -> list[Any]:
    """Return a single page of items (``start``/``limit``; ``range="a-b"`` is translated)."""
    params = _page_params(_boolify_params(kwargs), DEFAULT_PAGE_SIZE)
    return self._request("GET", _hl_route(itemtype), params=params)

get_all_pages

get_all_pages(itemtype: str, page_size: int = DEFAULT_PAGE_SIZE, **kwargs: Any) -> list[Any]

Fetch all items across all pages automatically.

Source code in glpi_utils/oauth.py
def get_all_pages(
    self,
    itemtype: str,
    page_size: int = DEFAULT_PAGE_SIZE,
    **kwargs: Any,
) -> list[Any]:
    """Fetch all items across all pages automatically."""
    return list(item for page in self.iter_pages(itemtype, page_size=page_size, **kwargs) for item in page)

iter_pages

iter_pages(itemtype: str, page_size: int = DEFAULT_PAGE_SIZE, **kwargs: Any) -> Iterator[list[Any]]

Yield one page of items at a time.

Source code in glpi_utils/oauth.py
def iter_pages(
    self,
    itemtype: str,
    page_size: int = DEFAULT_PAGE_SIZE,
    **kwargs: Any,
) -> Iterator[list[Any]]:
    """Yield one page of items at a time."""
    base = _boolify_params(kwargs)
    base.pop("range", None)
    start = 0
    fetched = 0

    while True:
        params = {**base, "start": start, "limit": page_size}
        page_items, resp_headers = self._request_with_headers("GET", _hl_route(itemtype), params=params)

        if not page_items:
            return

        fetched += len(page_items)
        yield page_items

        total = _parse_content_range(resp_headers.get("Content-Range", ""))
        if total is not None and fetched >= total:
            return
        if len(page_items) < page_size:
            return

        start += page_size

search

search(itemtype: str, filter: Optional[str] = None, **kwargs: Any) -> list[Any]

Search a collection with an RSQL filter, e.g. "name=like=*srv*;status.id==1".

Extra kwargs (start, limit, sort) are passed as query parameters.

Source code in glpi_utils/oauth.py
def search(self, itemtype: str, filter: Optional[str] = None, **kwargs: Any) -> list[Any]:
    """Search a collection with an RSQL *filter*, e.g. ``"name=like=*srv*;status.id==1"``.

    Extra kwargs (``start``, ``limit``, ``sort``) are passed as query parameters.
    """
    params = _boolify_params(kwargs)
    if filter:
        params["filter"] = filter
    return self._request("GET", _hl_route(itemtype), params=params)

create_item

create_item(itemtype: str, input_data: Any, **kwargs: Any) -> Any

Create one or several items.

Source code in glpi_utils/oauth.py
def create_item(self, itemtype: str, input_data: Any, **kwargs: Any) -> Any:
    """Create one or several items."""
    # HL API v2: POST body is the object directly, no {input:} wrapper
    if isinstance(input_data, dict):
        body = dict(input_data)
        body.update(kwargs)
    else:
        body = input_data
    return self._request("POST", _hl_route(itemtype), json=body)

update_item

update_item(itemtype: str, input_data: Any, **kwargs: Any) -> list[Any]

Update one or several items.

Source code in glpi_utils/oauth.py
def update_item(self, itemtype: str, input_data: Any, **kwargs: Any) -> list[Any]:
    """Update one or several items."""
    # HL API v2: PUT /{route}/{id} with fields in body (no wrapper)
    if isinstance(input_data, dict) and "id" in input_data:
        item_id = input_data["id"]
        body = {k: v for k, v in input_data.items() if k != "id"}
        body.update(kwargs)
        return self._request("PATCH", f"{_hl_route(itemtype)}/{item_id}", json=body)
    # Fallback for list input (bulk) - not natively supported in HL API
    payload: dict[str, Any] = {"input": input_data}
    payload.update(kwargs)
    return self._request("PATCH", _hl_route(itemtype), json=payload)

delete_item

delete_item(itemtype: str, input_data: Any, force_purge: bool = False, history: bool = True) -> list[Any]

Delete one or several items.

Source code in glpi_utils/oauth.py
def delete_item(
    self,
    itemtype: str,
    input_data: Any,
    force_purge: bool = False,
    history: bool = True,
) -> list[Any]:
    """Delete one or several items."""
    # HL API v2: DELETE /{route}/{id}
    if isinstance(input_data, dict) and "id" in input_data:
        item_id = input_data["id"]
        return self._request("DELETE", f"{_hl_route(itemtype)}/{item_id}")
    payload: dict[str, Any] = {"input": input_data}
    return self._request("DELETE", _hl_route(itemtype), json=payload)

get_sub_items

get_sub_items(itemtype: str, item_id: int, sub_itemtype: str, **kwargs: Any) -> list[Any]

Return sub-items of a parent item.

Source code in glpi_utils/oauth.py
def get_sub_items(
    self, itemtype: str, item_id: int, sub_itemtype: str, **kwargs: Any
) -> list[Any]:
    """Return sub-items of a parent item."""
    params = _boolify_params(kwargs)
    return self._request("GET", f"{_hl_route(itemtype)}/{item_id}/{_hl_subitem_route(sub_itemtype)}", params=params)

add_sub_item

add_sub_item(itemtype: str, item_id: int, sub_itemtype: str, input_data: dict[str, Any], **kwargs: Any) -> dict[str, Any]

Add a sub-item to a parent resource.

Source code in glpi_utils/oauth.py
def add_sub_item(
    self, itemtype: str, item_id: int, sub_itemtype: str, input_data: dict[str, Any], **kwargs: Any
) -> dict[str, Any]:
    """Add a sub-item to a parent resource."""
    # HL API v2: body is the object directly, no {"input":...} wrapper
    body = dict(input_data)
    body.update(kwargs)
    return self._request("POST", f"{_hl_route(itemtype)}/{item_id}/{_hl_subitem_route(sub_itemtype)}", json=body)

AsyncGlpiOAuthClient

glpi_utils.oauth.AsyncGlpiOAuthClient

Asynchronous OAuth2 client for the GLPI 11/12 High-level API (/api.php).

Parameters:

Name Type Description Default
url str or None
None
client_id str or None
None
client_secret str or None
None
verify_ssl bool
True
timeout int
30
api_version str or None

See :class:GlpiOAuthClient.

None

Examples:

::

async with AsyncGlpiOAuthClient(
    url="https://glpi.example.com",
    client_id="my-app",
    client_secret="secret",
) as api:
    await api.authenticate()
    tickets = await api.ticket.get_all_pages()
Source code in glpi_utils/oauth.py
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
class AsyncGlpiOAuthClient:
    """Asynchronous OAuth2 client for the GLPI 11/12 High-level API (``/api.php``).

    Parameters
    ----------
    url : str or None
    client_id : str or None
    client_secret : str or None
    verify_ssl : bool
    timeout : int
    api_version : str or None
        See :class:`GlpiOAuthClient`.

    Examples
    --------
    ::

        async with AsyncGlpiOAuthClient(
            url="https://glpi.example.com",
            client_id="my-app",
            client_secret="secret",
        ) as api:
            await api.authenticate()
            tickets = await api.ticket.get_all_pages()
    """

    def __init__(
        self,
        url: Optional[str] = None,
        client_id: Optional[str] = None,
        client_secret: Optional[str] = None,
        username: Optional[str] = None,
        password: Optional[str] = None,
        verify_ssl: bool = True,
        timeout: int = 30,
        api_version: Optional[str] = None,
    ) -> None:
        try:
            import aiohttp  # noqa: F401
        except ImportError as exc:
            raise ImportError(
                "AsyncGlpiOAuthClient requires 'aiohttp'. "
                "Install it with: pip install glpi-utils[async]"
            ) from exc

        self._url = (url or os.environ.get("GLPI_URL", "")).rstrip("/")
        if not self._url:
            raise ValueError("A GLPI URL is required. Pass url= or set GLPI_URL.")

        self._client_id = client_id or os.environ.get("GLPI_OAUTH_CLIENT_ID")
        self._client_secret = client_secret or os.environ.get("GLPI_OAUTH_CLIENT_SECRET")
        self._username = username or os.environ.get("GLPI_OAUTH_USERNAME")
        self._password = password or os.environ.get("GLPI_OAUTH_PASSWORD")
        self._api_version = _normalize_api_version(
            api_version or os.environ.get("GLPI_API_VERSION")
        )
        self._verify_ssl = verify_ssl
        self._timeout = timeout

        self._token = _TokenStore()
        self._http: Any = None
        self._version: Optional[GLPIVersion] = None
        self._proxies: dict[str, Any] = {}

    async def __aenter__(self) -> AsyncGlpiOAuthClient:
        return self

    async def __aexit__(self, *_: Any) -> None:
        await self.close()

    async def close(self) -> None:
        """Close the underlying aiohttp session."""
        if self._http and not self._http.closed:
            await self._http.close()
        self._token.clear()

    # ------------------------------------------------------------------
    # Fluent accessors
    # ------------------------------------------------------------------

    def __getattr__(self, name: str) -> AsyncItemProxy:
        try:
            proxies = object.__getattribute__(self, "_proxies")
        except AttributeError:
            proxies = {}
            object.__setattr__(self, "_proxies", proxies)

        lower = name.lower()
        if lower in _ITEMTYPE_MAP:
            if lower not in proxies:
                proxies[lower] = AsyncItemProxy(self, _ITEMTYPE_MAP[lower])  # type: ignore[arg-type]
            return proxies[lower]
        raise AttributeError(
            f"{self.__class__.__name__!r} has no attribute {name!r}. "
            "Use api.item('YourItemtype') for non-standard item types."
        )

    def item(self, itemtype: str) -> AsyncItemProxy:
        try:
            proxies = object.__getattribute__(self, "_proxies")
        except AttributeError:
            proxies = {}
            object.__setattr__(self, "_proxies", proxies)
        if itemtype not in proxies:
            proxies[itemtype] = AsyncItemProxy(self, itemtype)  # type: ignore[arg-type]
        return proxies[itemtype]

    # ------------------------------------------------------------------
    # HTTP helpers
    # ------------------------------------------------------------------

    @property
    def _token_url(self) -> str:
        return f"{self._url}/api.php/token"

    @property
    def _api_url(self) -> str:
        if self._api_version:
            return f"{self._url}/api.php/{self._api_version}"
        return f"{self._url}/api.php"

    @property
    def api_version(self) -> Optional[str]:
        """Pinned HL API version prefix (e.g. ``"v3.0"``), or ``None``."""
        return self._api_version

    def _get_http(self) -> Any:
        import aiohttp

        if self._http is None or self._http.closed:
            connector = aiohttp.TCPConnector(ssl=self._verify_ssl)
            self._http = aiohttp.ClientSession(connector=connector)
        return self._http

    def _auth_headers(self, with_content_type: bool = False) -> dict[str, Any]:
        if not self._token.access_token:
            raise GlpiAuthError("Not authenticated. Call await authenticate() first.")
        headers = {"Authorization": f"Bearer {self._token.access_token}"}
        if with_content_type:
            headers["Content-Type"] = "application/json"
        return headers

    # ------------------------------------------------------------------
    # Authentication
    # ------------------------------------------------------------------

    async def authenticate(
        self,
        username: Optional[str] = None,
        password: Optional[str] = None,
    ) -> None:
        """Obtain an OAuth2 Bearer token asynchronously."""
        import aiohttp

        if not self._client_id:
            raise GlpiAuthError("client_id is required. Set GLPI_OAUTH_CLIENT_ID.")

        username = username or self._username
        password = password or self._password

        if username and password:
            payload = {
                "grant_type": "password",
                "client_id": self._client_id,
                "client_secret": self._client_secret or "",
                "username": username,
                "password": password,
                "scope": "api",
            }
            grant = "password"
        else:
            if not self._client_secret:
                raise GlpiAuthError(
                    "client_secret is required for client_credentials grant."
                )
            payload = {
                "grant_type": "client_credentials",
                "client_id": self._client_id,
                "client_secret": self._client_secret,
                "scope": "api",
            }
            grant = "client_credentials"

        log.debug("Async OAuth2 token request (grant=%s)", grant)

        http = self._get_http()
        timeout = aiohttp.ClientTimeout(total=self._timeout)

        try:
            async with http.post(
                self._token_url, data=payload, timeout=timeout
            ) as resp:
                body = await resp.json(content_type=None)
                if resp.status not in (200, 201) or "access_token" not in body:
                    error = body.get("error", str(resp.status))
                    desc  = body.get("error_description", "")
                    raise GlpiAuthError(
                        f"OAuth2 token request failed ({error}): {desc}",
                        status_code=resp.status,
                        error_code=error,
                    )
                self._token.store(body["access_token"], int(body.get("expires_in", 3600)))
                log.debug("Async OAuth2 token obtained.")
        except aiohttp.ClientConnectorError as exc:
            raise GlpiConnectionError(f"Cannot reach GLPI at {self._url}: {exc}") from exc

    async def _ensure_token(self) -> None:
        if not self._token.is_valid():
            await self.authenticate()

    # ------------------------------------------------------------------
    # Internal HTTP helpers
    # ------------------------------------------------------------------

    async def _request(
        self, method: str, path: str, *, params: Optional[dict[str, Any]] = None, json: Any = None
    ) -> Any:
        body, _ = await self._request_with_headers(method, path, params=params, json=json)
        return body

    async def _request_with_headers(
        self, method: str, path: str, *, params: Optional[dict[str, Any]] = None, json: Any = None
    ) -> tuple[Any, Any]:
        import aiohttp

        await self._ensure_token()
        url = f"{self._api_url}/{path.lstrip('/')}"
        log.debug("ASYNC %s %s params=%s", method.upper(), url, params)

        http = self._get_http()
        timeout = aiohttp.ClientTimeout(total=self._timeout)

        try:
            async with http.request(
                method, url,
                headers=self._auth_headers(with_content_type=json is not None),
                params=params,
                json=json,
                timeout=timeout,
            ) as resp:
                resp_headers = dict(resp.headers)
                if resp.status == 204 or resp.content_length == 0:
                    return None, resp_headers
                body = await resp.json(content_type=None)
                _raise_for_oauth_error(resp.status, body, "")
                return body, resp_headers
        except aiohttp.ClientConnectorError as exc:
            raise GlpiConnectionError(f"Cannot reach GLPI at {self._url}: {exc}") from exc
        except aiohttp.ServerTimeoutError as exc:
            raise GlpiConnectionError(f"Request timed out: {exc}") from exc

    # ------------------------------------------------------------------
    # CRUD + pagination  (mirrors GlpiOAuthClient)
    # ------------------------------------------------------------------

    async def get_item(self, itemtype: str, item_id: int, **kwargs: Any) -> dict[str, Any]:
        return await self._request("GET", f"{_hl_route(itemtype)}/{item_id}", params=_boolify_params(kwargs))

    async def get_all_items(self, itemtype: str, **kwargs: Any) -> list[Any]:
        params = _page_params(_boolify_params(kwargs), DEFAULT_PAGE_SIZE)
        return await self._request("GET", _hl_route(itemtype), params=params)

    async def get_all_pages(self, itemtype: str, page_size: int = DEFAULT_PAGE_SIZE, **kwargs: Any) -> list[Any]:
        results: list[Any] = []
        async for page in self.iter_pages(itemtype, page_size=page_size, **kwargs):
            results.extend(page)
        return results

    async def iter_pages(
        self, itemtype: str, page_size: int = DEFAULT_PAGE_SIZE, **kwargs: Any
    ) -> AsyncIterator[list[Any]]:
        base = _boolify_params(kwargs)
        base.pop("range", None)
        start = 0
        fetched = 0
        while True:
            params = {**base, "start": start, "limit": page_size}
            page_items, resp_headers = await self._request_with_headers("GET", _hl_route(itemtype), params=params)
            if not page_items:
                return
            fetched += len(page_items)
            yield page_items
            total = _parse_content_range(resp_headers.get("Content-Range", ""))
            if total is not None and fetched >= total:
                return
            if len(page_items) < page_size:
                return
            start += page_size

    async def search(self, itemtype: str, filter: Optional[str] = None, **kwargs: Any) -> list[Any]:
        params = _boolify_params(kwargs)
        if filter:
            params["filter"] = filter
        return await self._request("GET", _hl_route(itemtype), params=params)

    async def create_item(self, itemtype: str, input_data: Any, **kwargs: Any) -> Any:
        if isinstance(input_data, dict):
            body = dict(input_data)
            body.update(kwargs)
        else:
            body = input_data
        return await self._request("POST", _hl_route(itemtype), json=body)

    async def update_item(self, itemtype: str, input_data: Any, **kwargs: Any) -> list[Any]:
        if isinstance(input_data, dict) and "id" in input_data:
            item_id = input_data["id"]
            body = {k: v for k, v in input_data.items() if k != "id"}
            body.update(kwargs)
            return await self._request("PATCH", f"{_hl_route(itemtype)}/{item_id}", json=body)
        payload: dict[str, Any] = {"input": input_data}
        payload.update(kwargs)
        return await self._request("PATCH", _hl_route(itemtype), json=payload)

    async def delete_item(
        self, itemtype: str, input_data: Any, force_purge: bool = False, history: bool = True
    ) -> list[Any]:
        if isinstance(input_data, dict) and "id" in input_data:
            item_id = input_data["id"]
            return await self._request("DELETE", f"{_hl_route(itemtype)}/{item_id}")
        return await self._request("DELETE", _hl_route(itemtype), json={"input": input_data})

    async def get_sub_items(self, itemtype: str, item_id: int, sub_itemtype: str, **kwargs: Any) -> list[Any]:
        path = f"{_hl_route(itemtype)}/{item_id}/{_hl_subitem_route(sub_itemtype)}"
        return await self._request("GET", path, params=_boolify_params(kwargs))

    async def add_sub_item(
        self, itemtype: str, item_id: int, sub_itemtype: str, input_data: dict[str, Any], **kwargs: Any
    ) -> dict[str, Any]:
        body = dict(input_data)
        body.update(kwargs)
        path = f"{_hl_route(itemtype)}/{item_id}/{_hl_subitem_route(sub_itemtype)}"
        return await self._request("POST", path, json=body)

    @property
    def version(self) -> Optional[GLPIVersion]:
        return self._version

    async def get_version(self) -> GLPIVersion:
        """Fetch and cache the GLPI server version (``GET /Setup/Config/core/version``)."""
        data = await self._request("GET", "Setup/Config/core/version")
        raw = data.get("value") if isinstance(data, dict) else None
        self._version = GLPIVersion(raw or "0.0.0")
        return self._version

    async def get_api_versions(self) -> list[Any]:
        """Return the API versions the server offers (``GET /api.php/``)."""
        import aiohttp

        await self._ensure_token()
        http = self._get_http()
        try:
            async with http.get(
                f"{self._url}/api.php/",
                headers=self._auth_headers(),
                timeout=aiohttp.ClientTimeout(total=self._timeout),
            ) as resp:
                body = await resp.json(content_type=None)
                _raise_for_oauth_error(resp.status, body, "")
                return list(body.get("api_versions", []))
        except aiohttp.ClientConnectorError as exc:
            raise GlpiConnectionError(f"Cannot reach GLPI at {self._url}: {exc}") from exc

api_version property

api_version: Optional[str]

Pinned HL API version prefix (e.g. "v3.0"), or None.

close async

close() -> None

Close the underlying aiohttp session.

Source code in glpi_utils/oauth.py
async def close(self) -> None:
    """Close the underlying aiohttp session."""
    if self._http and not self._http.closed:
        await self._http.close()
    self._token.clear()

authenticate async

authenticate(username: Optional[str] = None, password: Optional[str] = None) -> None

Obtain an OAuth2 Bearer token asynchronously.

Source code in glpi_utils/oauth.py
async def authenticate(
    self,
    username: Optional[str] = None,
    password: Optional[str] = None,
) -> None:
    """Obtain an OAuth2 Bearer token asynchronously."""
    import aiohttp

    if not self._client_id:
        raise GlpiAuthError("client_id is required. Set GLPI_OAUTH_CLIENT_ID.")

    username = username or self._username
    password = password or self._password

    if username and password:
        payload = {
            "grant_type": "password",
            "client_id": self._client_id,
            "client_secret": self._client_secret or "",
            "username": username,
            "password": password,
            "scope": "api",
        }
        grant = "password"
    else:
        if not self._client_secret:
            raise GlpiAuthError(
                "client_secret is required for client_credentials grant."
            )
        payload = {
            "grant_type": "client_credentials",
            "client_id": self._client_id,
            "client_secret": self._client_secret,
            "scope": "api",
        }
        grant = "client_credentials"

    log.debug("Async OAuth2 token request (grant=%s)", grant)

    http = self._get_http()
    timeout = aiohttp.ClientTimeout(total=self._timeout)

    try:
        async with http.post(
            self._token_url, data=payload, timeout=timeout
        ) as resp:
            body = await resp.json(content_type=None)
            if resp.status not in (200, 201) or "access_token" not in body:
                error = body.get("error", str(resp.status))
                desc  = body.get("error_description", "")
                raise GlpiAuthError(
                    f"OAuth2 token request failed ({error}): {desc}",
                    status_code=resp.status,
                    error_code=error,
                )
            self._token.store(body["access_token"], int(body.get("expires_in", 3600)))
            log.debug("Async OAuth2 token obtained.")
    except aiohttp.ClientConnectorError as exc:
        raise GlpiConnectionError(f"Cannot reach GLPI at {self._url}: {exc}") from exc

get_version async

get_version() -> GLPIVersion

Fetch and cache the GLPI server version (GET /Setup/Config/core/version).

Source code in glpi_utils/oauth.py
async def get_version(self) -> GLPIVersion:
    """Fetch and cache the GLPI server version (``GET /Setup/Config/core/version``)."""
    data = await self._request("GET", "Setup/Config/core/version")
    raw = data.get("value") if isinstance(data, dict) else None
    self._version = GLPIVersion(raw or "0.0.0")
    return self._version

get_api_versions async

get_api_versions() -> list[Any]

Return the API versions the server offers (GET /api.php/).

Source code in glpi_utils/oauth.py
async def get_api_versions(self) -> list[Any]:
    """Return the API versions the server offers (``GET /api.php/``)."""
    import aiohttp

    await self._ensure_token()
    http = self._get_http()
    try:
        async with http.get(
            f"{self._url}/api.php/",
            headers=self._auth_headers(),
            timeout=aiohttp.ClientTimeout(total=self._timeout),
        ) as resp:
            body = await resp.json(content_type=None)
            _raise_for_oauth_error(resp.status, body, "")
            return list(body.get("api_versions", []))
    except aiohttp.ClientConnectorError as exc:
        raise GlpiConnectionError(f"Cannot reach GLPI at {self._url}: {exc}") from exc