All docs
lsdtools.advanced
lsdtools.advanced is the escape hatch to lsd internals — four honest reasons to reach in, and the grouped names it exposes. Use it sparingly.
lsdtools.advanced is the escape hatch below the curated lsdtools surface. The
@tool.* decorators are built on a substrate — raw step classes, parameter descriptors, the
source-kind registry, the event bus. Reach in only when the declarative API genuinely can't express
something. Importing a name from here is the honest signal that you stepped off the stable surface.
Usage#
from typing import Annotated
from lsdtools import Tool, Table
from lsdtools.advanced import param
tool = Tool("demo")
@tool.shape
def clip(t: Table, hi: Annotated[float, param(min=0, max=1)] = 0.5) -> Table:
...
# → a tuned parameter widget the declarative form couldn't express
Where to start#
- UI: Contributing UI
- Custom views: Custom views
- Surface: lsdtools API reference
The four honest reasons#
Reach for advanced when — and only when — you need one of these:
- Custom parameter widgets —
param(...)/columnmap_param(...)in a signature, viaAnnotated[...], when the auto-form isn't enough. - Hand-built menu / CLI / view contributions —
contribute(...)with aMenuItem,CliCommand, orViewContribution(a@tool.viewreturns aView; a custom view's GTK shell registers vialsdtools.views, not here). - Low-level entity / template plumbing —
EntityAction,FileRole,EntityTemplatefor import roles and templates the decorators don't cover. - Tuned step classes —
LoadStep/ShapeStep/DeliverStepauthored as classes when a decorated function can't carry the behavior.
The names it exposes#
Grouped by area (import from lsdtools.advanced):
| Group | Names |
|---|---|
| Configurable / params | Configurable, Container, ParameterInfo, ValidationResult, param, columnmap_param, COLUMNMAP_WIDGET, column-map + file-input helpers |
| Sources | source_param, SourceKind, FileSourceConfig, SqlSourceConfig, LargeCsvConfig, register_source_kind, source_kind(s), parse_source |
| Event bus | Event, EventBus, Events |
| Raw flow | LoadStep, ShapeStep, DeliverStep, the bare load / shape / deliver, combine_tables, available_steps |
| Tree | ScriptEntity, EntityAction, CreateSpec, topological_order, dependents_map, available_entity_types |
| Runtime | run_pipeline, PipelineResult, RunReport, describe_text, describe_markdown |
| Packages / contributions | PackageManager, PackageInfo, scaffold, contribute, ViewContribution, MenuItem, CliCommand, EntityTemplate, FileRole, registry |
Related#
Learn — Contributing UI · Custom views
API — Tool · Custom views · describe_api · PackageManager
Examples — A dockable panel · A complete package