Module with pre-defined reusable commandline options that can be used as click decorators.
aiida.cmdline.params.options.
graph_traversal_rules
Apply the graph traversal rule options to the command.
aiida.cmdline.params.options.conditional.
ConditionalOption
Bases: click.core.Option
click.core.Option
This cli option takes an additional callable parameter and uses that to determine wether a MissingParam should be raised if the option is not given on the cli.
The callable takes the context as an argument and can look up any amount of other parameter values etc.
required_fn – callable(ctx) -> True | False, returns True if the parameter is required to have a value. This is typically used when the condition depends on other parameters specified on the command line.
__init__
Initialize self. See help(type(self)) for accurate signature.
__module__
full_process_value
is_required
runs the given check on the context to determine requiredness
aiida.cmdline.params.options.config.
ConfigFileOption
Bases: aiida.cmdline.params.options.overridable.OverridableOption
aiida.cmdline.params.options.overridable.OverridableOption
Wrapper around click_config_file.configuration_option that increases reusability.
Example:
CONFIG_FILE = ConfigFileOption('--config', help='A configuration file') @click.command() @click.option('computer_name') @CONFIG_FILE(help='Configuration file for computer_setup') def computer_setup(computer_name): click.echo(f"Setting up computer {computername}") computer_setup --config config.yml
with config.yml:
--- computer_name: computer1
__call__
Override the stored kwargs, (ignoring args as we do not allow option name changes) and return the option.
kwargs – keyword arguments that will override those set in the construction
click_config_file.configuration_option constructed with args and kwargs defined during construction and call of this instance
Store the default args and kwargs.
args – default arguments to be used for the option
kwargs – default keyword arguments to be used that can be overridden in the call
yaml_config_file_provider
Read yaml config file from file handle.
aiida.cmdline.params.options.contextualdefault.
ContextualDefaultOption
A class that extends click.Option allowing to define a default callable that also get the context ctx as a parameter.
get_default
If a contextual default is defined, use it, otherwise behave normally.
aiida.cmdline.params.options.interactive.
InteractiveOption
Bases: aiida.cmdline.params.options.conditional.ConditionalOption
aiida.cmdline.params.options.conditional.ConditionalOption
Prompts for input, intercepting certain keyword arguments to replace click’s prompting behaviour with a more feature-rich one.
click
Note
This class has a parameter required_fn that can be passed to its __init__ (inherited from the superclass ConditionalOption) and a prompt_fn.
required_fn
prompt_fn
required_fn is about “is this parameter required” depending on the value of other params.
prompt_fn is about “should I prompt for this value if in interactive mode” and only makes sense in this class and not in ConditionalOption.
In most usecases, if I have a prompt_fn, then I would like to have also (the same) required_fn. The implementation still makes them independent for usecases where they might be different functions (e.g. if the variable is anyway not required, but you want to decide whether to prompt for it or not).
Usage:
import click @click.command() @click.option('label', prompt='Label', cls=InteractiveOption) def foo(label): click.echo(f'Labeling with label: {label}')
CHARACTER_IGNORE_DEFAULT
CHARACTER_PROMPT_HELP
PROMPT_COLOR
param_decls – relayed to click.Option
click.Option
switch – sequence of parameter
prompt_fn – callable(ctx) -> True | False, returns True if the option should be prompted for in interactive mode.
contextual_default – An optional callback function to get a default which is passed the click context
_get_default
provides the functionality of click.Option.get_default()
click.Option.get_default()
after_callback
If a callback was registered on init, call it and return it’s value.
ctrl_help
control behaviour when help is requested from the prompt
custom_value_proc
Custom value_proc function for the click.prompt which it will call to do value conversion.
Simply return the value, because we want to take care of value conversion ourselves in the simple_prompt_loop. If we let click.prompt do it, it will raise an exception when the user passes a control character, like the question mark, to bring up the help message and the type of the option is not a string, causing conversion to fail.
format_help_message
format the message to be displayed for in-prompt help.
gives a list of possibilities for parameter types that support completion
catch errors raised by ConditionalOption in order to adress them in the callback
disable click from circumventing prompting when a default value exists
is_non_interactive
Return whether the command is being run non-interactively.
This is the case if the non_interactive parameter in the context is set to True.
boolean, True if being run non-interactively, False otherwise
prompt_callback
decide wether to initiate the prompt_loop or not
prompt_func
prompt function with args set
safely_convert
convert without raising, instead print a message if fails
Tuple of ( success (bool), converted value )
simple_prompt_loop
Prompt until successful conversion. dispatch control sequences.
TemplateInteractiveOption
Bases: aiida.cmdline.params.options.interactive.InteractiveOption
aiida.cmdline.params.options.interactive.InteractiveOption
Sub class of InteractiveOption that uses template file for input instead of simple inline prompt.
This is useful for options that need to be able to specify multiline string values.
Define the configuration for the multiline template in the keyword arguments.
template – name of the template to use from the aiida.cmdline.templates directory. Default is the ‘multiline.tpl’ template.
aiida.cmdline.templates
header – string to put in the header of the template.
footer – string to put in the footer of the template.
extension – file extension to give to the template file.
Replace the basic prompt with a method that opens a template file in an editor.
opt_prompter
Prompt interactively for the value of an option of the command with context ctx.
ctx
Used to produce more complex behaviours than can be achieved with InteractiveOption alone.
Module to define multi value options for click.
aiida.cmdline.params.options.multivalue.
MultipleValueOption
An option that can handle multiple values with a single flag. For example:
@click.option('-n', '--nodes', cls=MultipleValueOption)
Will be able to parse the following:
--nodes 10 15 12
This is better than the builtin multiple=True keyword for click’s option which forces the user to specify the option flag for each value, which gets impractical for long lists of values
multiple=True
add_to_parser
Override built in click method that allows us to specify a custom parser to eat up parameters until the following flag or ‘endopt’ (i.e. –)
collect_usage_pieces
Returns all the pieces that go into the usage line and returns it as a list of strings.
aiida.cmdline.params.options.overridable.
OverridableOption
Bases: object
object
Wrapper around click option that increases reusability
Click options are reusable already but sometimes it can improve the user interface to for example customize a help message for an option on a per-command basis. Sometimes the option should be prompted for if it is not given On some commands an option might take any folder path, while on another the path only has to exist.
Overridable options store the arguments to click.option and only instantiate the click.Option on call, kwargs given to __call__ override the stored ones.
FOLDER = OverridableOption('--folder', type=click.Path(file_okay=False), help='A folder') @click.command() @FOLDER(help='A folder, will be created if it does not exist') def ls_or_create(folder): click.echo(os.listdir(folder)) @click.command() @FOLDER(help='An existing folder', type=click.Path(exists=True, file_okay=False, readable=True) def ls(folder) click.echo(os.listdir(folder))
click option constructed with args and kwargs defined during construction and call of this instance
__dict__
args – default arguments to be used for the click option
__slotnames__
__weakref__
list of weak references to the object (if defined)
clone
Create a new instance of the OverridableOption by cloning it and updating the stored kwargs with those passed.
This can be useful when an already predefined OverridableOption needs to be further specified and reused by a set of sub commands. Example:
LABEL = OverridableOption('-l', '--label', required=False, help='The label of the node' LABEL_COMPUTER = LABEL.clone(required=True, help='The label of the computer')
If multiple computer related sub commands need the LABEL option, but the default help string and required attribute need to be different, the clone method allows to override these and create a new OverridableOption instance that can then be used as a decorator.
kwargs – keyword arguments to update
OverridableOption instance with stored keyword arguments updated