bugfix for Document endpoints and stats date filters, add integration tests

Author: baraline

.github/workflows/release.yml

@@ -38,7 +38,7 @@ jobs:
           python -m pip install -e .[dev]
 
       - name: Run tests
-        run: python -m pytest
+        run: python -m pytest -m "not integration"
 
   quality:
     name: Release quality checks

.gitignore

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

docs/development_rtd.rst

@@ -31,6 +31,84 @@ Run the focused checks before opening a pull request:
    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
 --------------
 

docs/user_guide.rst

@@ -776,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``:
@@ -790,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;
@@ -893,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/__init__.py

@@ -72,7 +72,7 @@
     TicketMarkdownOptions,
 )
 
-__version__ = "0.3.2"
+__version__ = "0.3.3"
 
 __all__ = [
     "AsyncGlpiClient",

glpi_python_client/clients/api/assistance/timeline/_document.py

@@ -7,11 +7,12 @@
 -----
 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._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 @@ def list_ticket_timeline_documents(
 
         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 @@ def list_ticket_timeline_documents(
 
     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 @@ def get_ticket_timeline_document(
         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/clients/custom/_statistics.py

@@ -95,10 +95,12 @@ def get_ticket_statistics(
         Parameters
         ----------
         start_date : str | None, optional
-            ISO ``YYYY-MM-DD`` start of the window. Defaults to
-            ``end_date - default_days + 1`` when omitted.
+            ISO ``YYYY-MM-DD`` start of the window (inclusive from
+            00:00:00). Defaults to ``end_date - default_days + 1``
+            when omitted.
         end_date : str | None, optional
-            ISO ``YYYY-MM-DD`` end of the window. Defaults to today.
+            ISO ``YYYY-MM-DD`` end of the window (inclusive through
+            23:59:59). Defaults to today.
         default_days : int, optional
             Span in days used when ``start_date`` is omitted (defaults
             to 30 and must be a positive integer).
@@ -147,9 +149,10 @@ def get_ticket_statistics(
             entity_filter = rsql_any_filter(
                 *(f"entities_id=={e.id}" for e in entities if e.id is not None)
             )
-
+        date_filter = f"date_creation=ge={start.isoformat()};"
+        date_filter += f"date_creation=le={end.isoformat()} 23:59:59"
         query = rsql_all_filter(
-            f"date_creation=ge={start.isoformat()};date_creation=le={end.isoformat()}",
+            date_filter,
             entity_filter,
             extra_filter,
         )
@@ -226,10 +229,12 @@ def get_task_durations(
         Parameters
         ----------
         start_date : str | None, optional
-            ISO ``YYYY-MM-DD`` start of the window. Defaults to
-            ``end_date - default_days + 1`` when omitted.
+            ISO ``YYYY-MM-DD`` start of the window (inclusive from
+            00:00:00). Defaults to ``end_date - default_days + 1``
+            when omitted.
         end_date : str | None, optional
-            ISO ``YYYY-MM-DD`` end of the window. Defaults to today.
+            ISO ``YYYY-MM-DD`` end of the window (inclusive through
+            23:59:59). Defaults to today.
         default_days : int, optional
             Span in days used when ``start_date`` is omitted (defaults
             to 30 and must be a positive integer).
@@ -269,9 +274,8 @@ def get_task_durations(
             end_date=end_date,
             default_days=default_days,
         )
-        date_filter = (
-            f"date_creation=ge={start.isoformat()};date_creation=le={end.isoformat()}"
-        )
+        date_filter = f"date_creation=ge={start.isoformat()};"
+        date_filter += f"date_creation=le={end.isoformat()} 23:59:59"
 
         entity_filter: str | None = None
         if entity_id is not None:
@@ -399,9 +403,11 @@ def get_user_activity(
         firstname : str | None, optional
             Filter by given name (substring match).
         start_date : str | None, optional
-            ISO ``YYYY-MM-DD`` start of the activity window.
+            ISO ``YYYY-MM-DD`` start of the activity window (inclusive
+            from 00:00:00).
         end_date : str | None, optional
-            ISO ``YYYY-MM-DD`` end of the activity window. Defaults to today.
+            ISO ``YYYY-MM-DD`` end of the activity window (inclusive
+            through 23:59:59). Defaults to today.
         default_days : int, optional
             Span in days used when ``start_date`` is omitted (default 30).
 
@@ -460,9 +466,8 @@ def get_user_activity(
                 if u.id is not None
             }
 
-        date_range = (
-            f"date_creation=ge={start.isoformat()};date_creation=le={end.isoformat()}"
-        )
+        date_range = f"date_creation=ge={start.isoformat()};"
+        date_range += f"date_creation=le={end.isoformat()} 23:59:59"
 
         users_output: dict[str, UserActivityEntry] = {}
         for uid in resolved_user_ids: