# SingleFileExtractorContext

## class nominal.experimental.extractor.context.SingleFileExtractorContext(output_dir)

Bases: [`ExtractorContext`](https://dev.nominal.io/python/ref/generated/nominal.experimental.extractor.context.ExtractorContext.md#nominal.experimental.extractor.context.ExtractorContext "nominal.experimental.extractor.context.ExtractorContext")

Context for `single_file_extractor()` functions: declare the one output via [`set_output()`](https://dev.nominal.io/python/ref/generated/nominal.experimental.extractor.context.SingleFileExtractorContext.md#nominal.experimental.extractor.context.SingleFileExtractorContext.set_output "nominal.experimental.extractor.context.SingleFileExtractorContext.set_output").

### 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`](https://dev.nominal.io/python/ref/generated/nominal.experimental.extractor.context.SingleFileExtractorContext.md#nominal.experimental.extractor.context.SingleFileExtractorContext.ingest_job_rid "nominal.experimental.extractor.context.SingleFileExtractorContext.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, default=None)

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()`](https://dev.nominal.io/python/ref/generated/nominal.experimental.extractor.context.SingleFileExtractorContext.md#nominal.experimental.extractor.context.SingleFileExtractorContext.param "nominal.experimental.extractor.context.SingleFileExtractorContext.param"). With registered contract metadata present,
an unregistered `name` raises `ExtractorError`.

Return type:
:   [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") | *None*

### input(name=None)

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.

Return type:
:   [*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)")

### param(name)

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`.

Return type:
:   [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")

### set_output(path)

Declare the single file you wrote to the output directory.

Records the file (it must already exist under `output_dir`); it does not write anything
itself. A single-file extractor produces exactly one output, so a second call raises. Use
`manifest_extractor()` (with the image registered under the `MANIFEST` output format)
to emit multiple files.

Return type:
:   [*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)")