Source code for pain001_lsp._corpus
# SPDX-FileCopyrightText: 2026 Sebastien Rousseau <sebastian.rousseau@gmail.com>
# SPDX-License-Identifier: Apache-2.0 OR MIT
"""Example corpus commands (pain001 >= 0.0.67).
``pain001.corpus.list`` lists the validated example files pain001 ships
and ``pain001.corpus.get`` returns one market file's XML with its
provenance sidecar. With an older pain001 both answer with an error
payload instead of failing at import time.
"""
from __future__ import annotations
import importlib
from typing import Any
from pygls.lsp.server import LanguageServer
from pain001_lsp._commands import command_options
CORPUS_LIST_COMMAND = "pain001.corpus.list"
CORPUS_GET_COMMAND = "pain001.corpus.get"
_CORPUS_MISSING = (
"the example corpus needs pain001 >= 0.0.67; the installed pain001 "
"has no pain001.corpus module"
)
def _corpus_api() -> Any | None:
"""Return :mod:`pain001.corpus`, or ``None`` when the library predates it.
The corpus shipped in pain001 0.0.67; older releases remain valid
peers of this server, so the corpus commands answer with an error
payload instead of failing at import time.
"""
try:
return importlib.import_module("pain001.corpus")
except ImportError:
return None
[docs]
def corpus_list(options: dict[str, Any] | None = None) -> dict[str, Any]:
"""List the validated example files pain001 ships.
Pure helper behind :data:`CORPUS_LIST_COMMAND`. Market files are
realistic payments per country and rail, each with a scenario id
and an optional bank-overlay ``variant``; coverage files exercise
every element and choice branch of one message type.
Args:
options: Optional filters: ``kind`` (``market`` or ``coverage``),
``country`` (two letters, any case) and ``version`` (a
message type such as ``pain.001.001.09``).
Returns:
``{"count", "files": [...]}`` or ``{"error": ...}`` when the
installed pain001 has no corpus.
"""
corpus = _corpus_api()
if corpus is None:
return {"error": _CORPUS_MISSING}
options = options or {}
country = options.get("country")
wanted_country = str(country).upper() if country else None
version = options.get("version")
files = []
for entry in corpus.list_files(options.get("kind")):
if wanted_country and entry.country != wanted_country:
continue
if version and entry.version != version:
continue
files.append(
{
"kind": entry.kind,
"scenario_id": entry.scenario_id,
"version": entry.version,
"country": entry.country,
"family": entry.family,
"variant": entry.variant,
"file": entry.path.name,
}
)
return {"count": len(files), "files": files}
[docs]
def corpus_get(options: dict[str, Any] | None = None) -> dict[str, Any]:
"""Return one market file's XML and its provenance sidecar.
Pure helper behind :data:`CORPUS_GET_COMMAND`. Editors use it to open
a reference example next to the data file being authored: the XML a
correct ``scenario_id`` produces in ``version``, and the sidecar
that says which sources it rests on, how confident the evidence is
and how every validation rung judged it.
Args:
options: ``scenario_id`` and ``version`` (required) and an
optional ``variant`` overlay id for a bank variant.
Returns:
``{"scenario_id", "version", "variant", "xml", "provenance"}`` or
``{"error": ...}`` when the arguments are incomplete, the file
does not exist, or the installed pain001 has no corpus.
"""
corpus = _corpus_api()
if corpus is None:
return {"error": _CORPUS_MISSING}
options = options or {}
scenario_id = options.get("scenario_id")
version = options.get("version")
variant = options.get("variant") or None
if not scenario_id or not version:
return {"error": "scenario_id and version are required"}
try:
xml = corpus.get_file(scenario_id, version, variant)
record = corpus.provenance(scenario_id, version, variant)
except FileNotFoundError as exc:
return {"error": str(exc)}
return {
"scenario_id": scenario_id,
"version": version,
"variant": variant,
"xml": xml,
"provenance": record,
}
[docs]
def corpus_list_command(ls: LanguageServer, *args: Any) -> dict[str, Any]:
"""``workspace/executeCommand`` glue for :func:`corpus_list`.
Args:
ls: The language server (unused; pygls passes it first).
*args: The command arguments; the first may be a filter dict.
Returns:
The :func:`corpus_list` payload.
"""
return corpus_list(command_options(args))
[docs]
def corpus_get_command(ls: LanguageServer, *args: Any) -> dict[str, Any]:
"""``workspace/executeCommand`` glue for :func:`corpus_get`.
Args:
ls: The language server (unused; pygls passes it first).
*args: The command arguments; the first is the request dict.
Returns:
The :func:`corpus_get` payload.
"""
return corpus_get(command_options(args))