# 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*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Name of the callback argument to populate.
    - **envvar** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Input environment variable; defaults to the uppercase argument name.
    - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Registration display name; defaults to the argument name.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Optional registration description.
    - **file_suffixes** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

      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**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – A name is invalid or reserved, or the default is unsupported.
    - [**ExtractorError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.ExtractorError.md#nominal.exceptions.ExtractorError "nominal.exceptions.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*