input#

nominal.experimental.extractor.decorators.input(argument: str, *, envvar: str | None = None, name: str | None = None, description: str | None = None, file_suffixes: Sequence[str] = (), default: None | _Missing = _MISSING) → _Input#

Declare a file your callback needs and receive its mounted path.

For example, @input("recording", envvar="SOURCE", file_suffixes=["csv"]) supplies the callback’s recording: Path argument and describes that input for registration. Use default=None and Path | None for an optional file.

Place below the outer extractor decorator. The named callback argument must accept a keyword value and have no signature default. Annotations describe the received value; they do not control binding. Registered metadata is authoritative when present; otherwise the path comes from the declared environment variable. Lookup matches environment variables exactly, not display names.

Parameters:

  • argument – Name of the callback argument to populate.

  • envvar – Input environment variable; defaults to the uppercase argument name.

  • name – Registration display name; defaults to the argument name.

  • description – Optional registration description.

  • file_suffixes – Registration filters such as [“csv”, “mcap”]; empty accepts any suffix. These do not validate the local file’s extension.

  • default – Omit to require the input, or use None to allow an absent file. Other defaults are unsupported.

Raises:

  • ValueError – A name is invalid or reserved, or the default is unsupported.

  • ExtractorError – At binding time, a required input is absent or a supplied path does not exist as a file. All inputs resolve before the callback runs.