ExtractorContext

class nominal.experimental.extractor.context.ExtractorContext(output_dir: Path)

Bases: object

The execution context handed to an extractor function.

Use this for output paths, output declarations, and job metadata. Declare inputs and parameters with @input and @parameter so the runtime passes them as callback arguments. Context lookup methods remain available for migration and warn once per run. Authors do not construct this directly; Extractor.run() builds a SingleFileExtractorContext or ManifestExtractorContext.

output_dir: Path

property additional_tags: dict[str, str]

Tags the ingest request applies to all data from this run; empty when Nominal didn’t inject them.

property dataset_rid: str | None

RID of the dataset this run ingests into.

None when Nominal injected no value, empty included; see ingest_job_rid.

property ingest_job_rid: str | None

RID of the ingest job running this extractor.

None when Nominal injected no value, empty included – an empty environment variable means the same thing as an absent one here, as it does everywhere else in this contract.

property inputs: list[Path]

All input files Nominal mounted for this run.

Legacy authoring API: prefer a separate @input declaration per registered input. Access logs one migration warning per run; it contributes no registration metadata. Taken from the registered _NOMINAL_INPUTS metadata when present, in the order Nominal serializes them; otherwise discovered by listing the input mount, sorted by name.

property job_timestamp_metadata: TimestampMetadata | None

The job-level timestamp metadata this run’s outputs default to.

This is the metadata the pipeline resolved for the whole job (the ingest request’s override when given, else the image’s registered default) – the value a manifest output falls back to when it declares no per-output timestamp metadata of its own. None when Nominal didn’t inject it.

get_param(name: str, default: None = None) → str | None

get_param(name: str, default: str) → str

Read an optional parameter from the environment, or default when unset.

Legacy authoring API: prefer @parameter("parts", type=int, default=2) and a parts callback argument. This method logs one migration warning per run and contributes no registration metadata. Its returned values remain strings (or None). Name resolution matches param(). With registered contract metadata present, an unregistered name raises ExtractorError.

input(name: str | None = None) → Path

Resolve an input file.

Legacy authoring API: prefer @input("source", envvar="SOURCE") and a source callback argument. This method logs one migration warning per run and contributes no registration metadata.

With name – the input’s registered display name or its environment variable – returns that input’s path. Without it, returns the sole mounted input file, raising if there is not exactly one.

param(name: str) → str

Read a required parameter from the environment.

Legacy authoring API: prefer @parameter("parts", envvar="PARTS", type=int) and a parts callback argument. This method logs one migration warning per run and contributes no registration metadata.

name – the parameter’s registered display name or its environment variable – is resolved against _NOMINAL_PARAMETERS when Nominal injected it; otherwise it is treated directly as the environment variable. Raises ExtractorError when the parameter is not set. Values returned by this legacy method remain strings. With registered contract metadata present, an unregistered name raises ExtractorError.