ButlerCLI¶
- class lsst.daf.butler.cli.butler.ButlerCLI(*args: Any, **kwargs: Any)¶
Bases:
LoaderCLI
Specialized command loader implementing the
butler
command.Attributes Summary
the default for the
Context.allow_extra_args
flag.the default for the
Context.allow_interspersed_args
flag.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_commands
(ctx, formatter)Extra format methods for multi methods that adds all the commands after the options.
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 the commands offered by the local package.
Get the list of importable yaml files that contain cli data for this command.
get_command
(ctx, name)Get a single command for execution.
get_help
(ctx)Formats the help into a string and returns it.
get_help_option
(ctx)Returns the help option object.
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.
list_commands
(ctx)Get all the commands that can be called by the butler command, it is used to generate the --help output.
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.
resolve_command
(ctx, args)result_callback
([replace])Adds a result callback to the command.
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 = True¶
the default for the
Context.allow_extra_args
flag.
- allow_interspersed_args = False¶
the default for the
Context.allow_interspersed_args
flag.
- ignore_unknown_options = False¶
the default for the
Context.ignore_unknown_options
flag.
- localCmdPkg = 'lsst.daf.butler.cli.cmd'¶
- pluginEnvVar = 'DAF_BUTLER_PLUGINS'¶
Methods Documentation
- 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_commands(ctx: Context, formatter: HelpFormatter) None ¶
Extra format methods for multi methods that adds all the commands after the options.
- 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_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()
.
- getLocalCommands() defaultdict[str, list[str]] ¶
Get the commands offered by the local package. This assumes that the commands can be found in
localCmdPkg.__all__
, if this is not the case then this function should be overridden.
- classmethod getPluginList() list[str] ¶
Get the list of importable yaml files that contain cli data for this command.
- get_command(ctx: Context, name: str) Command | None ¶
Get a single command for execution.
Used by Click.
- Parameters:
- ctx
click.Context
The current Click context.
- name
str
The name of the command to return.
- ctx
- Returns:
- command
click.Command
A Command that wraps a callable command function.
- command
- get_help(ctx: Context) str ¶
Formats the help into a string and returns it.
Calls
format_help()
internally.
- 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.
- list_commands(ctx: Context) list[str] ¶
Get all the commands that can be called by the butler command, it is used to generate the –help output.
Used by Click.
- 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 ofinvoke()
.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: List[str]) 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()
.
- result_callback(replace: bool = False) Callable[[F], F] ¶
Adds a result callback to the command. By default if a result callback is already registered this will chain them but this can be disabled with the
replace
parameter. The result callback is invoked with the return value of the subcommand (or the list of return values from all subcommands if chaining is enabled) as well as the parameters as they would be passed to the main callback.Example:
@click.group() @click.option('-i', '--input', default=23) def cli(input): return 42 @cli.result_callback() def process_result(result, input): return result + input
- Parameters:
replace – if set to
True
an already existing result callback will be removed.
Changed in version 8.0: Renamed from
resultcallback
.New in version 3.0.
- shell_complete(ctx: Context, incomplete: str) List[CompletionItem] ¶
Return a list of completions for the incomplete value. Looks at the names of options, subcommands, 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.