Python API reference

The standalone server’s importable Python surface (used by the runnable examples and any tooling that wires the pure helpers in-process without going through the LSP transport).

pain001-lsp: a Language Server Protocol server for the pain001 library.

Server module

Language Server Protocol (LSP) server for pain001 payment-data files.

This server helps developers author pain.001 payment-data JSON files - a JSON array of flat record objects (the same records that drive XML generation). It provides four editor features, all backed by the pain001 public API so they behave identically to the CLI, REST API, and MCP server:

  • Diagnostics - each record is validated against a message type’s input JSON Schema, and any debtor_account_IBAN / creditor_account_IBAN / charge_account_IBAN / debtor_agent_BIC / creditor_agent_BIC / forwarding_agent_BIC values are additionally checked with the dedicated IBAN / BIC validators.

  • Completion - every input field (with its description) plus the list of supported message types are offered as completion items.

  • Hover - hovering a field name shows its schema description.

  • Code actions - when the document is missing required fields, the server offers a single “Add missing required fields” quick-fix that inserts placeholder values for each missing field on the affected record.

The intended message type defaults to pain.001.001.09 (Customer Credit Transfer Initiation V09); the pure helpers accept a message_type argument so a different type can be configured. Editors can override the default per-workspace by passing initializationOptions of the form {"messageType": "pain.001.001.11"}.

Launching

The package installs a pain001-lsp console entry point (declared in pyproject.toml as pain001_lsp.server:main) which starts the server over stdio:

pain001-lsp

Editor wiring

Point your editor’s LSP client at the pain001-lsp command for JSON files. For Neovim (nvim-lspconfig / the built-in vim.lsp.config API) register a server whose cmd is { "pain001-lsp" } and filetypes includes "json". VS Code clients spawn the same command over stdio.

The business logic lives in pure, testable helper functions (compute_diagnostics(), completion_items(), hover_text(), missing_required_fields(), build_insert_text()); the LSP handlers below are thin glue that map those plain dicts to lsprotocol types.

pain001_lsp.server.build_insert_text(missing, message_type='pain.001.001.09')[source]

Render JSON-Object fragments for the missing required fields.

The returned string is a comma-prefixed sequence of "field": placeholder lines that can be inserted just before a record object’s closing }. Placeholders are type-appropriate defaults ("" for strings, 0 for numbers, false for booleans, [] for arrays, {} for objects).

Parameters:
  • missing (list[str]) – Required field names to insert.

  • message_type (str) – The pain message type whose schema supplies types.

Return type:

str

Returns:

A multi-line snippet, or the empty string if no fields are missing or the schema is not bundled.

pain001_lsp.server.code_action(ls, params)[source]

Offer a “fill in missing required fields” quick-fix.

Active when the record under the cursor (or the first record, if the params don’t specify one) is missing schema-required fields. Inserts JSON "field": placeholder lines just before that record’s closing }.

Return type:

list[CodeAction]

Parameters:
  • ls (LanguageServer)

  • params (CodeActionParams)

pain001_lsp.server.completion(ls, params)[source]

Offer input-field and message-type completions.

Return type:

CompletionList

Parameters:
  • ls (LanguageServer)

  • params (CompletionParams)

pain001_lsp.server.completion_items(message_type='pain.001.001.09')[source]

Return completion items for a pain.001 payment-data document.

Offers every input field for message_type (with its schema description as the detail) plus every supported message type.

Parameters:

message_type (str) – The pain message type whose fields are offered.

Return type:

list[dict]

Returns:

A list of {"label": str, "detail": str, "kind": "field"} dicts.

pain001_lsp.server.compute_diagnostics(text, message_type='pain.001.001.09')[source]

Compute diagnostics for a pain.001 payment-data JSON document.

Parses text as JSON (a list of record dicts, or a single dict treated as one record). When the text does not parse (a syntax error, an integer too long to convert, or nesting too deep), returns a single diagnostic, at the offending position when JSON reports one. For valid JSON, runs schema validation against the bundled JSON Schema and additionally checks any present identifier fields with the IBAN / BIC validators.

Parameters:
  • text (str) – The raw document text.

  • message_type (str) – The pain message type to validate against.

Return type:

list[dict]

Returns:

A list of plain dicts:

{"line": int, "character": int,
 "severity": "error" | "warning", "message": str}

pain001_lsp.server.did_change(ls, params)[source]

Publish diagnostics when a document changes.

Return type:

None

Parameters:
  • ls (LanguageServer)

  • params (DidChangeTextDocumentParams)

pain001_lsp.server.did_open(ls, params)[source]

Publish diagnostics when a document is opened.

Return type:

None

Parameters:
  • ls (LanguageServer)

  • params (DidOpenTextDocumentParams)

pain001_lsp.server.hover(ls, params)[source]

Show the schema description for the field under the cursor.

Return type:

Hover | None

Parameters:
  • ls (LanguageServer)

  • params (HoverParams)

pain001_lsp.server.hover_text(field, message_type='pain.001.001.09')[source]

Return the schema description for field, or None.

Parameters:
  • field (str) – An input field name.

  • message_type (str) – The pain message type whose schema is consulted.

Return type:

str | None

Returns:

The field’s description string, or None if the field is unknown or has no description.

pain001_lsp.server.main()[source]

Start the pain001-lsp language server over stdio.

Return type:

None

pain001_lsp.server.missing_required_fields(record, message_type='pain.001.001.09')[source]

List required field names absent from record.

Returns an empty list if no schema is bundled for message_type or the record already satisfies the required list (so callers can keep a single short-circuit check on not missing_required_fields(...)).

Parameters:
  • record (dict[str, Any]) – A flat payment record.

  • message_type (str) – The pain message type whose required list applies.

Return type:

list[str]

Returns:

A list of field names from the schema’s required array that are missing from record.

pain001_lsp.server.on_did_change_configuration(ls, params)[source]

Live-switch the active message type when the client reconfigures.

Editors that wire workspace/didChangeConfiguration can push {"pain001": {"messageType": "pain.001.001.11"}} (or a top-level {"messageType": ...}) and have every subsequent diagnostic / completion / hover / code-action call use the new schema, with no restart required.

Return type:

None

Parameters:
  • ls (LanguageServer)

  • params (DidChangeConfigurationParams)

pain001_lsp.server.on_initialize(ls, params)[source]

Honour initializationOptions.messageType when the client sets it.

Return type:

None

Parameters:
  • ls (LanguageServer)

  • params (InitializeParams)

The helpers below live in their own modules and are imported into pain001_lsp.server, so from pain001_lsp.server import corpus_list (or any of them) keeps working.

CSV diagnostics

Lint a payment CSV document into the server’s plain-dict diagnostics.

The core’s pain001.lsp.diagnostics.diagnostics_for_csv() reads the text with the csv module, which raises csv.Error on text it cannot read: a bare carriage return inside an unquoted field, or, before Python 3.11, a NUL byte. Editor text can hold either, so that ends as one diagnostic, never as an exception escaping a keystroke.

pain001_lsp._csv.compute_diagnostics_csv(text, message_type='pain.001.001.09')[source]

Compute diagnostics for a pain.001 payment-data CSV document.

Wraps pain001.lsp.diagnostics.diagnostics_for_csv() and returns the same plain-dict shape as compute_diagnostics() so the LSP handlers can route by URI suffix without caring which engine ran.

Parameters:
  • text (str) – The raw CSV document text.

  • message_type (str) – The pain message type to validate against.

Return type:

list[dict]

Returns:

A list of plain dicts shaped like the JSON-mode output, with col_start / col_end keys retained so editors can paint per-cell ranges. Text the csv module cannot read gets one Invalid CSV error at the top instead.

pain001_lsp._csv.csv_diagnostics(text, message_type)[source]

Return the core’s CSV diagnostics as plain dicts, or one read error.

Return type:

list[dict]

Parameters:
  • text (str)

  • message_type (str)

Formatting and outline

Whole-document handlers: formatting and the record outline.

pain001_lsp._layout.document_symbol(ls, params)[source]

Return an outline of every top-level record in the document.

Each record becomes one DocumentSymbol whose name is the record’s id field (or <record N> when absent) and whose detail is the payment_id field (or empty when absent). The range covers the record’s opening { through its closing } so editors can jump-to / collapse on the record under the cursor.

Parameters:
  • ls (LanguageServer) – The active language server instance.

  • params (DocumentSymbolParams) – The LSP document-symbol parameters.

Return type:

list[DocumentSymbol]

Returns:

One DocumentSymbol per top-level record, or an empty list when the document is malformed or has no records.

pain001_lsp._layout.formatting(ls, params)[source]

Pretty-print the document as a JSON array of records.

Re-serialises with two-space indentation and a trailing newline so diffs against the previously-saved version stay minimal. Malformed JSON is left untouched (no edits returned) - the diagnostics handler already surfaces the syntax error.

Parameters:
  • ls (LanguageServer) – The active language server instance.

  • params (DocumentFormattingParams) – The LSP formatting parameters identifying the document.

Return type:

list[TextEdit]

Returns:

A single TextEdit replacing the document with its formatted text, or an empty list when the document is malformed or already formatted.

Corpus commands

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.

pain001_lsp._corpus.corpus_get(options=None)[source]

Return one market file’s XML and its provenance sidecar.

Pure helper behind 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.

Parameters:

options (dict[str, Any] | None) – scenario_id and version (required) and an optional variant overlay id for a bank variant.

Return type:

dict[str, Any]

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.

pain001_lsp._corpus.corpus_get_command(ls, *args)[source]

workspace/executeCommand glue for corpus_get().

Parameters:
  • ls (LanguageServer) – The language server (unused; pygls passes it first).

  • *args (Any) – The command arguments; the first is the request dict.

Return type:

dict[str, Any]

Returns:

The corpus_get() payload.

pain001_lsp._corpus.corpus_list(options=None)[source]

List the validated example files pain001 ships.

Pure helper behind 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.

Parameters:

options (dict[str, Any] | None) – Optional filters: kind (market or coverage), country (two letters, any case) and version (a message type such as pain.001.001.09).

Return type:

dict[str, Any]

Returns:

{"count", "files": [...]} or {"error": ...} when the installed pain001 has no corpus.

pain001_lsp._corpus.corpus_list_command(ls, *args)[source]

workspace/executeCommand glue for corpus_list().

Parameters:
  • ls (LanguageServer) – The language server (unused; pygls passes it first).

  • *args (Any) – The command arguments; the first may be a filter dict.

Return type:

dict[str, Any]

Returns:

The corpus_list() payload.

Faces commands

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 pain001.faces (pain001 >= 0.0.78) through 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.

pain001_lsp._faces.faces_list()[source]

List the faces, their targets and the binding keys each accepts.

Pure helper behind FACES_LIST_COMMAND.

Return type:

dict[str, Any]

Returns:

{"count", "faces": [{"name", "description", "bindings"}, ...]} or {"error": ...} when the installed pain001 has no faces.

pain001_lsp._faces.faces_list_command(ls, *args)[source]

workspace/executeCommand glue for faces_list().

Parameters:
  • ls (LanguageServer) – The language server (unused; pygls passes it first).

  • *args (Any) – The command arguments (none are read).

Return type:

dict[str, Any]

Returns:

The faces_list() payload.

pain001_lsp._faces.faces_project(options=None)[source]

Project a pain.001 document into a face, with its loss report.

Pure helper behind 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.

Parameters:

options (dict[str, Any] | None) – xml (the document text) and face (required), an optional version and optional bindings (an object of the keys faces_list() names for the face).

Return type:

dict[str, Any]

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.

pain001_lsp._faces.faces_project_command(ls, *args)[source]

workspace/executeCommand glue for faces_project().

Parameters:
  • ls (LanguageServer) – The language server (unused; pygls passes it first).

  • *args (Any) – The command arguments; the first is the request dict.

Return type:

dict[str, Any]

Returns:

The faces_project() payload.