2.27.2.3. pycsamt.pipeline._registry#

Step registry for the pyCSAMT processing pipeline.

Every processing operation exposed by pycsamt.emtools is described by a StepSpec entry in STEP_REGISTRY. Each entry carries:

A short code (e.g. "NR001") and a human name (e.g. "notch_powerline") so users can look up steps either way.
The module path and function name needed to import the transform lazily (avoiding circular imports at startup).
An optional override_fn for two-phase steps (SS002/SS003) and wrapper steps (NR007) that cannot be described by a single function reference.
A list of (module, fn_name) pairs for QC / diagnostic plot functions that the pipeline calls automatically after each step.
Default parameters merged with any user-supplied overrides.
A returns_sites flag: False for diagnostic-only (plot) steps that do not transform the Sites object.

Functions

`categories`()	Return a sorted list of distinct step categories.
`list_steps`([category])	Return all registered `StepSpec` objects, optionally filtered.
`lookup_step`(code_or_name)	Return the `StepSpec` for code_or_name.
`register_step`(spec, *[, replace_existing, ...])	Register a third-party `StepSpec` into the pipeline registry.
`step_codes`()	Return a sorted list of all step codes.
`step_names`()	Return a sorted list of all step names.
`unregister_step`(code_or_name, *[, missing_ok])	Remove a previously-registered step from the pipeline registry.

Classes

StepSpec(code, name, label, category[, ...])

Immutable descriptor for one pipeline step.

class pycsamt.pipeline._registry.StepSpec(code, name, label, category, defaults=<factory>, returns_sites=True, mod=None, fn_name=None, qc_defs=<factory>, override_fn=None, origin='builtin')[source]

Bases: object

Immutable descriptor for one pipeline step.

Parameters:

code (str) – Short uppercase identifier, e.g. "NR001".
name (str) – Snake-case name, e.g. "notch_powerline".
label (str) – Human-readable label shown in pipeline __repr__.
category (str) – Logical group ("frequency", "noise_removal", "static_shift", "tensor", "dimensionality", "skew", "source_effects", "qc").
defaults (dict) – Keyword arguments passed to the transform function when not overridden by the user.
returns_sites (bool) – True – step transforms the Sites object (default). False – diagnostic-only step; the Sites pass through unchanged.
mod (str | None) – Dotted module path for the primary transform function. None when override_fn is provided.
fn_name (str | None) – Name of the transform function inside mod. None when override_fn is provided.
qc_defs (list[tuple[str, str]]) – List of (module_path, function_name) pairs. The pipeline calls these after each step to generate QC figures.
override_fn (Callable | None) – Direct callable override. When set, mod / fn_name are ignored.
origin (str) – "builtin" for the 47 steps shipped with pyCSAMT (default), or "plugin" for anything added via register_step(). Stamped automatically by register_step() — callers never need to set it.

code: str

name: str

label: str

category: str

defaults: dict

returns_sites: bool = True

mod: str | None = None

fn_name: str | None = None

qc_defs: list[tuple[str, str]]

override_fn: Callable | None = None

origin: str = 'builtin'

get_fn()[source]

Return (lazily imported) transform function.

Return type:: Callable

get_qc_fns()[source]

Return list of (fn_name, callable) QC plot functions.

Return type:: list[tuple[str, Callable]]

pycsamt.pipeline._registry.lookup_step(code_or_name)[source]

Return the StepSpec for code_or_name.

Parameters:: code_or_name (str) – Either the uppercase code ("NR001") or the snake-case name ("notch_powerline").
Raises:: KeyError – When neither a code nor a name matches.
Return type:: StepSpec

pycsamt.pipeline._registry.list_steps(category=None)[source]

Return all registered StepSpec objects, optionally filtered.

Parameters:: category (str | None) – When supplied, only steps whose category matches this string are returned.
Return type:: list[StepSpec]

pycsamt.pipeline._registry.step_codes()[source]

Return a sorted list of all step codes.

Return type:: list[str]

pycsamt.pipeline._registry.step_names()[source]

Return a sorted list of all step names.

Return type:: list[str]

pycsamt.pipeline._registry.categories()[source]

Return a sorted list of distinct step categories.

Return type:: list[str]

pycsamt.pipeline._registry.register_step(spec, *, replace_existing=False, validate=True)[source]

Register a third-party StepSpec into the pipeline registry.

This is the extension point for anything outside the 47 steps shipped with pyCSAMT — a plugin package (see pycsamt.pipeline.discover_plugins()) or a one-off custom step defined in a user script. Once registered, the step is usable everywhere a built-in step is: Step(code), the CLI (pycsamt pipe steps, pipe run --steps ...), presets, etc.

Parameters:

spec (StepSpec) – The step to register. Its origin is always overwritten to "plugin" regardless of what the caller passed.
replace_existing (bool) – If False (default), raises ValueError when spec.code or spec.name already exists in the registry. Set True to overwrite an existing entry (built-in or previously-registered plugin) — e.g. to patch a built-in step’s implementation.
validate (bool) – If True (default), resolves spec.get_fn() once before inserting, so a typo’d mod/fn_name or a broken override_fn is caught at registration time rather than at the first pipeline run. On failure the registry is left untouched.

Returns:

The registered spec (with origin="plugin" stamped on it).

Return type:

StepSpec

Raises:

ValueError – spec.code or spec.name collides with an existing entry and replace_existing is False.
ModuleNotFoundError, AttributeError, RuntimeError – validate=True and spec.get_fn() could not resolve a callable (bad mod, missing fn_name, or neither mod/ fn_name nor override_fn set) — whatever StepSpec.get_fn() itself raises propagates unchanged.

pycsamt.pipeline._registry.unregister_step(code_or_name, *, missing_ok=False)[source]

Remove a previously-registered step from the pipeline registry.

Parameters:

code_or_name (str) – The step’s code or name (see lookup_step()).
missing_ok (bool) – If False (default), raises KeyError when no such step is registered. Set True to no-op instead.

Return type:

None