lsdtools API reference

lsdtools is the small, stable public API you author LSD tools against. It has about three dozen names and one rule: import only lsdtools. Everything under lsd.* is private engine internals that may change between releases.

Usage#

from lsdtools import Tool, Table, Engine, API_VERSION

API_VERSION
# → "2.1"

Everything you author with lives in that one namespace. This page routes you to a reference for each public class; for the narrative versions, start at What is LSD?.

The public surface#

from lsdtools import ...:

• Authoring — Tool · Context · StepContext
• Views (params + actions + data) — View · action · param · validators · views
• Domain — EntityAction · EntityTemplate · FileRole · columnmap_param · parse_column_map · resolve_column_map · apply_column_map · parse_source · autoselect_largecsv_source · Events
• Data — Table · Source
• Runtime / interop — Entity · Engine · RunResult · Runtime · find_runtime · API_VERSION
• Errors — ValidationError · SchemaError
• Meta — describe_api · advanced · generate_step

Reach past this line — into lsd.* — only through lsdtools.advanced, and only for the few things it documents.

Authoring#

• Tool — the one object per package; its @tool.* decorators turn functions into nodes, commands, and views.
• Context — StepContext (progress, cancel, outputs) and Context (host, engine, project, UI) that LSD injects into your functions.
• Source — the input a load step reads: files, folders, or a SQL query.

Data#

• Table — the immutable, zero-copy Arrow wrapper that flows between steps, plus its Column expressions and its Table(...) constructor.

Runtime#

• Engine — run pipelines in Python; returns a RunResult.
• Runtime — locate the installed LSD product; find_runtime() and API_VERSION.

Views#

• View — the one presentable surface: param() fields + @action + optional data, with the watch verb that links it to an entity's output.
• ViewerPayload — what a viewer-delivering @tool.deliver returns (LayerPayload / ChartPayload / LegendPayload); the framework routes it to whatever view watches the entity. See Rendering & payloads.
• UI overview — the one View model (params + @action + optional data), and how it shows: a window with the desktop, console text when headless.
• A View of params and actions — @tool.view returns a View with no kind: param() fields plus @action buttons. location= (sidebar / overlay / editor) only sets where it shows.
• Data views — @tool.view returns a data View: a table, chart, or flowchart from lsdtools.views, or a custom View subclass.
• Custom views — a hand-written View whose GTK shell registers through lsdtools.views.

Packaging#

• PackageManager — the desktop-side API behind the Package Manager.
• lsd_package.json — the manifest that makes a folder a package.
• CLI commands — lsd package, lsd <tool> <cmd>, lsd api.

Meta#

• Errors — ValidationError and SchemaError and when each is raised.
• describe_api — machine-readable JSON of every registered step.
• lsdtools.advanced — the escape hatch to lsd internals.

Related#

Learn — What is LSD? · The Tool object · Params vs ports

API — Tool · Table · Engine

Examples — Your first tool