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

glpi_python_client/clients/v2/common/client_config.py

@@ -0,0 +1,219 @@
+"""Configuration and resource setup for GLPI v2 clients.
+
+This module centralizes environment parsing, URL normalization, SSL warning
+behavior, and the construction of shared runtime resources used by both the
+sync and async high-level clients.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import requests
+import urllib3
+
+if TYPE_CHECKING:
+    from glpi_python_client.auth.auth import GLPITokenManager
+    from glpi_python_client.clients.api_v1_session import GLPIV1Session
+
+
+@dataclass(frozen=True)
+class ClientResources:
+    """Runtime resources shared by sync and async v2 clients.
+
+    The concrete client classes use this immutable bundle to keep setup logic
+    centralized while still owning the resource lifecycle themselves.
+    """
+
+    glpi_api_url: str
+    session: requests.Session
+    auth: GLPITokenManager
+    v1: GLPIV1Session | None
+
+
+def configure_ssl_warning_policy(*, verify_ssl: bool) -> None:
+    """Adjust insecure-request warning behavior for the configured SSL policy.
+
+    When certificate verification is disabled, urllib3 warnings are muted so
+    callers do not get repeated noise from every request made by the client.
+    """
+
+    if verify_ssl:
+        return
+    urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+
+def build_v2_client_resources(
+    *,
+    glpi_api_url: object,
+    client_name: str,
+    client_id: str | None,
+    client_secret: str | None,
+    username: str | None,
+    password: str | None,
+    verify_ssl: bool,
+    auth_token_refresh: int | None,
+    v1_base_url: str | None,
+    v1_user_token: str | None,
+    v1_app_token: str | None,
+) -> ClientResources:
+    """Build the shared resources required by a v2 client instance.
+
+    This includes the normalized API URL, the shared ``requests`` session, the
+    OAuth token manager, and the optional legacy v1 session used for document
+    uploads.
+    """
+
+    from glpi_python_client.auth.auth import GLPITokenManager
+    from glpi_python_client.clients.api_v1_session import GLPIV1Session
+
+    normalized_api_url = normalize_client_api_url(
+        glpi_api_url,
+        client_name=client_name,
+    )
+    validate_v1_document_config(
+        v1_base_url=v1_base_url,
+        v1_user_token=v1_user_token,
+    )
+    configure_ssl_warning_policy(verify_ssl=verify_ssl)
+
+    session = requests.Session()
+    session.verify = verify_ssl
+    try:
+        auth = GLPITokenManager(
+            token_url=f"{normalized_api_url}/token",
+            client_id=client_id,
+            client_secret=client_secret,
+            username=username,
+            password=password,
+            session=session,
+            auth_token_refresh=auth_token_refresh,
+        )
+    except Exception:
+        session.close()
+        raise
+
+    v1: GLPIV1Session | None = None
+    if v1_base_url and v1_user_token:
+        v1 = GLPIV1Session(
+            base_url=v1_base_url,
+            user_token=v1_user_token,
+            app_token=v1_app_token or "",
+            verify_ssl=verify_ssl,
+        )
+
+    return ClientResources(
+        glpi_api_url=normalized_api_url,
+        session=session,
+        auth=auth,
+        v1=v1,
+    )
+
+
+def parse_optional_env_int(value: object) -> int | None:
+    """Parse one optional integer from an environment-style value.
+
+    ``None`` is preserved, native integers are accepted as-is, and strings are
+    converted through ``int()`` so explicit overrides and environment values
+    follow the same normalization path.
+    """
+
+    if value is None:
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        return int(value)
+    raise TypeError("Integer environment values must be strings or integers")
+
+
+def parse_optional_env_bool(value: object, *, default: bool) -> bool:
+    """Parse one optional boolean from an environment-style value.
+
+    String values follow the conventional true and false spellings accepted by
+    the package configuration helpers, while ``None`` falls back to the caller
+    provided default.
+    """
+
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    if not isinstance(value, str):
+        raise TypeError("Boolean environment values must be strings or booleans")
+    if value.casefold() in {"1", "true", "yes", "on"}:
+        return True
+    if value.casefold() in {"0", "false", "no", "off"}:
+        return False
+    raise ValueError(f"Invalid boolean environment value: {value!r}")
+
+
+def build_client_env_config(
+    *,
+    prefix: str,
+    env: Mapping[str, str],
+    overrides: Mapping[str, object],
+) -> dict[str, object]:
+    """Build common GLPI client config values from environment variables.
+
+    The returned mapping matches the constructor keyword arguments accepted by
+    both public client classes, making it suitable for direct unpacking.
+    """
+
+    config: dict[str, object] = {
+        "glpi_api_url": env.get(f"{prefix}API_URL"),
+        "client_id": env.get(f"{prefix}CLIENT_ID"),
+        "client_secret": env.get(f"{prefix}CLIENT_SECRET"),
+        "username": env.get(f"{prefix}USERNAME"),
+        "password": env.get(f"{prefix}PASSWORD"),
+        "glpi_entity": parse_optional_env_int(env.get(f"{prefix}ENTITY")),
+        "glpi_profile": parse_optional_env_int(env.get(f"{prefix}PROFILE")),
+        "entity_recursive": parse_optional_env_bool(
+            env.get(f"{prefix}ENTITY_RECURSIVE"),
+            default=False,
+        ),
+        "language": env.get(f"{prefix}LANGUAGE") or "en_GB",
+        "verify_ssl": parse_optional_env_bool(
+            env.get(f"{prefix}VERIFY_SSL"),
+            default=True,
+        ),
+        "auth_token_refresh": parse_optional_env_int(
+            env.get(f"{prefix}AUTH_TOKEN_REFRESH")
+        ),
+        "v1_base_url": env.get(f"{prefix}V1_BASE_URL"),
+        "v1_user_token": env.get(f"{prefix}V1_USER_TOKEN"),
+        "v1_app_token": env.get(f"{prefix}V1_APP_TOKEN"),
+    }
+    config.update(overrides)
+    return config
+
+
+def normalize_client_api_url(glpi_api_url: object, *, client_name: str) -> str:
+    """Validate and normalize the configured GLPI API base URL.
+
+    The helper rejects missing or non-string values early and strips a trailing
+    slash so endpoint assembly remains consistent across the client codebase.
+    """
+
+    if not isinstance(glpi_api_url, str) or not glpi_api_url:
+        raise ValueError(f"{client_name} requires glpi_api_url")
+    return glpi_api_url.rstrip("/")
+
+
+def validate_v1_document_config(
+    *,
+    v1_base_url: str | None,
+    v1_user_token: str | None,
+) -> None:
+    """Validate the paired legacy v1 document configuration values.
+
+    Document uploads require both the legacy base URL and the user token. This
+    helper rejects partial configuration before a client is constructed.
+    """
+
+    if bool(v1_base_url) != bool(v1_user_token):
+        raise ValueError(
+            "GLPI v1 document support requires both v1_base_url and v1_user_token."
+        )

glpi_python_client/clients/v2/common/constants.py

@@ -0,0 +1,45 @@
+"""GLPI v2 endpoint names and shared type aliases.
+
+This module keeps string constants and lightweight aliases in one place so the
+client layers can share endpoint paths and request parameter types without
+repeating literals.
+"""
+
+from __future__ import annotations
+
+from typing import TypeAlias
+
+GlpiId: TypeAlias = str | int
+RequestParamValue: TypeAlias = str | int | float | bytes | None
+
+TICKET_ENDPOINT = "Assistance/Ticket"
+FOLLOWUP_SUFFIX = "Timeline/Followup"
+TASK_SUFFIX = "Timeline/Task"
+SOLUTION_SUFFIX = "Timeline/Solution"
+DOCUMENT_SUFFIX = "Timeline/Document"
+TEAM_MEMBER_SUFFIX = "TeamMember"
+USER_ENDPOINT = "Administration/User"
+LOCATION_ENDPOINT = "Dropdowns/Location"
+
+LIST_TICKET_CORE_FIELDS = [
+    "id",
+    "name",
+    "content",
+    "is_deleted",
+    "status",
+    "urgency",
+    "impact",
+    "priority",
+    "type",
+    "external_id",
+    "date_creation",
+    "date_mod",
+    "date_close",
+    "category",
+    "entity",
+    "location",
+    "request_type",
+    "team",
+    "user_recipient",
+    "user_editor",
+]

glpi_python_client/clients/v2/common/errors.py

@@ -0,0 +1,23 @@
+"""Error formatting helpers for GLPI v2 client operations.
+
+These helpers normalize exception messages so retry wrappers and direct remote
+call failures surface a readable error string to higher-level client methods.
+"""
+
+from __future__ import annotations
+
+from tenacity import RetryError
+
+
+def remote_error_message(exc: Exception) -> str:
+    """Return a readable message for one remote-call exception.
+
+    ``tenacity.RetryError`` instances are unwrapped to expose the underlying
+    failure message instead of the retry wrapper representation.
+    """
+
+    if isinstance(exc, RetryError):
+        inner_exception = exc.last_attempt.exception()
+        if isinstance(inner_exception, Exception):
+            return str(inner_exception)
+    return str(exc)

glpi_python_client/clients/v2/common/filters.py

@@ -0,0 +1,30 @@
+"""RSQL filter helpers for GLPI v2 search endpoints.
+
+The high-level client uses these helpers to build safe text-search filters for
+GLPI endpoints that accept RSQL-like query expressions.
+"""
+
+from __future__ import annotations
+
+
+def rsql_contains_filter(field: str, value: str) -> str | None:
+    """Build a contains-style RSQL filter for one text field.
+
+    Blank search input returns ``None`` so callers can skip adding the filter,
+    while non-empty input is escaped before being wrapped in wildcard syntax.
+    """
+
+    text = value.strip()
+    if not text:
+        return None
+    return f'{field}=like="*{escape_rsql_like_value(text)}*"'
+
+
+def escape_rsql_like_value(value: str) -> str:
+    """Escape user text embedded in a quoted RSQL ``like`` value.
+
+    The helper protects backslashes, quotes, and wildcard characters so caller
+    input is treated as text instead of modifying the filter expression.
+    """
+
+    return value.replace("\\", "\\\\").replace('"', '\\"').replace("*", "\\*")

glpi_python_client/clients/v2/common/payloads.py

@@ -0,0 +1,57 @@
+"""Request payload builders for GLPI v2 client operations.
+
+These helpers keep small but repeated mutation payload rules out of the public
+client methods so sync and async implementations can share them directly.
+"""
+
+from __future__ import annotations
+
+from .constants import GlpiId
+
+
+def build_team_member_payload(
+    *,
+    member_type: str,
+    member_id: int,
+    role: str,
+) -> dict[str, object]:
+    """Build the API payload used to add or remove one team member.
+
+    The returned mapping matches the shape expected by the GLPI team-member
+    endpoint for both creation and removal workflows.
+    """
+
+    return {
+        "type": member_type,
+        "id": member_id,
+        "role": role,
+    }
+
+
+def prepare_document_upload(
+    *,
+    ticket_id: GlpiId | None,
+    filename: str | None,
+    content: bytes | None,
+    mime_type: str | None,
+) -> tuple[int, str, bytes, str, str]:
+    """Validate a document upload request and return normalized upload data.
+
+    This helper enforces the package-level upload prerequisites and converts the
+    mixed model fields into the concrete values required by the legacy v1 upload
+    API.
+    """
+
+    if ticket_id is None:
+        raise ValueError("GLPI document upload requires a ticket_id")
+    if filename is None:
+        raise ValueError("GLPI document upload requires a filename")
+    if content is None:
+        raise ValueError("GLPI document upload requires file content")
+
+    parsed_ticket_id = int(ticket_id)
+    document_name = f"Document ticket {parsed_ticket_id}"
+    effective_mime_type = (
+        mime_type if mime_type is not None else "application/octet-stream"
+    )
+    return parsed_ticket_id, filename, content, effective_mime_type, document_name

glpi_python_client/clients/v2/common/request_http.py

@@ -0,0 +1,195 @@
+"""HTTP request and response helpers for GLPI v2 clients.
+
+This module contains the small transport-agnostic helpers used by both sync
+and async request layers to normalize parameters, assemble headers, and handle
+common response validation rules.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+
+import requests
+
+from glpi_python_client.content.records.core.scalars import _optional_text
+
+from .constants import RequestParamValue
+
+
+def request_params(
+    params: dict[str, object] | None,
+) -> dict[str, RequestParamValue] | None:
+    """Normalize query parameters into ``requests``-compatible values.
+
+    Each value is converted through ``request_param_value`` so callers can pass
+    richer Python objects without repeating serialization logic.
+    """
+
+    if params is None:
+        return None
+    return {key: request_param_value(value) for key, value in params.items()}
+
+
+def request_param_value(value: object) -> RequestParamValue:
+    """Normalize one query parameter value for ``requests``.
+
+    Native scalar values are preserved and any other object is stringified so
+    higher-level client code can pass enums and IDs without special handling.
+    """
+
+    if value is None or isinstance(value, str | int | float | bytes):
+        return value
+    return str(value)
+
+
+def require_access_token(access_token: str | None) -> str:
+    """Return a usable access token or raise when it is missing.
+
+    Transport helpers call this right before request dispatch so missing token
+    state turns into a clear local error instead of a malformed API call.
+    """
+
+    if not access_token:
+        raise ValueError("Failed to acquire access token for API request")
+    return access_token
+
+
+def build_request_headers(
+    *,
+    access_token: str | None,
+    language: str,
+    glpi_entity: int | None,
+    glpi_profile: int | None,
+    entity_recursive: bool,
+    include_content_type: bool = False,
+    skip_entity: bool = False,
+) -> dict[str, str]:
+    """Build GLPI request headers from one client state snapshot.
+
+    The header set includes authorization and language settings, with optional
+    entity, profile, recursion, and content-type headers derived from the
+    current client configuration.
+    """
+
+    headers = {
+        "Authorization": f"Bearer {access_token}",
+        "Accept": "application/json",
+        "Accept-Language": language,
+    }
+    if include_content_type:
+        headers["Content-Type"] = "application/json"
+    if not skip_entity:
+        if glpi_entity is not None:
+            headers["GLPI-Entity"] = str(glpi_entity)
+        if glpi_profile is not None:
+            headers["GLPI-Profile"] = str(glpi_profile)
+        if entity_recursive:
+            headers["GLPI-Entity-Recursive"] = "true"
+    return headers
+
+
+def build_request_url(glpi_api_url: str, endpoint: str) -> str:
+    """Return the absolute URL for one GLPI endpoint path.
+
+    Callers provide the normalized API base URL and the endpoint suffix that is
+    already specific to the requested resource.
+    """
+
+    return f"{glpi_api_url}/{endpoint}"
+
+
+def finalize_request_response(
+    response: requests.Response,
+    *,
+    method: str,
+    url: str,
+    success_statuses: tuple[int, ...],
+    logger: logging.Logger,
+) -> requests.Response:
+    """Validate one GLPI transport response and preserve warning behavior.
+
+    Server errors are raised immediately while non-success statuses outside the
+    accepted set are logged for higher-level mutation and lookup helpers to
+    interpret consistently.
+    """
+
+    method_name = method.upper()
+    if 500 <= response.status_code < 600:
+        message = (
+            f"GLPI {method_name} {url} failed with "
+            f"{response.status_code} {response.reason}"
+        )
+        logger.warning(message)
+        raise requests.HTTPError(message)
+    if response.status_code not in success_statuses:
+        logger.warning(
+            "GLPI %s %s returned %s: %s",
+            method_name,
+            url,
+            response.status_code,
+            response.text[:200],
+        )
+    return response
+
+
+def ensure_response_status(
+    response: requests.Response,
+    *,
+    success_statuses: tuple[int, ...],
+    failure_message: str,
+) -> None:
+    """Raise a consistent ``ValueError`` for an unexpected response status.
+
+    Higher-level client methods use this helper to keep their mutation and fetch
+    failure messages aligned across sync and async call sites.
+    """
+
+    if response.status_code not in success_statuses:
+        raise ValueError(
+            f"{failure_message}: {response.status_code} {response.text[:200]}"
+        )
+
+
+def response_json_mapping(response: requests.Response) -> Mapping[str, object]:
+    """Return the JSON response payload as a mapping when possible.
+
+    Empty response bodies become an empty mapping and non-mapping JSON payloads
+    are intentionally ignored so callers can safely probe expected keys.
+    """
+
+    result = response.json() if response.content else {}
+    return result if isinstance(result, Mapping) else {}
+
+
+def require_response_text(
+    response: requests.Response,
+    *,
+    keys: tuple[str, ...],
+    missing_message: str,
+) -> str:
+    """Return the first non-empty text field from a JSON response mapping.
+
+    This is primarily used for create responses that may expose the created ID
+    under one of several field names.
+    """
+
+    result = response_json_mapping(response)
+    for key in keys:
+        value = _optional_text(result.get(key))
+        if value is not None:
+            return value
+    raise ValueError(missing_message)
+
+
+def require_non_empty_text(value: object, *, error_message: str) -> str:
+    """Return stripped text or raise when the value is empty.
+
+    Validation stays centralized here so operation-level preconditions use the
+    same message and whitespace-trimming behavior throughout the package.
+    """
+
+    text = _optional_text(value)
+    if text is None:
+        raise ValueError(error_message)
+    return text

glpi_python_client/clients/v2/common/response_payloads.py

@@ -0,0 +1,76 @@
+"""Response payload extraction helpers for GLPI v2 clients.
+
+These functions turn raw JSON and timeline payloads into predictable lists of
+mapping items before higher-level parsers convert them into typed models.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+import requests
+
+from glpi_python_client.content.records.core.normalization import (
+    _normalize_timeline_records,
+)
+
+RecordT = TypeVar("RecordT")
+
+
+def list_payload_items(payload: object) -> list[dict[str, Any]]:
+    """Return dictionary items from one plain JSON list payload.
+
+    Non-list payloads are treated as empty so callers can safely use this on
+    API responses that may vary or fail validation upstream.
+    """
+
+    if not isinstance(payload, list):
+        return []
+    return [item for item in payload if isinstance(item, dict)]
+
+
+def timeline_payload_items(payload: object) -> list[dict[str, Any]]:
+    """Return dictionary items from one GLPI timeline payload.
+
+    Timeline payloads go through the shared normalization step first because
+    GLPI can nest timeline items in multiple container shapes.
+    """
+
+    return [
+        item for item in _normalize_timeline_records(payload) if isinstance(item, dict)
+    ]
+
+
+def list_payload_records(
+    payload: object,
+    *,
+    record_factory: Callable[[dict[str, Any]], RecordT | None],
+) -> list[RecordT]:
+    """Build typed records from one plain JSON list payload.
+
+    The provided factory may return ``None`` to skip individual raw items while
+    preserving the rest of the batch.
+    """
+
+    records: list[RecordT] = []
+    for item in list_payload_items(payload):
+        record = record_factory(item)
+        if record is not None:
+            records.append(record)
+    return records
+
+
+def timeline_records_from_response(
+    response: requests.Response,
+    *,
+    record_factory: Callable[[dict[str, Any]], RecordT],
+) -> list[RecordT]:
+    """Build typed records from one successful GLPI timeline response.
+
+    Unlike plain list payload handling, timeline parsing assumes each normalized
+    item should produce a record and lets the record factory raise on invalid
+    data.
+    """
+
+    return [record_factory(item) for item in timeline_payload_items(response.json())]