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

{glpi_python_client-0.3.1 → glpi_python_client-0.3.3}/.gitignore

@@ -26,5 +26,6 @@ dist/
 secrets/
 secrets/*
 
-integration_tests/
-integration_tests/*
+.claude/
+
+CLAUDE.md

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: glpi-python-client
-Version: 0.3.1
+Version: 0.3.3
 Summary: A typed Python client for GLPI ITSM APIs.
 Project-URL: Homepage, https://github.com/baraline/glpi_python_client
 Project-URL: Documentation, https://glpi-python-client.readthedocs.io/en/latest/

glpi_python_client-0.3.3/docs/development_rtd.rst

@@ -0,0 +1,162 @@
+Development
+===========
+
+Local Setup
+-----------
+
+Create a virtual environment and install the development dependencies:
+
+.. code-block:: console
+
+   python -m venv .venv
+   .venv\Scripts\activate
+   python -m pip install --upgrade pip
+   python -m pip install -e .[dev]
+   python -m pre_commit install
+
+The repository ships a root ``.pre-commit-config.yaml`` that runs Ruff on each
+commit. The lint hook applies safe fixes first, then Ruff formats the touched
+files.
+
+Quality Checks
+--------------
+
+Run the focused checks before opening a pull request:
+
+.. code-block:: console
+
+   python -m pre_commit run --all-files
+   python -m pytest
+   python -m ruff check .
+   python -m mypy glpi_python_client
+   python -m sphinx -b html docs docs/_build/html
+
+Integration Tests
+-----------------
+
+The ``integration_tests/`` directory holds end-to-end tests that drive a live
+GLPI instance through the synchronous and asynchronous clients. They are
+collected only when secrets resolve to a reachable instance; otherwise each
+test self-skips via ``pytest.skip``. Every test cleans up the records it
+creates in a ``finally`` block, but it is still recommended to point them at
+a non-production GLPI.
+
+Markers and CI behaviour
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+All integration tests are tagged with the ``integration`` pytest marker
+declared in ``pyproject.toml``. The ``ci.yml`` workflow runs
+``pytest -m "not integration"`` for both the test matrix and the coverage
+job, so the public CI never reaches a live GLPI. The default local
+``python -m pytest`` invocation *does* attempt to collect them, but they
+skip automatically when no secrets are configured.
+
+To explicitly opt in or out locally:
+
+.. code-block:: console
+
+   python -m pytest -m integration       # run only the live suite
+   python -m pytest -m "not integration" # mirror the CI behaviour
+
+Configuration
+~~~~~~~~~~~~~
+
+The suite reads each value from a file named after the secret under
+``secrets/`` at the repository root, falling back to the matching
+environment variable when the file is absent. The ``secrets/`` directory is
+gitignored. Each file contains a single trimmed value.
+
+Required:
+
+==============================  =========================  ===========================================
+Secret file                     Environment variable       Purpose
+==============================  =========================  ===========================================
+``glpi_api_url``                ``GLPI_API_URL``           Base URL of the GLPI v2 API.
+``glpi_client_id_test``         ``GLPI_CLIENT_ID``         OAuth2 client identifier.
+``glpi_client_secret_test``     ``GLPI_CLIENT_SECRET``     OAuth2 client secret.
+``glpi_username``               ``GLPI_USERNAME``          GLPI user for the password grant.
+``glpi_password``               ``GLPI_PASSWORD``          Password for the GLPI user above.
+==============================  =========================  ===========================================
+
+Optional:
+
+==============================  =============================  ============================================
+Secret file                     Environment variable           Purpose
+==============================  =============================  ============================================
+``glpi_verify_ssl``             ``GLPI_VERIFY_SSL``            Toggle TLS verification (default ``false``).
+``glpi_entity``                 ``GLPI_ENTITY``                Active entity id sent on every request.
+``glpi_profile``                ``GLPI_PROFILE``               Active profile id sent on every request.
+``glpi_entity_recursive``       ``GLPI_ENTITY_RECURSIVE``      Include sub-entities (default ``false``).
+``glpi_api_v1_url``             ``GLPI_API_V1_URL``            Base URL of the legacy v1 API.
+``glpi_api_v1_token_user``      ``GLPI_V1_USER_TOKEN``         v1 user token (enables document uploads).
+``glpi_api_v1_app_token``       ``GLPI_V1_APP_TOKEN``          v1 application token paired with the above.
+``glpi_team_member_role``       ``GLPI_TEAM_MEMBER_ROLE``      Role used to add the test user to a ticket.
+==============================  =============================  ============================================
+
+The v1 secrets are only required for the document-upload test; when they
+are missing that single test skips while the rest of the suite runs.
+
+Running the suite
+~~~~~~~~~~~~~~~~~
+
+Once secrets are in place:
+
+.. code-block:: console
+
+   python -m pytest integration_tests -m integration
+
+Use a disposable GLPI instance or one whose entity is dedicated to
+automated tests. The suite creates and deletes users, locations, tickets,
+followups, tasks, and solutions on every run.
+
+Package Layout
+--------------
+
+``glpi_python_client.__init__``
+   Public import surface (``GlpiClient``, ``GlpiTicketContext``, public Pydantic
+   models, enums, and ``__version__``).
+
+``glpi_python_client.clients.glpi_client``
+   Composition root. ``GlpiClient`` mixes the per-resource async API mixins,
+   the OAuth2 token manager, the asynchronous v2 transport, and the optional
+   internal v1 session used for document uploads.
+
+``glpi_python_client.clients.api``
+   Async API mixins generated from the GLPI v2 OpenAPI contract: tickets,
+   ticket timeline (followups, tasks, solutions, documents), team members,
+   documents, users, locations, entities, ...
+
+``glpi_python_client.clients.custom``
+   Higher-level helpers built on top of the contract mixins:
+   ``get_ticket_context``, ``get_ticket_statistics``, ``get_task_statistics``.
+
+``glpi_python_client.clients.commons``
+   Shared HTTP transport pieces, including the timeline envelope unwrap that
+   reconciles live server behaviour with the OpenAPI contract.
+
+``glpi_python_client.models.api_schema``
+   Contract-aligned Pydantic v2 models (``Get``/``Post``/``Patch``/``Delete``)
+   for each GLPI v2 resource.
+
+``glpi_python_client.models.custom_schema``
+   Composite models such as ``GlpiTicketContext`` returned by the custom
+   helpers.
+
+Adding Endpoints
+----------------
+
+#. Add or extend the contract-aligned models in
+   ``glpi_python_client.models.api_schema``.
+#. Add the async mixin and method under ``glpi_python_client.clients.api``,
+   mirroring the OpenAPI path and HTTP verb.
+#. When the live server diverges from the contract, document the choice in the
+   module docstring and (when needed) wire an unwrap helper from
+   ``glpi_python_client.clients.commons``.
+#. Re-export new public symbols from ``glpi_python_client.__init__``.
+#. Add tests for payload serialization, response parsing, and client behaviour.
+#. Document the workflow in :doc:`user_guide` and the matching skill in
+   ``skills/``.
+
+Keep organization-specific entity, profile, and category defaults outside the
+library core. Applications can apply their own mapping before calling the
+client.

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

@@ -179,16 +179,40 @@ fan-outs cannot race the auth manager, while the HTTP requests
 themselves execute outside the lock through the thread-safe
 :class:`requests.Session`.
 
-A small number of helpers exist in async-only variants because they
-need real concurrency:
-
-* :meth:`AsyncGlpiClient.get_ticket_context` fans the five underlying
-  GLPI calls out concurrently with :func:`asyncio.gather`.
-* :meth:`AsyncGlpiClient.get_task_statistics` fans the per-ticket task
-  list calls out concurrently with :func:`asyncio.gather`.
-* :meth:`AsyncGlpiClient.get_task_durations` fans the per-ticket task
-  fetches out concurrently with :func:`asyncio.gather` when
-  ``return_task_details=True``.
+A number of helpers ship with hand-written async overrides rather than
+relying solely on the bridge. There are two reasons a method needs its
+own async variant:
+
+1. **Concurrency** — the method benefits from fanning multiple GLPI
+   calls out concurrently with :func:`asyncio.gather`.
+2. **Internal self-calls** — the method calls another public method
+   through ``self`` (e.g. ``self.search_tickets(...)`` inside a
+   pagination loop). When the bridge runs the synchronous body in a
+   worker thread, ``self.method`` resolves to the bridge-wrapped
+   *coroutine*, which returns a coroutine object instead of data when
+   called without ``await``. The async override replaces the body so
+   every internal call is properly awaited on the event loop.
+
+Helpers with async overrides:
+
+* :meth:`AsyncGlpiClient.get_ticket_context` — fans the five underlying
+  GLPI calls out concurrently (reason: concurrency).
+* :meth:`AsyncGlpiClient.get_task_statistics` — fans the per-ticket
+  task-list calls out concurrently (reason: concurrency).
+* :meth:`AsyncGlpiClient.get_task_durations` — fans the per-ticket task
+  fetches out concurrently when ``return_task_details=True``, and
+  properly awaits ``iter_search_tickets`` and ``search_entities``
+  internally (reasons: concurrency + internal self-calls).
+* :meth:`AsyncGlpiClient.get_ticket_statistics` — properly awaits
+  ``search_tickets`` and ``search_entities`` internally (reason:
+  internal self-calls).
+* :meth:`AsyncGlpiClient.get_user_activity` — properly awaits
+  ``search_users``, ``iter_search_tickets``, and ``get_task_durations``
+  internally (reason: internal self-calls).
+* ``iter_search_tickets``, ``iter_search_users``,
+  ``iter_search_entities`` — each pagination loop body calls
+  ``self.search_*(...)``; the async variants are native async generators
+  that ``await`` those calls directly (reason: internal self-calls).
 
 Pagination helpers (``iter_search_tickets``, ``iter_search_users``,
 ``iter_search_entities``) are exposed as **async generators** on the
@@ -752,6 +776,14 @@ batches until the API returns fewer rows than the requested
            print(ticket.id, ticket.name)
    print(f"processed {total} tickets")
 
+.. note::
+
+   Always pass an RSQL filter to ``iter_search_tickets``. Querying
+   without any filter can return very large result sets and may cause
+   the GLPI server to return a 500 error on busy instances. The other
+   two generators (``iter_search_users``, ``iter_search_entities``) are
+   not affected because those collections are typically much smaller.
+
 On the asynchronous client the same helpers are exposed as **async
 generators** through the bridge, so each ``next()`` call runs off the
 event loop and the consumer uses ``async for``:
@@ -766,8 +798,10 @@ event loop and the consumer uses ``async for``:
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Counts tickets created within an ISO date window and groups them by
-entity, status, priority, and type. Optional filters restrict the
-result set on the server side:
+entity, status, priority, and type. The ``start_date`` is inclusive
+from 00:00:00 and the ``end_date`` is inclusive through 23:59:59, so
+tickets created at any time on those days are counted. Optional
+filters restrict the result set on the server side:
 
 * ``entity_id`` — restrict to a single entity by numeric identifier.
 * ``entity_name`` — substring match against the entity ``name`` column;
@@ -869,7 +903,9 @@ then computes per-user and per-entity totals.
 Available filters:
 
 * ``start_date`` / ``end_date`` / ``default_days`` — ISO ``YYYY-MM-DD``
-  date window; ``default_days`` is used when ``start_date`` is omitted.
+  date window; ``start_date`` is inclusive from 00:00:00,
+  ``end_date`` is inclusive through 23:59:59, and ``default_days``
+  is used when ``start_date`` is omitted.
 * ``entity_id`` — restrict to a single entity by identifier.
 * ``entity_name`` — substring match resolved through ``search_entities``;
   ignored when ``entity_id`` is given.

{glpi_python_client-0.3.1 → glpi_python_client-0.3.3}/glpi_python_client/__init__.py

@@ -72,7 +72,7 @@ from glpi_python_client.models import (
     TicketMarkdownOptions,
 )
 
-__version__ = "0.3.1"
+__version__ = "0.3.3"
 
 __all__ = [
     "AsyncGlpiClient",

{glpi_python_client-0.3.1 → glpi_python_client-0.3.3}/glpi_python_client/clients/api/assistance/timeline/_document.py

@@ -7,11 +7,12 @@ Notes
 -----
 The live GLPI v2 server returns each entry of the list endpoint wrapped
 in a ``{"type": "Document_Item", "item": {...}}`` envelope, even though
-the OpenAPI contract documents a flat array of ``Document_Item``. Real
-behaviour wins over the contract, so :func:`list_ticket_timeline_documents`
-unwraps the envelope through the shared
-:meth:`~glpi_python_client.clients.commons._transport.TransportMixin._resource_list`
-helper and tolerates both shapes.
+the OpenAPI contract documents a flat array of ``Document_Item``.  The
+``item`` value is a full ``Document`` record (matching :class:`GetDocument`),
+not a ``Document_Item`` link record — real behaviour wins over the contract.
+:func:`list_ticket_timeline_documents` unwraps the envelope through the shared
+``TransportMixin._resource_list`` helper and deserialises each inner object
+as :class:`GetDocument`.
 """
 
 from __future__ import annotations
@@ -24,19 +25,17 @@ from glpi_python_client.clients.commons._constants import (
 from glpi_python_client.clients.commons._transport import TransportMixin
 from glpi_python_client.models.api_schema.assistance.timeline._document import (
     DeleteTimelineDocument,
-    GetTimelineDocument,
     PatchTimelineDocument,
     PostTimelineDocument,
 )
+from glpi_python_client.models.api_schema.management._document import GetDocument
 
 
 class TimelineDocumentMixin(TransportMixin):
     """Synchronous CRUD helpers for the ticket document timeline endpoint."""
 
-    def list_ticket_timeline_documents(
-        self, ticket_id: GlpiId
-    ) -> list[GetTimelineDocument]:
-        """List all timeline documents linked to one ticket.
+    def list_ticket_timeline_documents(self, ticket_id: GlpiId) -> list[GetDocument]:
+        """List all documents linked to one ticket timeline.
 
         Parameters
         ----------
@@ -45,14 +44,16 @@ class TimelineDocumentMixin(TransportMixin):
 
         Returns
         -------
-        list[GetTimelineDocument]
-            Document links returned by the GLPI server, with the timeline
-            envelope unwrapped where present.
+        list[GetDocument]
+            Document records returned by the GLPI server.  The live API
+            wraps each entry in a ``{"type": "Document_Item", "item": {...}}``
+            envelope whose ``item`` value is a full ``Document`` record; the
+            envelope is unwrapped automatically.
         """
 
         return self._resource_list(
             f"{TICKET_ENDPOINT}/{ticket_id}/{TIMELINE_DOCUMENT_SUFFIX}",
-            GetTimelineDocument,
+            GetDocument,
             failure_message=(
                 f"Failed to list timeline documents for ticket {ticket_id}"
             ),
@@ -61,20 +62,20 @@ class TimelineDocumentMixin(TransportMixin):
 
     def get_ticket_timeline_document(
         self, ticket_id: GlpiId, document_link_id: GlpiId
-    ) -> GetTimelineDocument:
-        """Fetch one timeline document link by identifier.
+    ) -> GetDocument:
+        """Fetch one document linked to the ticket timeline by its document ID.
 
         Parameters
         ----------
         ticket_id : GlpiId
             Numeric identifier of the parent ticket.
         document_link_id : GlpiId
-            Numeric identifier of the timeline document link to retrieve.
+            Numeric identifier of the linked document to retrieve.
 
         Returns
         -------
-        GetTimelineDocument
-            Validated document-link payload.
+        GetDocument
+            Validated document payload.
 
         Raises
         ------
@@ -85,7 +86,7 @@ class TimelineDocumentMixin(TransportMixin):
         return self._resource_get(
             f"{TICKET_ENDPOINT}/{ticket_id}/"
             f"{TIMELINE_DOCUMENT_SUFFIX}/{document_link_id}",
-            GetTimelineDocument,
+            GetDocument,
             failure_message=(
                 f"Failed to get timeline document {document_link_id} on "
                 f"ticket {ticket_id}"

{glpi_python_client-0.3.1 → glpi_python_client-0.3.3}/glpi_python_client/clients/async_client.py

@@ -50,6 +50,7 @@ from glpi_python_client.clients.commons._config import (
     build_client_resources,
 )
 from glpi_python_client.clients.commons._transport import TransportMixin
+from glpi_python_client.clients.custom._pagination_async import AsyncPaginationMixin
 from glpi_python_client.clients.custom._statistics_async import AsyncStatisticsMixin
 from glpi_python_client.clients.custom._ticket_context_async import (
     AsyncTicketContextMixin,
@@ -61,8 +62,9 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-class AsyncGlpiClient(
+class AsyncGlpiClient(  # type: ignore[misc]
     AsyncBridge,
+    AsyncPaginationMixin,
     TicketMixin,
     TicketTaskMixin,
     FollowupMixin,

{glpi_python_client-0.3.1 → glpi_python_client-0.3.3}/glpi_python_client/clients/commons/_async_bridge.py

@@ -22,6 +22,23 @@ Concurrency notes
   releases the awaiter immediately, but the in-flight HTTP request keeps
   running on the worker thread until ``requests`` returns. This matches
   the behaviour of the original async client.
+
+Known limitation — internal ``self``-calls
+------------------------------------------
+The bridge wraps *every* public method on the async client class. As a
+result, when a synchronous body that is running inside a worker thread
+calls another public method through ``self`` (e.g.
+``self.search_tickets(...)``), it resolves to the *bridge-wrapped*
+coroutine, not the synchronous function. Calling a coroutine without
+``await`` produces a dangling coroutine object, not data.
+
+Any sync method (or generator) that internally calls other public
+methods through ``self`` must therefore be given a hand-written async
+override that ``await``s (or ``async for``s) those calls on the event
+loop. The convention used in this codebase is to place such overrides
+in a ``_*_async.py`` companion module (e.g.
+``clients/custom/_statistics_async.py``) and wire them into the async
+client's MRO *before* the sync mixin that defines the original method.
 """
 
 from __future__ import annotations

{glpi_python_client-0.3.1 → glpi_python_client-0.3.3}/glpi_python_client/clients/custom/__init__.py

@@ -17,6 +17,7 @@ composed into :class:`~glpi_python_client.clients.AsyncGlpiClient`.
 
 from __future__ import annotations
 
+from glpi_python_client.clients.custom._pagination_async import AsyncPaginationMixin
 from glpi_python_client.clients.custom._statistics import StatisticsMixin
 from glpi_python_client.clients.custom._statistics_async import AsyncStatisticsMixin
 from glpi_python_client.clients.custom._ticket_context import TicketContextMixin
@@ -25,6 +26,7 @@ from glpi_python_client.clients.custom._ticket_context_async import (
 )
 
 __all__ = [
+    "AsyncPaginationMixin",
     "AsyncStatisticsMixin",
     "AsyncTicketContextMixin",
     "StatisticsMixin",

glpi_python_client-0.3.3/glpi_python_client/clients/custom/_pagination_async.py

@@ -0,0 +1,164 @@
+"""Asynchronous overrides for the three paginated search generators.
+
+Each of the three ``iter_search_*`` generators in the API mixins
+delegates its pagination loop to a ``self.search_*()`` call.  When the
+:class:`~glpi_python_client.clients.commons._async_bridge.AsyncBridge`
+wraps a sync generator it drives ``next()`` on the generator object inside
+a worker thread.  Inside that thread ``self`` is still the
+:class:`~glpi_python_client.clients.AsyncGlpiClient` instance, so
+``self.search_tickets(...)`` resolves to the bridge-wrapped coroutine
+function and calling it without ``await`` returns a coroutine object
+instead of the expected list — triggering a
+``RuntimeWarning: coroutine … was never awaited`` and a 500 response.
+
+This mixin replaces all three generators with native async generators that
+``await self.search_*(...)`` directly on the event loop.
+
+The mixin must be positioned **before** ``TicketMixin``, ``UserMixin``, and
+``EntityMixin`` in the :class:`~glpi_python_client.clients.AsyncGlpiClient`
+base list so that the bridge's ``__init_subclass__`` hook finds the async
+generator via ``getattr`` before it would otherwise wrap the sync version.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+
+from glpi_python_client.models.api_schema.administration._entity import GetEntity
+from glpi_python_client.models.api_schema.administration._user import GetUser
+from glpi_python_client.models.api_schema.assistance._ticket import GetTicket
+
+
+class AsyncPaginationMixin:
+    """Async generator overrides for the three paginated search helpers.
+
+    Each override re-implements the simple ``start``-advancing loop of
+    the synchronous counterpart but ``await``\\ s the underlying
+    ``search_*`` call so it runs on the event loop rather than inside a
+    worker-thread-dispatched ``next()`` call where the coroutine would
+    be dropped on the floor.
+    """
+
+    async def iter_search_tickets(
+        self,
+        rsql_filter: str = "",
+        *,
+        batch_size: int = 50,
+        sort: str | None = None,
+        fields: tuple[str, ...] = (),
+    ) -> AsyncIterator[list[GetTicket]]:
+        """Yield successive pages of GLPI tickets until exhausted.
+
+        Parameters
+        ----------
+        rsql_filter : str, optional
+            Raw RSQL filter forwarded as the ``filter`` query parameter.
+            Empty by default, which lists every visible ticket.
+        batch_size : int, optional
+            Number of records requested per page (default 50).
+        sort : str | None, optional
+            ``sort`` query parameter forwarded as-is to each page request.
+        fields : tuple[str, ...], optional
+            Restricted set of contract field names to request.
+
+        Yields
+        ------
+        list[GetTicket]
+            One page of tickets per iteration. The last yielded batch may
+            be shorter than ``batch_size``.
+        """
+
+        start = 0
+        while True:
+            batch: list[GetTicket] = await self.search_tickets(  # type: ignore[attr-defined]
+                rsql_filter,
+                limit=batch_size,
+                start=start,
+                sort=sort,
+                fields=fields,
+            )
+            if batch:
+                yield batch
+            if len(batch) < batch_size:
+                break
+            start += batch_size
+
+    async def iter_search_users(
+        self,
+        rsql_filter: str = "",
+        *,
+        batch_size: int = 50,
+        skip_entity: bool = False,
+    ) -> AsyncIterator[list[GetUser]]:
+        """Yield successive pages of GLPI users until exhausted.
+
+        Parameters
+        ----------
+        rsql_filter : str, optional
+            Raw RSQL filter forwarded as the ``filter`` query parameter.
+            Empty by default, which lists every visible user.
+        batch_size : int, optional
+            Number of records requested per page (default 50).
+        skip_entity : bool, optional
+            When ``True`` the ``GLPI-Entity`` header is omitted so the
+            search spans every entity the caller has access to.
+
+        Yields
+        ------
+        list[GetUser]
+            One page of users per iteration. The last yielded batch may
+            be shorter than ``batch_size``.
+        """
+
+        start = 0
+        while True:
+            batch: list[GetUser] = await self.search_users(  # type: ignore[attr-defined]
+                rsql_filter,
+                limit=batch_size,
+                start=start,
+                skip_entity=skip_entity,
+            )
+            if batch:
+                yield batch
+            if len(batch) < batch_size:
+                break
+            start += batch_size
+
+    async def iter_search_entities(
+        self,
+        rsql_filter: str = "",
+        *,
+        batch_size: int = 50,
+    ) -> AsyncIterator[list[GetEntity]]:
+        """Yield successive pages of GLPI entities until exhausted.
+
+        Parameters
+        ----------
+        rsql_filter : str, optional
+            Raw RSQL filter forwarded as the ``filter`` query parameter.
+            Empty by default, which lists every accessible entity.
+        batch_size : int, optional
+            Number of records requested per page (default 50).
+
+        Yields
+        ------
+        list[GetEntity]
+            One page of entities per iteration. The last yielded batch
+            may be shorter than ``batch_size``.
+        """
+
+        start = 0
+        while True:
+            batch: list[GetEntity] = await self.search_entities(  # type: ignore[attr-defined]
+                rsql_filter,
+                limit=batch_size,
+                start=start,
+            )
+            if batch:
+                yield batch
+            if len(batch) < batch_size:
+                break
+            start += batch_size
+
+
+__all__ = ["AsyncPaginationMixin"]