input#

nominal.experimental.extractor.decorators.input(argument, *, envvar=None, name=None, description=None, file_suffixes=(), default=_MISSING)#

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 (str)

    Name of the callback argument to populate.

  • envvar (str | None)

    Input environment variable; defaults to the uppercase argument name.

  • name (str | None)

    Registration display name; defaults to the argument name.

  • description (str | None)

    Optional registration description.

  • file_suffixes (Sequence[str])

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

  • default (None | _Missing)

    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.

Return type:

_Input