# parameter

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

Declare a setting so your callback receives a usable Python value.

For example, `@parameter("parts", type=IntRange(min=1), default=2)` supplies
the callback’s `parts: int` argument. Omission gives 2; a supplied value is converted
and checked before extraction starts. This also declares the setting for registration.

Place below the outer extractor decorator, with no default on the callback argument.
Binding happens before extraction and uses the runner’s normal error mappings. Registered
parameter metadata is authoritative: an unknown parameter fails even if it has a default.
Registration stores names, descriptions, environment variables, and requiredness;
converters and default values remain runtime settings.

Parameters:
:   - **argument** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

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

      Parameter 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.
    - **type** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.15)")*[**[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]**,* [*object*](https://docs.python.org/3/builtins/functions.html#object "(in Python v3.15)")*]* *|* *_Missing*)

      Converter for supplied strings. When omitted, infer str/int/float/bool from
      a concrete default, otherwise use str. Explicit converters take precedence;
      annotations do not select conversion. Boolean conversion accepts true/false,
      yes/no, on/off, and 1/0 case-insensitively. Float values must be finite.
    - **default** ([*object*](https://docs.python.org/3/builtins/functions.html#object "(in Python v3.15)"))

      Already-converted Python value used when absent, including None; omit to
      require the parameter. Built-in types and constraints validate concrete defaults.
      Custom converters are never invoked on defaults. An empty supplied string
      is a value, not a request for the default.

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – A name is invalid or reserved, or a constrained default is invalid.
    - [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – The converter is not callable or a default has an incompatible type.
    - [**ExtractorError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.ExtractorError.md#nominal.exceptions.ExtractorError "nominal.exceptions.ExtractorError") – At binding time, a parameter is missing or unregistered, or conversion
      raises ValueError or TypeError. Those converter messages and values are suppressed,
      except BadParameter, whose author-controlled diagnostic is included.

Return type:
:   *_Parameter*

Other converter exceptions propagate unchanged to the runner, including their messages
in tracebacks and mapped termination reports. Wrap third-party failures in ValueError
or TypeError to sanitize them, or BadParameter with a message safe to display.