parameter#

nominal.experimental.extractor.decorators.parameter(argument: str, *, envvar: str | None = None, name: str | None = None, description: str | None = None, type: Callable[[str], object] | _Missing = _MISSING, default: object = _MISSING) → _Parameter#

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 – Name of the explicit callback argument to populate.

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

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

  • description – Optional registration description.

  • type – 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 – 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 – A name is invalid or reserved, or a constrained default is invalid.

  • TypeError – The converter is not callable or a default has an incompatible type.

  • 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.

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.