glpi-python-client 0.1.0__py3-none-any.whl

glpi_python_client/clients/v2/sync/transport.py

@@ -0,0 +1,246 @@
+"""Synchronous GLPI v2 transport methods.
+
+This module owns the authenticated ``requests`` call helpers used by the sync
+mixins to communicate with the GLPI high-level API.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, cast
+
+import requests
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_fixed
+
+from glpi_python_client.clients.v2.common.request_http import (
+    build_request_headers,
+    build_request_url,
+    finalize_request_response,
+    request_params,
+    require_access_token,
+)
+
+if TYPE_CHECKING:
+    from glpi_python_client.auth.auth import GLPITokenManager
+    from glpi_python_client.clients.api_v1_session import GLPIV1Session
+
+logger = logging.getLogger(__name__)
+
+
+class SyncTransportMixin:
+    """Synchronous GLPI API transport helpers.
+
+    The transport mixin keeps token handling, header construction, retries, and
+    request dispatch out of the endpoint-specific synchronous mixins.
+    """
+
+    _auth: GLPITokenManager
+    _auth_lock: Any
+    _closed: bool = False
+    _session: requests.Session
+    _v1: GLPIV1Session | None
+    entity_recursive: bool
+    glpi_api_url: str
+    glpi_entity: int | None
+    glpi_profile: int | None
+    language: str
+
+    def _ensure_open(self) -> None:
+        """Raise when the client has already been closed.
+
+        All synchronous transport helpers call this guard before touching the
+        shared HTTP session.
+        """
+
+        if self._closed:
+            raise RuntimeError("GLPI client is closed")
+
+    def _ensure_token(self) -> None:
+        """Ensure that a valid GLPI access token is available.
+
+        Token refresh is protected by the client lock so concurrent sync calls
+        do not race while updating shared authentication state.
+        """
+
+        self._ensure_open()
+        with self._auth_lock:
+            self._auth.ensure_token()
+
+    def _get_headers(
+        self,
+        *,
+        include_content_type: bool = False,
+        skip_entity: bool = False,
+    ) -> dict[str, str]:
+        """Build GLPI request headers for the current client state.
+
+        This convenience wrapper forwards the current transport state to the
+        shared header builder used across sync and async implementations.
+        """
+
+        return build_request_headers(
+            access_token=self._auth.access_token,
+            language=self.language,
+            glpi_entity=self.glpi_entity,
+            glpi_profile=self.glpi_profile,
+            entity_recursive=self.entity_recursive,
+            include_content_type=include_content_type,
+            skip_entity=skip_entity,
+        )
+
+    def _send_request(
+        self,
+        method: str,
+        url: str,
+        **kwargs: object,
+    ) -> requests.Response:
+        request_method = getattr(self._session, method)
+        return cast(requests.Response, request_method(url, **kwargs))
+
+    def _execute_request(
+        self,
+        *,
+        method: str,
+        endpoint: str,
+        success_statuses: tuple[int, ...],
+        params: dict[str, object] | None = None,
+        json_body: dict[str, object] | None = None,
+        skip_entity: bool = False,
+        include_content_type: bool = False,
+    ) -> requests.Response:
+        """Execute one authenticated GLPI request.
+
+        The helper normalizes the endpoint URL, headers, timeout, and payload
+        placement before handing the response to the shared validation logic.
+        """
+
+        self._ensure_token()
+        access_token = require_access_token(self._auth.access_token)
+        url = build_request_url(self.glpi_api_url, endpoint)
+
+        request_kwargs: dict[str, object] = {
+            "headers": build_request_headers(
+                access_token=access_token,
+                language=self.language,
+                glpi_entity=self.glpi_entity,
+                glpi_profile=self.glpi_profile,
+                entity_recursive=self.entity_recursive,
+                include_content_type=include_content_type,
+                skip_entity=skip_entity,
+            ),
+            "timeout": 30,
+        }
+        if method == "get":
+            request_kwargs["params"] = request_params(params)
+        else:
+            request_kwargs["json"] = json_body
+
+        response = self._send_request(method, url, **request_kwargs)
+        return finalize_request_response(
+            response,
+            method=method,
+            url=url,
+            success_statuses=success_statuses,
+            logger=logger,
+        )
+
+    @retry(
+        retry=retry_if_exception_type(requests.RequestException),
+        stop=stop_after_attempt(3),
+        wait=wait_fixed(3),
+    )
+    def _get_request(
+        self,
+        endpoint: str,
+        params: dict[str, object] | None = None,
+        skip_entity: bool = False,
+    ) -> requests.Response:
+        """Execute one authenticated GLPI ``GET`` request.
+
+        Network-level request exceptions are retried according to the transport
+        retry policy before the response is returned to the caller.
+        """
+
+        return self._execute_request(
+            method="get",
+            endpoint=endpoint,
+            success_statuses=(200, 206),
+            params=params,
+            skip_entity=skip_entity,
+        )
+
+    @retry(
+        retry=retry_if_exception_type(requests.RequestException),
+        stop=stop_after_attempt(3),
+        wait=wait_fixed(3),
+    )
+    def _post_request(
+        self,
+        endpoint: str,
+        json_body: dict[str, object] | None = None,
+        skip_entity: bool = False,
+    ) -> requests.Response:
+        """Execute one authenticated GLPI ``POST`` request.
+
+        JSON request bodies automatically include the content-type header needed
+        by the GLPI API.
+        """
+
+        return self._execute_request(
+            method="post",
+            endpoint=endpoint,
+            success_statuses=(200, 201),
+            json_body=json_body,
+            skip_entity=skip_entity,
+            include_content_type=True,
+        )
+
+    @retry(
+        retry=retry_if_exception_type(requests.RequestException),
+        stop=stop_after_attempt(3),
+        wait=wait_fixed(3),
+    )
+    def _update_request(
+        self,
+        endpoint: str,
+        json_body: dict[str, object] | None = None,
+    ) -> requests.Response:
+        """Execute one authenticated GLPI ``PATCH`` request.
+
+        The helper uses the same authenticated execution path as the other HTTP
+        verbs while targeting the success codes expected from update calls.
+        """
+
+        return self._execute_request(
+            method="patch",
+            endpoint=endpoint,
+            success_statuses=(200, 204),
+            json_body=json_body,
+            include_content_type=True,
+        )
+
+    @retry(
+        retry=retry_if_exception_type(requests.RequestException),
+        stop=stop_after_attempt(3),
+        wait=wait_fixed(3),
+    )
+    def _delete_request(
+        self,
+        endpoint: str,
+        json_body: dict[str, object] | None = None,
+        skip_entity: bool = False,
+    ) -> requests.Response:
+        """Execute one authenticated GLPI ``DELETE`` request.
+
+        Some delete endpoints accept a JSON body, so the content-type header is
+        enabled automatically when a body is supplied.
+        """
+
+        return self._execute_request(
+            method="delete",
+            endpoint=endpoint,
+            success_statuses=(200, 204),
+            json_body=json_body,
+            skip_entity=skip_entity,
+            include_content_type=json_body is not None,
+        )

glpi_python_client/content/__init__.py

@@ -0,0 +1,11 @@
+"""Public content-layer exports for the GLPI client package.
+
+The content package contains helpers that translate between GLPI transport
+payloads and the package's canonical Markdown and typed-record representations.
+"""
+
+from __future__ import annotations
+
+from glpi_python_client.content.conversion import GlpiContentConverter
+
+__all__ = ["GlpiContentConverter"]

glpi_python_client/content/conversion.py

@@ -0,0 +1,58 @@
+"""Content conversion helpers for GLPI payloads.
+
+This module translates between GLPI's HTML transport format and the package's
+canonical Markdown representation used by the rich content models.
+"""
+
+from __future__ import annotations
+
+from markdown import markdown as markdown_to_html
+from markdownify import markdownify as html_to_markdown
+
+
+class GlpiContentConverter:
+    """Convert content between GLPI HTML payloads and canonical Markdown.
+
+    The converter keeps the translation rules in one place so ticket, followup,
+    task, and solution parsing all share the same content normalization.
+    """
+
+    @staticmethod
+    def from_transport(value: object) -> str:
+        """Convert one GLPI transport value into canonical Markdown.
+
+        Empty input stays empty, plain text is preserved, and HTML content is
+        normalized through ``markdownify`` with the package's preferred options.
+        """
+
+        content = str(value or "")
+        if not content.strip():
+            return ""
+        if "<" not in content or ">" not in content:
+            return content.strip()
+
+        markdown = html_to_markdown(
+            content,
+            heading_style="ATX",
+            bullets="-",
+            strip=["script", "style"],
+        )
+        return str(markdown).strip()
+
+    @staticmethod
+    def to_transport(value: object) -> str:
+        """Convert one canonical Markdown value into GLPI HTML.
+
+        Empty Markdown stays empty, while non-empty content is rendered through
+        the configured Markdown extensions used by the package.
+        """
+
+        markdown = str(value or "")
+        if not markdown.strip():
+            return ""
+        html = markdown_to_html(
+            markdown,
+            extensions=["nl2br", "sane_lists"],
+            output_format="html5",
+        )
+        return str(html).strip()

glpi_python_client/content/records/__init__.py

@@ -0,0 +1,84 @@
+"""Compatibility exports for GLPI record parsing helpers.
+
+The real parsing implementation is split between ``core`` shared helpers and
+``parsers`` for model-specific payload conversion. This package preserves the
+older aggregate import path for internal callers.
+"""
+
+from __future__ import annotations
+
+from glpi_python_client.content.records.core.document_links import (
+    _glpi_document_id_from_url,
+    _glpi_followup_attachment_document_ids,
+    _strip_glpi_document_references,
+)
+from glpi_python_client.content.records.core.normalization import (
+    _normalize_ticket_record,
+    _normalize_timeline_records,
+    _unwrap_timeline_item,
+)
+from glpi_python_client.content.records.core.references import (
+    _glpi_id_reference,
+    _glpi_id_value,
+    _glpi_reference,
+    _glpi_text_reference,
+    _glpi_ticket_user_payload,
+)
+from glpi_python_client.content.records.core.scalars import (
+    _coerce_bool,
+    _first_int,
+    _optional_int,
+    _optional_text,
+    _parse_glpi_datetime,
+)
+from glpi_python_client.content.records.parsers.directory import (
+    _glpi_location_record,
+    _glpi_user_record,
+)
+from glpi_python_client.content.records.parsers.documents import _glpi_document_record
+from glpi_python_client.content.records.parsers.team import (
+    _glpi_team_member_record,
+    _resolve_glpi_member_type,
+)
+from glpi_python_client.content.records.parsers.tickets import (
+    _filter_visible_ticket_batch,
+    _glpi_ticket_record,
+    _is_deleted_ticket,
+)
+from glpi_python_client.content.records.parsers.timeline import (
+    _glpi_author_id,
+    _glpi_followup_record,
+    _glpi_solution_record,
+    _glpi_task_record,
+)
+
+__all__ = [
+    "_coerce_bool",
+    "_filter_visible_ticket_batch",
+    "_first_int",
+    "_glpi_author_id",
+    "_glpi_document_id_from_url",
+    "_glpi_document_record",
+    "_glpi_followup_attachment_document_ids",
+    "_glpi_followup_record",
+    "_glpi_id_reference",
+    "_glpi_id_value",
+    "_glpi_location_record",
+    "_glpi_reference",
+    "_glpi_solution_record",
+    "_glpi_task_record",
+    "_glpi_team_member_record",
+    "_glpi_text_reference",
+    "_glpi_ticket_record",
+    "_glpi_ticket_user_payload",
+    "_glpi_user_record",
+    "_is_deleted_ticket",
+    "_normalize_ticket_record",
+    "_normalize_timeline_records",
+    "_optional_int",
+    "_optional_text",
+    "_parse_glpi_datetime",
+    "_resolve_glpi_member_type",
+    "_strip_glpi_document_references",
+    "_unwrap_timeline_item",
+]

glpi_python_client/content/records/core/__init__.py

@@ -0,0 +1,6 @@
+"""Shared low-level helpers for GLPI record parsing.
+
+Modules in this package handle reusable normalization, scalar coercion,
+reference extraction, and attachment-link parsing that multiple record parsers
+depend on.
+"""

glpi_python_client/content/records/core/document_links.py

@@ -0,0 +1,100 @@
+"""Helpers for parsing GLPI document references in timeline HTML.
+
+GLPI followups and solutions can embed attachments as links or images pointing
+to ``document.send.php`` with a ``docid`` query parameter. These helpers keep
+that transport-specific HTML parsing isolated from the model parsers.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import parse_qs, urlsplit
+
+from bs4 import BeautifulSoup
+
+
+def _glpi_followup_attachment_document_ids(raw_content: object) -> tuple[str, ...]:
+    """Return attachment document IDs referenced by followup HTML.
+
+    GLPI timeline content may contain one or more ``a`` or ``img`` tags that
+    point at ``document.send.php``. The parser scans both ``href`` and ``src``
+    attributes, preserves the order in which document IDs appear, and removes
+    duplicates so callers can safely request metadata once per attachment.
+    """
+
+    content = str(raw_content or "")
+    if "document.send.php" not in content.casefold():
+        return ()
+
+    document_ids: list[str] = []
+    seen_document_ids: set[str] = set()
+    soup = BeautifulSoup(content, features="lxml")
+    root = soup.body or soup
+
+    for tag in root.find_all(["a", "img"]):
+        if getattr(tag, "attrs", None) is None:
+            continue
+        for attribute_name in ("href", "src"):
+            document_id = _glpi_document_id_from_url(tag.get(attribute_name))
+            if document_id is None or document_id in seen_document_ids:
+                continue
+            seen_document_ids.add(document_id)
+            document_ids.append(document_id)
+
+    return tuple(document_ids)
+
+
+def _strip_glpi_document_references(raw_content: object) -> str:
+    """Return followup HTML with GLPI attachment references removed.
+
+    Attachment images are removed completely because their source points at the
+    GLPI document endpoint rather than meaningful inline content. Attachment
+    links are replaced by their visible text when possible so the human-written
+    part of the followup remains readable after document references are split
+    into structured attachment IDs.
+    """
+
+    content = str(raw_content or "")
+    if "document.send.php" not in content.casefold():
+        return content
+
+    soup = BeautifulSoup(content, features="lxml")
+    root = soup.body or soup
+
+    for tag in list(root.find_all(["a", "img"])):
+        if tag.name is None or getattr(tag, "attrs", None) is None:
+            continue
+        target = tag.get("src") if tag.name == "img" else tag.get("href")
+        if _glpi_document_id_from_url(target) is None:
+            continue
+        if tag.name == "img" or tag.find("img") is not None:
+            tag.decompose()
+            continue
+        replacement = tag.get_text(" ", strip=True)
+        if replacement:
+            tag.replace_with(replacement)
+        else:
+            tag.decompose()
+
+    normalized_root = soup.body or soup
+    return "".join(str(child) for child in normalized_root.contents)
+
+
+def _glpi_document_id_from_url(url: object) -> str | None:
+    """Extract one GLPI document ID from a document download URL.
+
+    Only GLPI ``document.send.php`` URLs are accepted. Missing URLs, non-string
+    values, unrelated paths, missing ``docid`` parameters, and blank document IDs
+    all return ``None`` so callers can probe arbitrary HTML attributes without
+    handling parsing exceptions.
+    """
+
+    if not isinstance(url, str) or not url.strip():
+        return None
+    parsed = urlsplit(url)
+    if not parsed.path.casefold().endswith("document.send.php"):
+        return None
+    document_ids = parse_qs(parsed.query).get("docid")
+    if not document_ids:
+        return None
+    document_id = str(document_ids[0]).strip()
+    return document_id or None

glpi_python_client/content/records/core/normalization.py

@@ -0,0 +1,53 @@
+"""Raw GLPI payload normalization helpers.
+
+These helpers smooth over the small shape differences between GLPI ticket and
+timeline payloads before the model-specific parsers consume them.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _normalize_ticket_record(data: object) -> dict[str, Any] | object:
+    """Return a shallow mapping copy for one raw GLPI ticket payload.
+
+    Ticket payloads are usually already flat mappings, so normalization here is
+    limited to copying dictionaries before downstream mutation.
+    """
+
+    if not isinstance(data, dict):
+        return data
+    return dict(data)
+
+
+def _normalize_timeline_records(data: object) -> list[dict[str, Any]]:
+    """Normalize one GLPI timeline payload to a list of item mappings.
+
+    GLPI timeline responses may contain wrapper objects around the actual item
+    payload. This helper unwraps those entries and keeps only mapping items.
+    """
+
+    if not isinstance(data, list):
+        return []
+
+    records: list[dict[str, Any]] = []
+    for entry in data:
+        if not isinstance(entry, dict):
+            continue
+        item = _unwrap_timeline_item(entry)
+        if isinstance(item, dict):
+            records.append(dict(item))
+    return records
+
+
+def _unwrap_timeline_item(entry: dict[str, Any]) -> dict[str, Any]:
+    """Return the nested timeline item mapping when GLPI wraps it in ``item``.
+
+    Some timeline endpoints return an outer record with the real payload stored
+    under the ``item`` key; others already return the payload directly.
+    """
+
+    if "item" in entry and isinstance(entry["item"], dict):
+        return entry["item"]
+    return entry

glpi_python_client/content/records/core/references.py

@@ -0,0 +1,98 @@
+"""GLPI nested reference parsing helpers.
+
+These helpers normalize the mixed scalar-or-mapping reference fields that GLPI
+uses for related objects such as users, entities, and categories.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from glpi_python_client.models import GlpiUser
+
+from .scalars import _optional_int, _optional_text
+
+
+def _glpi_id_value(value: Any) -> Any:
+    """Return the ``id`` field from one GLPI mapping payload.
+
+    Non-mapping values return ``None`` so callers can safely probe optional
+    nested references without type checks at every call site.
+    """
+
+    if isinstance(value, dict):
+        return value.get("id")
+    return None
+
+
+def _glpi_reference(value: Any) -> dict[str, object] | int | str | None:
+    """Normalize one GLPI reference field using the API field shape.
+
+    Mapping values are reduced to the supported reference keys, while scalar
+    values are preserved as integers when possible and text otherwise.
+    """
+
+    if isinstance(value, dict):
+        reference = _reference_mapping(value)
+        return reference or None
+    integer_value = _optional_int(value)
+    if integer_value is not None:
+        return integer_value
+    return _optional_text(value)
+
+
+def _glpi_id_reference(value: Any) -> dict[str, object] | int | None:
+    """Normalize one GLPI reference whose scalar form must be an ID.
+
+    This is used for fields that should never surface free text when GLPI sends
+    a scalar reference representation.
+    """
+
+    if isinstance(value, dict):
+        reference = _reference_mapping(value)
+        return reference or None
+    return _optional_int(value)
+
+
+def _glpi_text_reference(value: Any) -> dict[str, object] | str | None:
+    """Normalize one GLPI reference whose scalar form is textual.
+
+    Mapping payloads are preserved as reduced references, while scalar values
+    are coerced to stripped text.
+    """
+
+    if isinstance(value, dict):
+        reference = _reference_mapping(value)
+        return reference or None
+    return _optional_text(value)
+
+
+def _glpi_ticket_user_payload(value: Any) -> GlpiUser | None:
+    """Build a lightweight ``GlpiUser`` from one nested ticket field.
+
+    Ticket payloads often embed partial user records. This helper keeps only the
+    fields that are meaningful for the package's ticket models.
+    """
+
+    if not isinstance(value, dict):
+        return None
+    user_id = _optional_text(value.get("id"))
+    name = _optional_text(value.get("name"))
+    email = _optional_text(value.get("email"))
+    if user_id is None and name is None and email is None:
+        return None
+    return GlpiUser(user_id=user_id, name=name, email=email)
+
+
+def _reference_mapping(value: dict[str, Any]) -> dict[str, object]:
+    """Return the supported GLPI reference fields from one nested payload.
+
+    Only the small subset of keys used by the package's models is preserved so
+    reference payloads stay predictable.
+    """
+
+    return {
+        key: field_value
+        for key, field_value in value.items()
+        if key in {"id", "name", "completename"} and field_value is not None
+    }