glpi-python-client 0.3.2__tar.gz → 0.3.4__tar.gz

{glpi_python_client-0.3.2 → glpi_python_client-0.3.4}/.gitignore

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

{glpi_python_client-0.3.2 → glpi_python_client-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: glpi-python-client
-Version: 0.3.2
+Version: 0.3.4
 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.2 → glpi_python_client-0.3.4}/docs/api_reference.rst

@@ -289,6 +289,36 @@ Entities
    :undoc-members:
    :show-inheritance:
 
+Plugin: Fields (custom fields)
+------------------------------
+
+Schemas returned by the GLPI ``Fields`` plugin (legacy v1 REST endpoints).
+The companion mixin methods are exposed on :class:`GlpiClient` /
+:class:`AsyncGlpiClient` as ``list_plugin_fields_containers``,
+``list_plugin_fields_fields``, ``list_item_plugin_field_rows``,
+``create_item_plugin_field_row``, ``update_item_plugin_field_row``,
+``get_ticket_custom_fields`` and ``set_ticket_custom_fields``.
+
+.. autoclass:: GetPluginFieldsContainer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: GetPluginFieldsField
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: GetPluginFieldsValueRow
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: PostPluginFieldsValueRow
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Enums
 -----
 

glpi_python_client-0.3.4/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.2 → glpi_python_client-0.3.4}/docs/user_guide.rst

@@ -11,8 +11,10 @@ whose surface is built from contract-aligned per-endpoint mixins:
   it to a worker thread via :func:`asyncio.to_thread`.
 
 Both clients speak the GLPI **v2** high-level API and fall back to the
-legacy v1 endpoint only for binary document uploads. They expose the
-exact same endpoint methods and accept the same constructor arguments.
+legacy v1 API for features that are not exposed by v2, currently
+binary document uploads and the ``Fields`` plugin custom-field
+helpers. They expose the exact same endpoint methods and accept the
+same constructor arguments.
 Public methods always return Pydantic models (or simple Python types)
 and never raw dictionaries.
 
@@ -36,7 +38,8 @@ The guide is split into the following sections:
    one-to-one to GLPI v2 endpoints (tickets, timeline, team members,
    users, locations, entities, documents).
 5. **Added functionalities** — helpers built on top of the API mixins:
-   the aggregated ticket context view and the reporting helpers.
+    the ``Fields`` plugin custom-field helpers, the aggregated ticket
+    context view, and the reporting helpers.
 6. **End-to-end examples** — full workflows that combine the previous
    building blocks.
 
@@ -111,7 +114,9 @@ Optional constructor arguments
 * ``auth_token_refresh`` — number of seconds before token expiry at
   which the auth manager proactively refreshes the OAuth access token.
 * ``v1_base_url`` and ``v1_user_token`` — together enable the legacy v1
-  fallback used by :meth:`GlpiClient.upload_document`.
+    fallback used by :meth:`GlpiClient.upload_document` and the
+    ``Fields`` plugin helpers such as
+    :meth:`GlpiClient.get_ticket_custom_fields`.
 * ``executor`` (:class:`AsyncGlpiClient` only) — an explicit
   :class:`concurrent.futures.Executor` used to dispatch the wrapped
   synchronous calls. Defaults to the standard library thread pool
@@ -616,6 +621,55 @@ Example output::
 The helpers in this section are not part of the GLPI contract. They are
 small utilities the client builds on top of the API mixins.
 
+Ticket custom fields via the Fields plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `Fields plugin <https://github.com/pluginsGLPI/fields>`_ exposes
+ticket custom fields through the legacy v1 API rather than the GLPI v2
+contract. Configure the client with ``v1_base_url`` and
+``v1_user_token`` (or the matching ``GLPI_V1_*`` environment
+variables), then use the discovery helpers when you need the plugin's
+internal container and field names:
+
+.. code-block:: python
+
+    from glpi_python_client import GlpiClient
+
+   with GlpiClient(
+       glpi_api_url="https://glpi.example.com/api.php/v2",
+       client_id="oauth-client-id",
+       client_secret="oauth-client-secret",
+       username="api-user",
+       password="api-password",
+       v1_base_url="https://glpi.example.com/apirest.php",
+       v1_user_token="legacy-user-token",
+   ) as client:
+       containers = client.list_plugin_fields_containers(itemtype="Ticket")
+       for container in containers:
+           print(container.id, container.name)
+           fields = client.list_plugin_fields_fields(container_id=container.id)
+           print([field.name for field in fields])
+
+       custom_fields = client.get_ticket_custom_fields(ticket_id)
+       print(custom_fields)
+
+       client.set_ticket_custom_fields(
+           ticket_id,
+           {
+               "aidelarsolution": {
+                   "aidelarsolutionfield": "<p>Handled by the NOC shift</p>",
+               }
+           },
+       )
+
+The high-level ``get_ticket_custom_fields`` /
+``set_ticket_custom_fields`` pair uses the mapping
+``{container_name: {field_name: value}}`` and automatically decides
+whether the v1 plugin needs a row creation or an in-place update. Drop
+to ``list_item_plugin_field_rows``, ``create_item_plugin_field_row``,
+or ``update_item_plugin_field_row`` only when you need the raw v1 row
+shape.
+
 Aggregated ticket context
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -776,6 +830,12 @@ 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 errors.
+
 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 +850,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 +955,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.2 → glpi_python_client-0.3.4}/glpi_python_client/__init__.py

@@ -30,6 +30,9 @@ from glpi_python_client.models import (
     GetEntity,
     GetFollowup,
     GetLocation,
+    GetPluginFieldsContainer,
+    GetPluginFieldsField,
+    GetPluginFieldsValueRow,
     GetSolution,
     GetTeamMember,
     GetTicket,
@@ -63,6 +66,7 @@ from glpi_python_client.models import (
     PostEntity,
     PostFollowup,
     PostLocation,
+    PostPluginFieldsValueRow,
     PostSolution,
     PostTeamMember,
     PostTicket,
@@ -72,7 +76,7 @@ from glpi_python_client.models import (
     TicketMarkdownOptions,
 )
 
-__version__ = "0.3.2"
+__version__ = "0.3.4"
 
 __all__ = [
     "AsyncGlpiClient",
@@ -90,6 +94,9 @@ __all__ = [
     "GetEntity",
     "GetFollowup",
     "GetLocation",
+    "GetPluginFieldsContainer",
+    "GetPluginFieldsField",
+    "GetPluginFieldsValueRow",
     "GetSolution",
     "GetTeamMember",
     "GetTicket",
@@ -124,6 +131,7 @@ __all__ = [
     "PostEntity",
     "PostFollowup",
     "PostLocation",
+    "PostPluginFieldsValueRow",
     "PostSolution",
     "PostTeamMember",
     "PostTicket",