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_BICvalues 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
missingrequired fields.The returned string is a comma-prefixed sequence of
"field": placeholderlines that can be inserted just before a record object’s closing}. Placeholders are type-appropriate defaults (""for strings,0for numbers,falsefor booleans,[]for arrays,{}for objects).
- 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": placeholderlines 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.
- pain001_lsp.server.compute_diagnostics(text, message_type='pain.001.001.09')[source]¶
Compute diagnostics for a pain.001 payment-data JSON document.
Parses
textas 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.
- pain001_lsp.server.did_change(ls, params)[source]¶
Publish diagnostics when a document changes.
- Return type:
- Parameters:
ls (LanguageServer)
params (DidChangeTextDocumentParams)
- pain001_lsp.server.did_open(ls, params)[source]¶
Publish diagnostics when a document is opened.
- Return type:
- 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, orNone.
- 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_typeor the record already satisfies the required list (so callers can keep a single short-circuit check onnot missing_required_fields(...)).
- 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:
- Parameters:
ls (LanguageServer)
params (DidChangeConfigurationParams)
- pain001_lsp.server.on_initialize(ls, params)[source]¶
Honour
initializationOptions.messageTypewhen the client sets it.- Return type:
- 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 ascompute_diagnostics()so the LSP handlers can route by URI suffix without caring which engine ran.- Parameters:
- Return type:
- Returns:
A list of plain dicts shaped like the JSON-mode output, with
col_start/col_endkeys retained so editors can paint per-cell ranges. Text thecsvmodule cannot read gets oneInvalid CSVerror at the top instead.
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
DocumentSymbolwhose name is the record’sidfield (or<record N>when absent) and whose detail is thepayment_idfield (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
DocumentSymbolper 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
TextEditreplacing 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 correctscenario_idproduces inversion, 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_idandversion(required) and an optionalvariantoverlay id for a bank variant.- Return type:
- 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/executeCommandglue forcorpus_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:
- 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-overlayvariant; coverage files exercise every element and choice branch of one message type.
- pain001_lsp._corpus.corpus_list_command(ls, *args)[source]¶
workspace/executeCommandglue forcorpus_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:
- 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.
- pain001_lsp._faces.faces_list_command(ls, *args)[source]¶
workspace/executeCommandglue forfaces_list().- Parameters:
ls (
LanguageServer) – The language server (unused; pygls passes it first).*args (
Any) – The command arguments (none are read).
- Return type:
- 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) andface(required), an optionalversionand optionalbindings(an object of the keysfaces_list()names for the face).- Return type:
- 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/executeCommandglue forfaces_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:
- Returns:
The
faces_project()payload.