glpi-python-client 0.3.4__py3-none-any.whl → 0.4.2__py3-none-any.whl

glpi_python_client/__init__.py

@@ -2,10 +2,13 @@
 
 The package re-exports two client classes:
 
-* :class:`GlpiClient` — synchronous, blocking client (single source of
-  truth for endpoint behaviour).
-* :class:`AsyncGlpiClient` — asynchronous facade that wraps each
-  synchronous method into a coroutine.
+* :class:`GlpiClient` — synchronous, blocking client.
+* :class:`AsyncGlpiClient` — asynchronous client doing real
+  non-blocking I/O on the event loop.
+
+They expose identical endpoint surfaces because they are the same
+code: the async tree is hand-written and the sync one is generated
+from it. Neither is a wrapper around the other.
 
 The ``api_schema`` and ``custom_schema`` Pydantic models are also
 re-exported so downstream users can import them from a single stable
@@ -14,11 +17,26 @@ package root.
 
 from __future__ import annotations
 
-from glpi_python_client.clients import AsyncGlpiClient, GlpiClient
+from glpi_python_client._async.clients import AsyncGlpiClient
+from glpi_python_client._errors import (
+    GlpiAuthError,
+    GlpiError,
+    GlpiNotFoundError,
+    GlpiProtocolError,
+    GlpiServerError,
+    GlpiStatusError,
+    GlpiTimeoutError,
+    GlpiTransportError,
+    GlpiValidationError,
+)
+from glpi_python_client._sync.clients import GlpiClient
 from glpi_python_client.models import (
     DeleteDocument,
     DeleteEntity,
     DeleteFollowup,
+    DeleteKBArticle,
+    DeleteKBArticleComment,
+    DeleteKBCategory,
     DeleteLocation,
     DeleteSolution,
     DeleteTeamMember,
@@ -29,6 +47,10 @@ from glpi_python_client.models import (
     GetDocument,
     GetEntity,
     GetFollowup,
+    GetKBArticle,
+    GetKBArticleComment,
+    GetKBArticleRevision,
+    GetKBCategory,
     GetLocation,
     GetPluginFieldsContainer,
     GetPluginFieldsField,
@@ -55,6 +77,9 @@ from glpi_python_client.models import (
     PatchDocument,
     PatchEntity,
     PatchFollowup,
+    PatchKBArticle,
+    PatchKBArticleComment,
+    PatchKBCategory,
     PatchLocation,
     PatchSolution,
     PatchTeamMember,
@@ -65,6 +90,9 @@ from glpi_python_client.models import (
     PostDocument,
     PostEntity,
     PostFollowup,
+    PostKBArticle,
+    PostKBArticleComment,
+    PostKBCategory,
     PostLocation,
     PostPluginFieldsValueRow,
     PostSolution,
@@ -76,13 +104,16 @@ from glpi_python_client.models import (
     TicketMarkdownOptions,
 )
 
-__version__ = "0.3.4"
+__version__ = "0.4.2"
 
 __all__ = [
     "AsyncGlpiClient",
     "DeleteDocument",
     "DeleteEntity",
     "DeleteFollowup",
+    "DeleteKBArticle",
+    "DeleteKBArticleComment",
+    "DeleteKBCategory",
     "DeleteLocation",
     "DeleteSolution",
     "DeleteTeamMember",
@@ -93,6 +124,10 @@ __all__ = [
     "GetDocument",
     "GetEntity",
     "GetFollowup",
+    "GetKBArticle",
+    "GetKBArticleComment",
+    "GetKBArticleRevision",
+    "GetKBCategory",
     "GetLocation",
     "GetPluginFieldsContainer",
     "GetPluginFieldsField",
@@ -103,23 +138,35 @@ __all__ = [
     "GetTicketTask",
     "GetTimelineDocument",
     "GetUser",
+    "GlpiAuthError",
     "GlpiClient",
     "GlpiEnum",
+    "GlpiError",
     "GlpiGlobalValidation",
+    "GlpiNotFoundError",
     "GlpiPriority",
+    "GlpiProtocolError",
+    "GlpiServerError",
     "GlpiSolutionStatus",
+    "GlpiStatusError",
     "GlpiTaskState",
     "GlpiTicketContext",
     "GlpiTicketStatus",
     "GlpiTicketType",
     "GlpiTimelinePosition",
+    "GlpiTimeoutError",
+    "GlpiTransportError",
     "GlpiUserAuthType",
+    "GlpiValidationError",
     "IdNameCompletenameRef",
     "IdNameRef",
     "IdRef",
     "PatchDocument",
     "PatchEntity",
     "PatchFollowup",
+    "PatchKBArticle",
+    "PatchKBArticleComment",
+    "PatchKBCategory",
     "PatchLocation",
     "PatchSolution",
     "PatchTeamMember",
@@ -130,6 +177,9 @@ __all__ = [
     "PostDocument",
     "PostEntity",
     "PostFollowup",
+    "PostKBArticle",
+    "PostKBArticleComment",
+    "PostKBCategory",
     "PostLocation",
     "PostPluginFieldsValueRow",
     "PostSolution",

glpi_python_client/_async/__init__.py

@@ -0,0 +1,15 @@
+"""Hand-written client tree.
+
+This package is the single source of truth for client code. Its sibling
+``glpi_python_client._sync`` is generated from it by ``unasync_build.py``
+and checked in; CI regenerates and diffs to keep the two from drifting.
+
+Prose written here is copied verbatim into the generated tree -- the
+codegen rewrites tokens, not sentences. Docstrings under this package are
+therefore worded so they read correctly on both surfaces: describe *what* a
+helper does, and leave whether it blocks or awaits to the signature.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

glpi_python_client/_async/_concurrency.py

@@ -0,0 +1,59 @@
+"""Asyncio concurrency primitives for the async client tree.
+
+This module and its ``_sync`` twin are the only files maintained by hand on
+both sides of the codegen. Everything else under ``_sync/`` is generated
+from ``_async/`` by :mod:`unasync`, which rewrites tokens and strips
+``async``/``await``. That works for syntax; it cannot work here, because the
+two surfaces need genuinely *different primitives*, not differently-spelled
+ones:
+
+* A fan-out is :func:`asyncio.gather` on this side and plain sequential
+  evaluation on the other. ``unasync`` leaves ``asyncio.gather`` untouched,
+  so a generated twin would call it from synchronous code and break.
+* The auth lock must be an :class:`asyncio.Lock` here and a
+  :class:`threading.Lock` there -- see :data:`Lock` for why substituting one
+  for the other is wrong in *both* directions.
+
+Keeping both twins tiny is deliberate: hand-maintained duplication is a
+liability, so it is confined to the smallest possible surface.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+#: Lock type guarding OAuth token acquisition on the async surface.
+#:
+#: An :class:`asyncio.Lock`, and the ``_sync`` twin uses a
+#: :class:`threading.Lock`. Neither choice is substitutable for the other,
+#: which is exactly why this is hand-written:
+#:
+#: * A :class:`threading.Lock` here would **deadlock**. The lock is held
+#:   across an ``await``, so a second task blocking on it blocks the whole
+#:   event loop -- and the task holding it can then never resume to release
+#:   it. A single-threaded loop has no way out of that.
+#: * An :class:`asyncio.Lock` on the sync side would be worse than useless:
+#:   it is bound to the loop that first contends it, so sharing one client
+#:   across threads raises ``RuntimeError: ... bound to a different event
+#:   loop`` and can deadlock a thread permanently. The failure is latent --
+#:   ``acquire()`` only looks up the loop on the *contended* path, so
+#:   uncontended use passes and tests stay green.
+Lock = asyncio.Lock
+
+
+async def gather(*awaitables: Any) -> list[Any]:
+    """Run ``awaitables`` concurrently and return their results in order.
+
+    The ``_sync`` twin takes already-computed values and simply returns
+    them. That is not a stub: once ``unasync`` strips the ``await`` from a
+    call site, each argument expression evaluates eagerly at the point it is
+    written, which *is* sequential execution. So the same call shape --
+    ``await gather(self.a(), self.b())`` -- means "concurrently" here and
+    "one after the other" there, with no change to the calling code.
+    """
+
+    return list(await asyncio.gather(*awaitables))
+
+
+__all__ = ["Lock", "gather"]

glpi_python_client/_async/_testing.py

@@ -0,0 +1,146 @@
+"""In-memory client factory and transport stubs for this tree's unit tests.
+
+One of a generated pair: the module is written once and
+``unasync_build.py`` transforms it into its twin in the other tree.
+``AsyncGlpiClient`` is already a substitution key, so each copy returns
+the client of the tree it lands in while the factory stays spelled
+``make_client`` on both sides -- call sites read identically wherever
+they are. The same holds for the two recorder classes: each replaces a
+client's four transport helpers with stubs that capture the call and hand
+back a fixed response, so a mixin test can assert the endpoint, verb and
+serialised body without any HTTP plumbing.
+
+It lives beside the tree rather than in ``glpi_python_client.testing``
+because that module is a published downstream helper whose factories must
+keep their current names; this one has to change its return type when the
+tree is transformed.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from glpi_python_client import AsyncGlpiClient
+from glpi_python_client.testing.utils import DEFAULT_CLIENT_CONFIG, FakeResponse
+
+__all__ = ["FailingTransportRecorder", "TransportRecorder", "make_client"]
+
+
+def make_client(**overrides: object) -> AsyncGlpiClient:
+    """Return a test client with no real HTTP plumbing.
+
+    Any constructor keyword can be overridden while the rest of the shared
+    base configuration is reused.
+    """
+
+    config = dict(DEFAULT_CLIENT_CONFIG)
+    config.update(overrides)
+    return AsyncGlpiClient(**config)  # type: ignore[arg-type]
+
+
+class TransportRecorder:
+    """Capture the four transport calls and answer with fixed responses.
+
+    Installed over the client's request helpers so a mixin test can assert
+    the endpoint, verb and serialised body without any HTTP plumbing.
+    """
+
+    def __init__(
+        self,
+        *,
+        get_payload: Any = None,
+        get_status: int = 200,
+        get_content: bytes | None = None,
+        post_payload: Any = None,
+        post_status: int = 201,
+        patch_status: int = 204,
+        delete_status: int = 204,
+    ) -> None:
+        self.calls: list[dict[str, Any]] = []
+        self._get_payload = get_payload if get_payload is not None else []
+        self._get_status = get_status
+        self._get_content = get_content
+        self._post_payload = post_payload if post_payload is not None else {"id": 999}
+        self._post_status = post_status
+        self._patch_status = patch_status
+        self._delete_status = delete_status
+
+    def install(self, client: AsyncGlpiClient) -> None:
+        """Replace the four transport helpers with capturing stubs."""
+
+        async def _get(
+            endpoint: str,
+            params: dict[str, Any] | None = None,
+            skip_entity: bool = False,
+        ) -> FakeResponse:
+            self.calls.append(
+                {
+                    "method": "GET",
+                    "endpoint": endpoint,
+                    "params": params,
+                    "skip_entity": skip_entity,
+                }
+            )
+            return FakeResponse(
+                status_code=self._get_status,
+                payload=self._get_payload,
+                content=self._get_content,
+            )
+
+        async def _post(
+            endpoint: str,
+            json_body: dict[str, Any] | None = None,
+            skip_entity: bool = False,
+        ) -> FakeResponse:
+            self.calls.append(
+                {
+                    "method": "POST",
+                    "endpoint": endpoint,
+                    "json": json_body,
+                    "skip_entity": skip_entity,
+                }
+            )
+            return FakeResponse(
+                status_code=self._post_status, payload=self._post_payload
+            )
+
+        async def _patch(
+            endpoint: str, json_body: dict[str, Any] | None = None
+        ) -> FakeResponse:
+            self.calls.append(
+                {"method": "PATCH", "endpoint": endpoint, "json": json_body}
+            )
+            return FakeResponse(status_code=self._patch_status, payload={})
+
+        async def _delete(
+            endpoint: str,
+            json_body: dict[str, Any] | None = None,
+            skip_entity: bool = False,
+        ) -> FakeResponse:
+            self.calls.append(
+                {
+                    "method": "DELETE",
+                    "endpoint": endpoint,
+                    "json": json_body,
+                    "skip_entity": skip_entity,
+                }
+            )
+            return FakeResponse(status_code=self._delete_status, payload={})
+
+        client._get_request = _get  # type: ignore[method-assign, assignment]
+        client._post_request = _post  # type: ignore[method-assign, assignment]
+        client._update_request = _patch  # type: ignore[method-assign, assignment]
+        client._delete_request = _delete  # type: ignore[method-assign, assignment]
+
+
+class FailingTransportRecorder(TransportRecorder):
+    """Answer every verb with one fixed non-success status."""
+
+    def __init__(self, status: int) -> None:
+        super().__init__(
+            get_status=status,
+            get_payload={"err": "x"},
+            post_status=status,
+            patch_status=status,
+            delete_status=status,
+        )

glpi_python_client/{auth → _async/auth}/__init__.py

@@ -1,13 +1,13 @@
 """Public authentication exports for the GLPI client package.
 
 The authentication package owns the OAuth2 token manager used by the
-asynchronous ``GlpiClient`` and the legacy v1 session wrapper used solely by
+GLPI client and the legacy v1 session wrapper used solely by
 the management document upload mixin.
 """
 
 from __future__ import annotations
 
-from glpi_python_client.auth._v1_session import GLPIV1Session
-from glpi_python_client.auth.auth import GLPITokenManager
+from glpi_python_client._async.auth._v1_session import GLPIV1Session
+from glpi_python_client._async.auth.auth import GLPITokenManager
 
 __all__ = ["GLPITokenManager", "GLPIV1Session"]