glpi-python-client 0.2.0__tar.gz → 0.3.0__tar.gz

{glpi_python_client-0.2.0 → glpi_python_client-0.3.0}/CONTRIBUTING.md

@@ -50,7 +50,11 @@ python -m sphinx -W --keep-going -b html docs docs/_build/html
 
 ## Design Guidelines
 
-- Keep API calls behind `GlpiClient` methods.
+- Keep API calls behind `GlpiClient` / `AsyncGlpiClient` methods. Add
+  new endpoints to a sync endpoint mixin only; `AsyncGlpiClient`
+  exposes them as coroutines automatically through `AsyncBridge`. Only
+  add a dedicated async override when the method needs concurrent
+  fan-out via `asyncio.gather`.
 - Prefer field-validated Pydantic models for request and response payloads.
 - Avoid organization-specific category, entity, or profile defaults in the
   library core.

{glpi_python_client-0.2.0 → glpi_python_client-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: glpi-python-client
-Version: 0.2.0
+Version: 0.3.0
 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/
@@ -62,7 +62,7 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://github.com/baraline/glpi_python_client)
 [![Docs](https://readthedocs.org/projects/glpi-python-client/badge/?version=latest)](https://glpi-python-client.readthedocs.io/en/latest/)
 
-`glpi-python-client` is a typed Python client for GLPI ITSM APIs.
+`glpi-python-client` is a typed Python client for the GLPI REST API.
 
 The goal is to let GLPI integrations work with domain objects instead of raw
 JSON payloads. The package exposes Pydantic models for tickets, users,
@@ -70,8 +70,16 @@ followups, documents, locations, and related records, while converting GLPI
 HTML content into Markdown for Python-side workflows and rendering Markdown
 back to HTML for outgoing payloads.
 
-It currently focuses on ticket-centric workflows and exposes a single
-asynchronous high-level client built on top of the GLPI v2 REST API.
+It currently focuses on ticket-centric workflows and exposes two high-level
+clients built on top of the GLPI v2 REST API:
+
+- `GlpiClient` — synchronous, blocking client (single source of truth for
+  endpoint behaviour).
+- `AsyncGlpiClient` — asynchronous facade that wraps every synchronous
+  method into a coroutine and dispatches it to a worker thread.
+
+Note that all integration tests using this package are made on GLPI 11.
+I cannot make any guarantee of the behaviour on previous versions.
 
 While the package is preparing for 1.0, alot of potential breaking change might happen between versions. A deprecation policy will be put in place once 1.0 is out and the package have been stabilized.
 
@@ -96,14 +104,38 @@ Create a client with your GLPI v2 API URL and at least one complete auth pair:
 - `username` and `password`
 - both pairs together
 
+### Synchronous client
+
+```python
+from glpi_python_client import GlpiClient, PostTicket
+
+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",
+) as glpi:
+    ticket_id = glpi.create_ticket(
+        PostTicket(
+            name="Printer issue",
+            content="The printer is not reachable from the office network.",
+        )
+    )
+    ticket = glpi.get_ticket(ticket_id)
+    print(ticket.id, ticket.name)
+```
+
+### Asynchronous client
+
 ```python
 import asyncio
 
-from glpi_python_client import GlpiClient, PostTicket
+from glpi_python_client import AsyncGlpiClient, PostTicket
 
 
 async def main() -> None:
-    async with GlpiClient(
+    async with AsyncGlpiClient(
         glpi_api_url="https://glpi.example.com/api.php/v2",
         client_id="oauth-client-id",
         client_secret="oauth-client-secret",
@@ -123,38 +155,22 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-If your application already provides `GLPI_` environment variables,
-`GlpiClient.from_env()` is also available.
+`GlpiClient.from_env()` and `AsyncGlpiClient.from_env()` are also available
+when the credentials are already exposed as `GLPI_`-prefixed environment
+variables.
 
-### Calling from synchronous code
+### Sync or async?
 
-The client is async-only, but it works from sync programs through
-`asyncio.run`. Wrap the calls in a coroutine and execute it once:
-
-```python
-import asyncio
-
-from glpi_python_client import GlpiClient
-
-
-def fetch_open_tickets() -> list[int]:
-    async def _run() -> list[int]:
-        async with GlpiClient.from_env() as glpi:
-            tickets = await glpi.search_tickets("status==1", limit=10)
-            return [ticket.id for ticket in tickets]
-
-    return asyncio.run(_run())
-
-
-if __name__ == "__main__":
-    print(fetch_open_tickets())
-```
-
-For long-lived sync services that need many calls, run a dedicated
-event loop on a background thread and dispatch with
-`asyncio.run_coroutine_threadsafe`. See the
-[user guide](https://glpi-python-client.readthedocs.io/en/latest/user_guide.html#calling-the-client-from-synchronous-code)
-for the full pattern.
+Both clients expose the exact same endpoint surface and accept the same
+constructor arguments. The async client is a thin facade that wraps each
+synchronous method into a coroutine dispatched to a worker thread via
+`asyncio.to_thread` (or a caller-supplied `concurrent.futures.Executor`).
+A shared `threading.Lock` serialises OAuth token acquisition so concurrent
+`asyncio.gather(...)` fan-outs cannot race. Pick `GlpiClient` for plain
+scripts, CLI tools, and synchronous services; pick `AsyncGlpiClient` when
+your application already runs an event loop or when you need concurrent
+fan-out (the aggregated `get_ticket_context` and per-ticket
+`get_task_statistics` helpers use `asyncio.gather` on the async client).
 
 ## Documentation
 
@@ -169,3 +185,9 @@ To build the Sphinx documentation locally:
 python -m pip install -e .[docs]
 python -m sphinx -b html docs docs/_build/html
 ```
+
+## Sponsoring & Professional services
+The development of this package is indirectly supported by [Novahé](https://www.novahe.fr/) & [Constellation](https://www.constellation.fr/).
+
+If you need professional help or services around GLPI, we offer consulting and engineering services to install, maintain or upgarde GLPI instance, as an [official GLPI partner](https://www.glpi-project.org/fr/new-glpi-silver-partner-in-france-novahe/).
+

{glpi_python_client-0.2.0 → glpi_python_client-0.3.0}/README.md

@@ -6,7 +6,7 @@
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://github.com/baraline/glpi_python_client)
 [![Docs](https://readthedocs.org/projects/glpi-python-client/badge/?version=latest)](https://glpi-python-client.readthedocs.io/en/latest/)
 
-`glpi-python-client` is a typed Python client for GLPI ITSM APIs.
+`glpi-python-client` is a typed Python client for the GLPI REST API.
 
 The goal is to let GLPI integrations work with domain objects instead of raw
 JSON payloads. The package exposes Pydantic models for tickets, users,
@@ -14,8 +14,16 @@ followups, documents, locations, and related records, while converting GLPI
 HTML content into Markdown for Python-side workflows and rendering Markdown
 back to HTML for outgoing payloads.
 
-It currently focuses on ticket-centric workflows and exposes a single
-asynchronous high-level client built on top of the GLPI v2 REST API.
+It currently focuses on ticket-centric workflows and exposes two high-level
+clients built on top of the GLPI v2 REST API:
+
+- `GlpiClient` — synchronous, blocking client (single source of truth for
+  endpoint behaviour).
+- `AsyncGlpiClient` — asynchronous facade that wraps every synchronous
+  method into a coroutine and dispatches it to a worker thread.
+
+Note that all integration tests using this package are made on GLPI 11.
+I cannot make any guarantee of the behaviour on previous versions.
 
 While the package is preparing for 1.0, alot of potential breaking change might happen between versions. A deprecation policy will be put in place once 1.0 is out and the package have been stabilized.
 
@@ -40,14 +48,38 @@ Create a client with your GLPI v2 API URL and at least one complete auth pair:
 - `username` and `password`
 - both pairs together
 
+### Synchronous client
+
+```python
+from glpi_python_client import GlpiClient, PostTicket
+
+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",
+) as glpi:
+    ticket_id = glpi.create_ticket(
+        PostTicket(
+            name="Printer issue",
+            content="The printer is not reachable from the office network.",
+        )
+    )
+    ticket = glpi.get_ticket(ticket_id)
+    print(ticket.id, ticket.name)
+```
+
+### Asynchronous client
+
 ```python
 import asyncio
 
-from glpi_python_client import GlpiClient, PostTicket
+from glpi_python_client import AsyncGlpiClient, PostTicket
 
 
 async def main() -> None:
-    async with GlpiClient(
+    async with AsyncGlpiClient(
         glpi_api_url="https://glpi.example.com/api.php/v2",
         client_id="oauth-client-id",
         client_secret="oauth-client-secret",
@@ -67,38 +99,22 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-If your application already provides `GLPI_` environment variables,
-`GlpiClient.from_env()` is also available.
+`GlpiClient.from_env()` and `AsyncGlpiClient.from_env()` are also available
+when the credentials are already exposed as `GLPI_`-prefixed environment
+variables.
 
-### Calling from synchronous code
+### Sync or async?
 
-The client is async-only, but it works from sync programs through
-`asyncio.run`. Wrap the calls in a coroutine and execute it once:
-
-```python
-import asyncio
-
-from glpi_python_client import GlpiClient
-
-
-def fetch_open_tickets() -> list[int]:
-    async def _run() -> list[int]:
-        async with GlpiClient.from_env() as glpi:
-            tickets = await glpi.search_tickets("status==1", limit=10)
-            return [ticket.id for ticket in tickets]
-
-    return asyncio.run(_run())
-
-
-if __name__ == "__main__":
-    print(fetch_open_tickets())
-```
-
-For long-lived sync services that need many calls, run a dedicated
-event loop on a background thread and dispatch with
-`asyncio.run_coroutine_threadsafe`. See the
-[user guide](https://glpi-python-client.readthedocs.io/en/latest/user_guide.html#calling-the-client-from-synchronous-code)
-for the full pattern.
+Both clients expose the exact same endpoint surface and accept the same
+constructor arguments. The async client is a thin facade that wraps each
+synchronous method into a coroutine dispatched to a worker thread via
+`asyncio.to_thread` (or a caller-supplied `concurrent.futures.Executor`).
+A shared `threading.Lock` serialises OAuth token acquisition so concurrent
+`asyncio.gather(...)` fan-outs cannot race. Pick `GlpiClient` for plain
+scripts, CLI tools, and synchronous services; pick `AsyncGlpiClient` when
+your application already runs an event loop or when you need concurrent
+fan-out (the aggregated `get_ticket_context` and per-ticket
+`get_task_statistics` helpers use `asyncio.gather` on the async client).
 
 ## Documentation
 
@@ -113,3 +129,9 @@ To build the Sphinx documentation locally:
 python -m pip install -e .[docs]
 python -m sphinx -b html docs docs/_build/html
 ```
+
+## Sponsoring & Professional services
+The development of this package is indirectly supported by [Novahé](https://www.novahe.fr/) & [Constellation](https://www.constellation.fr/).
+
+If you need professional help or services around GLPI, we offer consulting and engineering services to install, maintain or upgarde GLPI instance, as an [official GLPI partner](https://www.glpi-project.org/fr/new-glpi-silver-partner-in-france-novahe/).
+

{glpi_python_client-0.2.0 → glpi_python_client-0.3.0}/docs/api_reference.rst

@@ -7,14 +7,27 @@ underscore-prefixed helpers are intentionally omitted.
 
 .. currentmodule:: glpi_python_client
 
-Client
-------
+Clients
+-------
+
+The package exposes two clients with identical endpoint surfaces. The
+synchronous one is the single source of truth for endpoint behaviour;
+the asynchronous one wraps each synchronous method into a coroutine.
 
 .. autoclass:: GlpiClient
    :members:
    :inherited-members:
    :show-inheritance:
 
+.. autoclass:: AsyncGlpiClient
+   :members:
+   :inherited-members:
+   :show-inheritance:
+
+.. autoclass:: glpi_python_client.clients.commons._async_bridge.AsyncBridge
+   :members:
+   :show-inheritance:
+
 Aggregated Models
 -----------------
 
@@ -23,6 +36,11 @@ Aggregated Models
    :undoc-members:
    :show-inheritance:
 
+.. autoclass:: TicketMarkdownOptions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Common Reference Models
 -----------------------
 

glpi_python_client-0.3.0/docs/development.md

@@ -0,0 +1,109 @@
+# Development Guide
+
+## Local Setup
+
+Create a virtual environment and install the package with development dependencies:
+
+```bash
+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.
+
+## Checks
+
+Run these before publishing or opening a pull request:
+
+```bash
+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
+python -m build
+python -m vulture glpi_python_client --min-confidence 80
+```
+
+If your global Python environment has broken pytest plugins, run the suite with
+plugin autoload disabled:
+
+```bash
+$env:PYTEST_DISABLE_PLUGIN_AUTOLOAD = "1"
+python -m pytest
+```
+
+## Package Layout
+
+- `glpi_python_client.__init__` exposes the public import surface,
+  including both client classes and the Pydantic models.
+- `glpi_python_client.clients.sync_client.GlpiClient` is the
+  synchronous, blocking client. It is the single source of truth for
+  endpoint behaviour: each public method lives on one of the sync
+  endpoint mixins under `glpi_python_client.clients.api.*` and
+  `glpi_python_client.clients.custom.*`.
+- `glpi_python_client.clients.async_client.AsyncGlpiClient` is the
+  asynchronous facade. It inherits the same endpoint mixins and uses
+  `glpi_python_client.clients.commons._async_bridge.AsyncBridge` to wrap
+  every inherited public sync method into a coroutine dispatched on a
+  worker thread (`asyncio.to_thread` by default, or a caller-supplied
+  `concurrent.futures.Executor`).
+- `glpi_python_client.clients.commons` holds the reusable building
+  blocks shared by every endpoint mixin: configuration helpers
+  (`_config`), constants (`_constants`), errors (`_errors`), filters
+  (`_filters`), HTTP helpers (`_http`), payload builders (`_payloads`),
+  the synchronous `TransportMixin` (`_transport`), and the
+  `AsyncBridge` (`_async_bridge`). A shared `threading.Lock` in the
+  transport serialises OAuth token acquisition so concurrent
+  `asyncio.gather` fan-outs on the async client cannot race.
+- `glpi_python_client.clients.api.*` contains the contract-aligned
+  synchronous endpoint mixins, grouped by GLPI subtree (administration,
+  assistance, assistance/timeline, dropdowns, management).
+- `glpi_python_client.clients.custom` contains custom helpers built on
+  top of the API mixins. Each helper has a synchronous implementation
+  (`_ticket_context.py`, `_statistics.py`) plus an optional async
+  override (`_ticket_context_async.py`, `_statistics_async.py`) that
+  fans the underlying calls out concurrently with `asyncio.gather`.
+- `glpi_python_client.auth._v1_session` contains the legacy v1
+  session used for binary document uploads.
+- `glpi_python_client.models` contains typed request and response
+  models.
+- `glpi_python_client.content` handles HTML/Markdown conversion for
+  ticket descriptions, followups, tasks, and solutions.
+- `glpi_python_client.testing` exposes `make_client` and
+  `make_async_client` factories that produce in-memory clients with no
+  real HTTP plumbing for downstream test suites.
+- `docs` contains the Read the Docs/Sphinx documentation source.
+- `skills` contains contributor-facing Agent Skills for repository
+  workflows. The source distribution includes them for source consumers
+  and contributors, but the wheel still installs only the
+  `glpi_python_client` runtime package.
+
+## Adding Endpoints
+
+1. Add or extend a model in `glpi_python_client.models`.
+2. Add the client method on the matching **synchronous** endpoint mixin
+   under `glpi_python_client.clients.api.*` (or
+   `glpi_python_client.clients.custom.*` for derived helpers). The
+   async client picks the new method up automatically through the
+   `AsyncBridge` — do not duplicate the method on a parallel async
+   mixin unless you genuinely need concurrent fan-out (`asyncio.gather`)
+   inside the method body.
+3. Put reusable endpoint names, payload builders, response handling, or
+   pagination logic in the focused
+   `glpi_python_client.clients.commons` helper module named for that
+   responsibility.
+4. Add unit tests for payload serialization, response parsing, and
+   client behavior. The parity test in
+   `glpi_python_client/clients/tests/test_parity.py` will fail if the
+   sync and async surfaces diverge.
+5. Document the new workflow in `docs/user_guide.rst` or the README.
+
+Keep organization-specific defaults outside the package core.
+Applications can map their own entities, profiles, and categories
+before calling the client.

{glpi_python_client-0.2.0 → glpi_python_client-0.3.0}/docs/index.rst

@@ -24,6 +24,7 @@ handling, and helpers for ticket, user, location, and document workflows.
 
    development_rtd
    publishing_rtd
+   sponsoring
 
 Indices and Tables
 ==================

glpi_python_client-0.3.0/docs/sponsoring.rst

@@ -0,0 +1,9 @@
+Sponsoring & Professional Services
+===================================
+
+The development of this package is indirectly supported by
+`Novahé <https://www.novahe.fr/>`_ & `Constellation <https://www.constellation.fr/>`_.
+
+If you need professional help or services around GLPI, we offer consulting and
+engineering services to install, maintain, or upgrade GLPI instances, as an
+`official GLPI partner <https://www.glpi-project.org/fr/new-glpi-silver-partner-in-france-novahe/>`_.