ButlerCommand

class lsst.daf.butler.cli.utils.ButlerCommand(*args: Any, **kwargs: Any)

Bases: MWCommand

Command subclass with butler-command specific overrides.

Attributes Summary

allow_extra_args	the default for the Context.allow_extra_args flag.
allow_interspersed_args	the default for the Context.allow_interspersed_args flag.
epilog	Override the epilog attribute to add extra_epilog (if defined by a subclass) to the end of any epilog provided by a subcommand.
extra_epilog
ignore_unknown_options	the default for the Context.ignore_unknown_options flag.

Methods Summary

__call__(*args, **kwargs)	Alias for main().
collect_usage_pieces(ctx)	Returns all the pieces that go into the usage line and returns it as a list of strings.
format_epilog(ctx, formatter)	Writes the epilog into the formatter if it exists.
format_help(ctx, formatter)	Writes the help into the formatter if it exists.
format_help_text(ctx, formatter)	Writes the help text to the formatter if it exists.
format_options(ctx, formatter)	Writes all the options into the formatter if they exist.
format_usage(ctx, formatter)	Writes the usage line into the formatter.
get_help(ctx)	Formats the help into a string and returns it.
get_help_option(ctx)	Returns the help option object.
get_help_option_names(ctx)	Returns the names for the help option.
get_params(ctx)
get_short_help_str([limit])	Gets short help for the command or makes it by shortening the long help string.
get_usage(ctx)	Formats the usage line into a string and returns it.
invoke(ctx)	Given a context, this invokes the attached callback (if it exists) in the right way.
main([args, prog_name, complete_var, ...])	This is the way to invoke a script with all the bells and whistles as a command line application.
make_context(info_name, args[, parent])	This function when given an info name and arguments will kick off the parsing and create a new Context.
make_parser(ctx)	Creates the underlying option parser for this command.
parse_args(ctx, args)	Given a context and a list of arguments this creates the parser and parses the arguments, then modifies the context as necessary.
shell_complete(ctx, incomplete)	Return a list of completions for the incomplete value.
to_info_dict(ctx)	Gather information that could be useful for a tool generating user-facing documentation.

Attributes Documentation

allow_extra_args = False

the default for the Context.allow_extra_args flag.

allow_interspersed_args = True

the default for the Context.allow_interspersed_args flag.

epilog

Override the epilog attribute to add extra_epilog (if defined by a subclass) to the end of any epilog provided by a subcommand.

extra_epilog: str | None = "See 'butler --help' for more options."

ignore_unknown_options = False

the default for the Context.ignore_unknown_options flag.

Methods Documentation

__call__(*args: Any, **kwargs: Any) → Any

Alias for main().

collect_usage_pieces(ctx: Context) → List[str]

Returns all the pieces that go into the usage line and returns it as a list of strings.

format_epilog(ctx: Context, formatter: HelpFormatter) → None

Writes the epilog into the formatter if it exists.

format_help(ctx: Context, formatter: HelpFormatter) → None

Writes the help into the formatter if it exists.

This is a low-level method called by get_help().

This calls the following methods:

• format_usage()

• format_help_text()

• format_options()

• format_epilog()

format_help_text(ctx: Context, formatter: HelpFormatter) → None

Writes the help text to the formatter if it exists.

format_options(ctx: Context, formatter: HelpFormatter) → None

Writes all the options into the formatter if they exist.

format_usage(ctx: Context, formatter: HelpFormatter) → None

Writes the usage line into the formatter.

This is a low-level method called by get_usage().

get_help(ctx: Context) → str

Formats the help into a string and returns it.

Calls format_help() internally.

get_help_option(ctx: Context) → Option | None

Returns the help option object.

get_help_option_names(ctx: Context) → List[str]

Returns the names for the help option.

get_params(ctx: Context) → List[Parameter]

get_short_help_str(limit: int = 45) → str

Gets short help for the command or makes it by shortening the long help string.

get_usage(ctx: Context) → str

Formats the usage line into a string and returns it.

Calls format_usage() internally.

invoke(ctx: Context) → Any

Given a context, this invokes the attached callback (if it exists) in the right way.

main(args: Sequence[str] | None = None, prog_name: str | None = None, complete_var: str | None = None, standalone_mode: bool = True, windows_expand_args: bool = True, **extra: Any) → Any

This is the way to invoke a script with all the bells and whistles as a command line application. This will always terminate the application after a call. If this is not wanted, SystemExit needs to be caught.

This method is also available by directly calling the instance of a Command.

Parameters:

• args – the arguments that should be used for parsing. If not provided, sys.argv[1:] is used.

• prog_name – the program name that should be used. By default the program name is constructed by taking the file name from sys.argv[0].

• complete_var – the environment variable that controls the bash completion support. The default is "_<prog_name>_COMPLETE" with prog_name in uppercase.

• standalone_mode – the default behavior is to invoke the script in standalone mode. Click will then handle exceptions and convert them into error messages and the function will never return but shut down the interpreter. If this is set to False they will be propagated to the caller and the return value of this function is the return value of invoke().

• windows_expand_args – Expand glob patterns, user dir, and env vars in command line args on Windows.

• extra – extra keyword arguments are forwarded to the context constructor. See Context for more information.

Changed in version 8.0.1: Added the windows_expand_args parameter to allow disabling command line arg expansion on Windows.

Changed in version 8.0: When taking arguments from sys.argv on Windows, glob patterns, user dir, and env vars are expanded.

Changed in version 3.0: Added the standalone_mode parameter.

make_context(info_name: str | None, args: List[str], parent: Context | None = None, **extra: Any) → Context

This function when given an info name and arguments will kick off the parsing and create a new Context. It does not invoke the actual command callback though.

To quickly customize the context class used without overriding this method, set the context_class attribute.

Parameters:

• info_name – the info name for this invocation. Generally this is the most descriptive name for the script or command. For the toplevel script it’s usually the name of the script, for commands below it’s the name of the command.

• args – the arguments to parse as list of strings.

• parent – the parent context if available.

• extra – extra keyword arguments forwarded to the context constructor.

Changed in version 8.0: Added the context_class attribute.

make_parser(ctx: Context) → OptionParser

Creates the underlying option parser for this command.

parse_args(ctx: Context, args: Any) → list[str]

Given a context and a list of arguments this creates the parser and parses the arguments, then modifies the context as necessary. This is automatically invoked by make_context().

This function overrides click.Command.parse_args.

The call to _capture_args in this override stores the arguments (option names, option value, and argument values) that were used by the caller on the command line in the context object. These stored arugments can be used by the command function, e.g. to process options in the order they appeared on the command line (pipetask uses this feature to create pipeline actions in an order from different options).

Parameters:

ctxclick.core.Context

The current Context.ß

argslist [str]

The list of arguments from the command line, split at spaces but not at separators (like “=”).

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

Return a list of completions for the incomplete value. Looks at the names of options and chained multi-commands.

Parameters:

• ctx – Invocation context for this command.

• incomplete – Value being completed. May be empty.

New in version 8.0.

to_info_dict(ctx: Context) → Dict[str, Any]

Gather information that could be useful for a tool generating user-facing documentation. This traverses the entire structure below this command.

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

Parameters:

ctx – A Context representing this command.

New in version 8.0.