Source code for pain001_lsp._faces

# SPDX-FileCopyrightText: 2026 Sebastien Rousseau <sebastian.rousseau@gmail.com>
# SPDX-License-Identifier: Apache-2.0 OR MIT
"""Faces commands: a pain.001 document projected into another standard.

``pain001.faces.list`` names each face, its target and the binding keys
it accepts; ``pain001.faces.project`` takes the document as XML text
(the editor sends the buffer) and returns the target payload with a
loss report of every source element not carried. Both delegate to
:mod:`pain001.faces` (pain001 >= 0.0.78) through
:func:`pain001.faces.project_face_text`, which never reads a path and
refuses entity declarations. With an older pain001 they answer with an
error payload, like the corpus commands.
"""

from __future__ import annotations

import importlib
from typing import Any

from pygls.lsp.server import LanguageServer

from pain001_lsp._commands import command_options

FACES_LIST_COMMAND = "pain001.faces.list"
FACES_PROJECT_COMMAND = "pain001.faces.project"
FACES_MISSING = (
    "faces need pain001 >= 0.0.78; the installed pain001 has no "
    "pain001.faces.project_face_text"
)


def _faces_api() -> Any | None:
    """Return :mod:`pain001.faces`, or ``None`` when the library predates it."""
    try:
        faces = importlib.import_module("pain001.faces")
    except ImportError:
        return None
    return faces if hasattr(faces, "project_face_text") else None


[docs] def faces_list() -> dict[str, Any]: """List the faces, their targets and the binding keys each accepts. Pure helper behind :data:`FACES_LIST_COMMAND`. Returns: ``{"count", "faces": [{"name", "description", "bindings"}, ...]}`` or ``{"error": ...}`` when the installed pain001 has no faces. """ faces = _faces_api() if faces is None: return {"error": FACES_MISSING} entries = faces.list_supported_faces() return {"count": len(entries), "faces": entries}
[docs] def faces_project(options: dict[str, Any] | None = None) -> dict[str, Any]: """Project a pain.001 document into a face, with its loss report. Pure helper behind :data:`FACES_PROJECT_COMMAND`. An editor sends the open buffer's text, so a payment file can be checked against the request body a UK Open Banking or Berlin Group API expects, and against what that body leaves out, without leaving the editor. Args: options: ``xml`` (the document text) and ``face`` (required), an optional ``version`` and optional ``bindings`` (an object of the keys :func:`faces_list` names for the face). Returns: ``{"face", "version", "payload", "loss_report"}`` or ``{"error": ...}`` when the arguments are incomplete, the face refuses the document or a binding, or the installed pain001 has no faces. """ faces = _faces_api() if faces is None: return {"error": FACES_MISSING} options = options or {} xml = options.get("xml") face = options.get("face") if not isinstance(xml, str) or not isinstance(face, str) or not face: return {"error": "xml and face are required strings"} try: result = faces.project_face_text( xml, face, version=options.get("version") or None, bindings=options.get("bindings"), ) except faces.FaceError as exc: return {"error": str(exc)} projection: dict[str, Any] = result.to_dict() return projection
[docs] def faces_list_command(ls: LanguageServer, *args: Any) -> dict[str, Any]: """``workspace/executeCommand`` glue for :func:`faces_list`. Args: ls: The language server (unused; pygls passes it first). *args: The command arguments (none are read). Returns: The :func:`faces_list` payload. """ return faces_list()
[docs] def faces_project_command(ls: LanguageServer, *args: Any) -> dict[str, Any]: """``workspace/executeCommand`` glue for :func:`faces_project`. Args: ls: The language server (unused; pygls passes it first). *args: The command arguments; the first is the request dict. Returns: The :func:`faces_project` payload. """ return faces_project(command_options(args))