OptionSection

class lsst.daf.butler.cli.utils.OptionSection(sectionName: str, sectionText: str)

Bases: lsst.daf.butler.cli.utils.MWOption

Implements an Option that prints a section label in the help text and does not pass any value to the command function.

This class does a bit of hackery to add a section label to a click command help output: first, expose_value is set to False so that no value is passed to the command function. Second, this class overrides click.Option.get_help_record to return the section label string without any prefix so that it stands out as a section label.

This class overrides the hidden attribute because our documentation build tool, sphinx-click, implements its own get_help_record function which builds the record from other option values (e.g. name, opts), which breaks the hack we use to make get_help_record only return the sectionText. Fortunately, Click gets the value of hidden inside the Option’s get_help_record, and sphinx-click calls opt.hidden before entering its _get_help_record function. So, making the hidden property return True hides this option from sphinx-click, while allowing the section text to be returned by our get_help_record method when using Click.

The intention for this implementation is to do minimally invasive overrides of the click classes so as to be robust and easy to fix if the click internals change.

Parameters:

sectionName : str

The parameter declaration for this option. It is not shown to the user, it must be unique within the command. If using the section decorator to add a section to a command’s options, the section name is auto-generated.

sectionText : str

The text to print in the section identifier.

Attributes Summary

hidden
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)
full_process_value(ctx, value)
get_default(ctx)	Given a context variable this calculates the default value.
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, None])
get_usage_pieces(ctx)
handle_parse_result(ctx, opts, args)
make_metavar()	Overrides click.Option.make_metavar.
process_value(ctx, value)	Given a value and context this runs the logic to convert the value as necessary.
prompt_for_value(ctx)	This is an alternative flow that can be activated in the full value processing if a value does not exist.
resolve_envvar_value(ctx)
type_cast_value(ctx, value)	Given a value this runs it properly through the type system.
value_from_envvar(ctx)
value_is_missing(value)

Attributes Documentation

hidden

human_readable_name

Returns the human readable name of this parameter. This is the same as the name for options, but the metavar for arguments.

param_type_name = 'option'

Methods Documentation

add_to_parser(parser, ctx)

consume_value(ctx, opts)

full_process_value(ctx, value)

get_default(ctx)

Given a context variable this calculates the default value.

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: click.core.Context | None[click.core.Context, None]) → tuple

get_usage_pieces(ctx)

handle_parse_result(ctx, opts, args)

make_metavar() → str

Overrides click.Option.make_metavar. Makes the metavar for the help menu. Adds a space and an elipsis after the metavar name if the option accepts multiple inputs, otherwise defers to the base implementation.

By default click does not add an elipsis when multiple is True and nargs is 1. And when nargs does not equal 1 click adds an elipsis without a space between the metavar and the elipsis, but we prefer a space between.

Does not get called for some option types (e.g. flag) so metavar transformation that must apply to all types should be applied in get_help_record.

process_value(ctx, value)

Given a value and context this runs the logic to convert the value as necessary.

prompt_for_value(ctx)

This is an alternative flow that can be activated in the full value processing if a value does not exist. It will prompt the user until a valid value exists and then returns the processed value as result.

resolve_envvar_value(ctx)

type_cast_value(ctx, value)

Given a value this runs it properly through the type system. This automatically handles things like nargs and multiple as well as composite types.

value_from_envvar(ctx)

value_is_missing(value)