# Extractor

## class nominal.experimental.extractor.runner.Extractor(_fn, _context_cls, _output_format=None, _timestamp_column=None, _timestamp_type=None)

Bases: [`Generic`](https://docs.python.org/3/library/typing.html#typing.Generic "(in Python v3.15)")[`_CtxT`]

A containerized-extractor entrypoint produced by `single_file_extractor()` or `manifest_extractor()`.

Declare callback inputs and parameters with `@input` and `@parameter` beneath the
outer extractor decorator. They bind as keyword arguments after the output context.
Use [`registration_kwargs()`](https://dev.nominal.io/python/ref/generated/nominal.experimental.extractor.runner.Extractor.md#nominal.experimental.extractor.runner.Extractor.registration_kwargs "nominal.experimental.extractor.runner.Extractor.registration_kwargs") to export the same contract for image registration.
Call [`run()`](https://dev.nominal.io/python/ref/generated/nominal.experimental.extractor.runner.Extractor.md#nominal.experimental.extractor.runner.Extractor.run "nominal.experimental.extractor.runner.Extractor.run") as the container’s entrypoint to drive it from the environment. In tests,
drive it with [`run()`](https://dev.nominal.io/python/ref/generated/nominal.experimental.extractor.runner.Extractor.md#nominal.experimental.extractor.runner.Extractor.run "nominal.experimental.extractor.runner.Extractor.run") (`env=...`, `exit=False`) rather than constructing a context by
hand. Carries the wrapped function’s metadata (`__name__`, `__doc__`, …) like any well-behaved
decorator.

Assemble a callback’s declarations; prefer the public extractor decorators.

### catalog_manifest(*, id, version, display_name, description)

Export a first-party catalog manifest from declarations and release identity.

Returns fresh JSON/YAML-serializable data for `extractor.yaml`, including error
fallbacks. Does not execute extraction, read the environment, build an image, write
a file, or publish a release. The publisher owns versioning and artifact identity.

Catalog export requires at least one input with suffix filters, uppercase environment
variables, and epoch or ISO 8601 timestamp defaults. Omitted error messages are derived
from their codes and truncated to 512 characters. Error codes must be non-reserved
catalog identifiers. Identical error fallbacks sharing an exit code are combined;
conflicting fallbacks are rejected.
Input display metadata, converters and defaults have no catalog schema fields.
Incomplete or unrepresentable metadata raises ValueError before publication.

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

### registration_kwargs()

Build image registration arguments exclusively from decorator declarations.

Pass the result as `**entrypoint.registration_kwargs()` to
`ContainerizedExtractor.register_image(tarball, tag=..., ...)`. Returns fresh lists of
FileExtractionInput, FileExtractionParameter, and ExitCodeMapping objects, the output format, and the two
default timestamp settings. List order follows the decorators from top to bottom.

Declare `default_timestamp_column` and `default_timestamp_type` on the outer
decorator. Manifest output format is automatic; single-file extractors also need an
explicit `output_format`. Missing required registration settings raise ValueError.
Timestamp settings describe image defaults; they do not populate local job metadata.

Does not execute the callback or converters, inspect its body, read the environment,
upload an image, or activate it. Parameter types/defaults remain runtime-only.
Error mappings require a non-reserved code; omitted messages are derived from the code
and truncated to 512 characters. Identical exit-code fallbacks are combined, while
conflicting fallbacks raise ValueError.
Legacy lookups add no metadata: no argument declarations yields empty
inputs/parameters. Keep complete manual registration metadata for partially migrated
extractors with additional undeclared dependencies.

Return type:
:   *_RegistrationKwargs*

### run(*, env=None, exit=True, termination_log_path=_DEFAULT_TERMINATION_LOG_PATH)

Run the extractor against the environment and finalize its outputs.

Intended as the container entrypoint (`if __name__ == "__main__": my_extractor.run()`).
Builds a context, resolves all declared arguments, invokes the callback, and finalizes
its outputs. `env` replaces the process environment when supplied; required values
must be present there, while optional parameters use their declared defaults. Output
directories must already exist. Binding failures prevent callback execution and use
the same error handling as startup, extraction, and finalization failures.

On success returns the context. With `exit=True` (the default), mapped exceptions
write bounded structured JSON to the termination log and stderr, then print the full
traceback to stderr before exiting with their mapped status. The closest mapped class in the
exception’s MRO wins. Other failures
print a traceback and exit 1. Pass `exit=False` to re-raise the original exception
without reporting – useful in tests. `termination_log_path` is a trusted explicit
output path (default `/dev/termination-log`), never read from the environment. Use a
temporary path when testing mapped exits locally.

Return type:
:   *_CtxT*