MWArgument¶

class lsst.daf.butler.cli.utils.MWArgument(param_decls: Sequence[str], required: bool | None = None, **attrs: Any)¶

Bases: Argument

Overrides click.Argument with desired behaviors.

Attributes Summary

`human_readable_name`	Returns the human readable name of this parameter.
`param_type_name`

Methods Summary

`add_to_parser`(parser, ctx)
`consume_value`(ctx, opts)	Returns the parameter value produced by the parser.
`get_default`(ctx[, call])	Get the default for the parameter.
`get_error_hint`(ctx)	Get a stringified version of the param for use in error messages to indicate which param caused the error.
`get_help_record`(ctx)
`get_usage_pieces`(ctx)
`handle_parse_result`(ctx, opts, args)	Process the value produced by the parser from user input.
`make_metavar`([ctx])	Make the metavar for the help menu.
`process_value`(ctx, value)	Process the value of this parameter:
`resolve_envvar_value`(ctx)	Returns the value found in the environment variable(s) attached to this parameter.
`shell_complete`(ctx, incomplete)	Return a list of completions for the incomplete value.
`to_info_dict`()	Gather information that could be useful for a tool generating user-facing documentation.
`type_cast_value`(ctx, value)	Convert and validate a value against the parameter's `type`, `multiple`, and `nargs`.
`value_from_envvar`(ctx)	Process the raw environment variable string for this parameter.
`value_is_missing`(value)	A value is considered missing if:

Attributes Documentation

human_readable_name¶

param_type_name = 'argument'¶

Methods Documentation

add_to_parser(parser: _OptionParser, ctx: Context) → None¶

consume_value(ctx: Context, opts: Mapping[str, Any]) → tuple[Any, click.core.ParameterSource]¶

Returns the parameter value produced by the parser.

If the parser did not produce a value from user input, the value is either sourced from the environment variable, the default map, or the parameter’s default value. In that order of precedence.

If no value is found, an internal sentinel value is returned.

get_default(ctx: Context, call: bool = True) → Any | Callable[[], Any] | None¶

Get the default for the parameter. Tries Context.lookup_default() first, then the local default.

Parameters:

ctx – Current context.
call – If the default is a callable, call it. Disable to return the callable instead.

Changed in version 8.0.2: Type casting is no longer performed when getting a default.

Changed in version 8.0.1: Type casting can fail in resilient parsing mode. Invalid defaults will not prevent showing help text.

Changed in version 8.0: Looks at ctx.default_map first.

Changed in version 8.0: Added the call parameter.

get_error_hint(ctx: Context) → str¶: Get a stringified version of the param for use in error messages to indicate which param caused the error.

get_help_record(ctx: Context) → tuple[str, str] | None¶

get_usage_pieces(ctx: Context) → list[str]¶

handle_parse_result(ctx: Context, opts: Mapping[str, Any], args: list[str]) → tuple[Any, list[str]]¶

Process the value produced by the parser from user input.

Always process the value through the Parameter’s type, wherever it comes from.

If the parameter is deprecated, this method warn the user about it. But only if the value has been explicitly set by the user (and as such, is not coming from a default).

make_metavar(ctx: Context | None = None) → str¶

Make the metavar for the help menu.

Parameters:

ctxclick.Context or None: Context from the command.

Returns:

metavarstr: The metavar value.

Notes

Overrides click.Option.make_metavar. Always adds a space and an ellipsis (’ …’) after the metavar name if the option accepts multiple inputs.

By default click adds an ellipsis without a space between the metavar and the ellipsis, but we prefer a space between.

process_value(ctx: Context, value: Any) → Any¶

Process the value of this parameter:

Type cast the value using type_cast_value().
Check if the value is missing (see: value_is_missing()), and raise MissingParameter if it is required.
If a callback is set, call it to have the value replaced by the result of the callback. If the value was not set, the callback receive None. This keep the legacy behavior as it was before the introduction of the UNSET sentinel.

resolve_envvar_value(ctx: Context) → str | None¶

Returns the value found in the environment variable(s) attached to this parameter.

Environment variables values are always returned as strings.

This method returns None if:

the envvar property is not set on the Parameter,
the environment variable is not found in the environment,
the variable is found in the environment but its value is empty (i.e. the environment variable is present but has an empty string).

If envvar is setup with multiple environment variables, then only the first non-empty value is returned.

Caution

The raw value extracted from the environment is not normalized and is returned as-is. Any normalization or reconciliation is performed later by the Parameter’s type.

shell_complete(ctx: Context, incomplete: str) → list[CompletionItem]¶

Return a list of completions for the incomplete value. If a shell_complete function was given during init, it is used. Otherwise, the type shell_complete() function is used.

Parameters:

ctx – Invocation context for this command.
incomplete – Value being completed. May be empty.

New in version 8.0.

to_info_dict() → dict[str, Any]¶

Gather information that could be useful for a tool generating user-facing documentation.

Use click.Context.to_info_dict() to traverse the entire CLI structure.

Changed in version 8.3.0: Returns None for the default if it was not set.

New in version 8.0.

type_cast_value(ctx: Context, value: Any) → Any¶: Convert and validate a value against the parameter’s type, multiple, and nargs.

value_from_envvar(ctx: Context) → str | Sequence[str] | None¶

Process the raw environment variable string for this parameter.

Returns the string as-is or splits it into a sequence of strings if the parameter is expecting multiple values (i.e. its nargs property is set to a value other than 1).

value_is_missing(value: Any) → bool¶

A value is considered missing if:

it is UNSET,
or if it is an empty sequence while the parameter is suppose to have non-single value (i.e. nargs is not 1 or multiple is set).

Navigation

MWArgument¶