Extractor

class nominal.experimental.extractor.runner.Extractor(_fn: Callable[[...], None], _context_cls: type[_CtxT], _output_format: FileOutputFormat | None = None, _timestamp_column: str | None = None, _timestamp_type: Iso8601 | Epoch | Relative | Custom | Literal['iso_8601', 'epoch_picoseconds', 'epoch_nanoseconds', 'epoch_microseconds', 'epoch_milliseconds', 'epoch_seconds', 'epoch_minutes', 'epoch_hours', 'epoch_days'] | None = None)

Bases: Generic[_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() to export the same contract for image registration. Call run() as the container’s entrypoint to drive it from the environment. In tests, drive it with 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: str, version: str, display_name: str, description: str) → dict[str, Any]

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.

registration_kwargs() → _RegistrationKwargs

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.

run(*, env: Mapping[str, str] | None = None, exit: bool = True, termination_log_path: str | Path = _DEFAULT_TERMINATION_LOG_PATH) → _CtxT

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.