# lsdtools.advanced
URL: https://lsd.tools/docs/api-advanced
Updated: 2026-07-18

> The @tool.* decorators are built on a substrate — raw step classes, parameter descriptors, source-kind plumbing, the event bus. lsdtools.advanced exposes that substrate for the few things the declarative API cannot express. Importing from here is the honest signal that you stepped off the stable surface.

`lsdtools.advanced` is the escape hatch below the curated [`lsdtools`](/docs/api-index) 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

```python
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](/docs/tools-panels-overlays-views)
- Custom views: [Custom views](/docs/ui-custom-views)
- Surface: [lsdtools API reference](/docs/api-index)

## The four honest reasons

Reach for `advanced` when — and only when — you need one of these:

1. **Custom parameter widgets** — `param(...)` / `columnmap_param(...)` in a signature, via
 `Annotated[...]`, when the auto-form isn't enough.
2. **Hand-built menu / CLI / view contributions** — `contribute(...)` with a `MenuItem`, `CliCommand`,
 or `ViewContribution` (a `@tool.view` returns a `View`; a custom view's GTK shell registers via
 `lsdtools.views`, not here).
3. **Low-level entity / template plumbing** — `EntityAction`, `FileRole`, `EntityTemplate` for import
 roles and templates the decorators don't cover.
4. **Tuned step classes** — `LoadStep` / `ShapeStep` / `DeliverStep` authored 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](/docs/tools-panels-overlays-views) · [Custom views](/docs/ui-custom-views)

**API** — [Tool](/docs/api-tool) · [Custom views](/docs/ui-custom-views) · [describe_api](/docs/api-describe) · [PackageManager](/docs/api-package-manager)

**Examples** — [A dockable panel](/docs/ex-panel) · [A complete package](/docs/ex-full-package)