aiida.cmdline.params.options package

Module with pre-defined reusable commandline options that can be used as click decorators.

aiida.cmdline.params.options.graph_traversal_rules(rules)[source]

Apply the graph traversal rule options to the command.

Submodules

class aiida.cmdline.params.options.conditional.ConditionalOption(param_decls=None, required_fn=None, **kwargs)[source]

Bases: 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.

Parameters

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__(param_decls=None, required_fn=None, **kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'aiida.cmdline.params.options.conditional'
full_process_value(ctx, value)[source]
is_required(ctx)[source]

runs the given check on the context to determine requiredness

class aiida.cmdline.params.options.config.ConfigFileOption(*args, **kwargs)[source]

Bases: 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__(**kwargs)[source]

Override the stored kwargs, (ignoring args as we do not allow option name changes) and return the option.

Parameters

kwargs – keyword arguments that will override those set in the construction

Returns

click_config_file.configuration_option constructed with args and kwargs defined during construction and call of this instance

__init__(*args, **kwargs)[source]

Store the default args and kwargs.

Parameters
  • args – default arguments to be used for the option

  • kwargs – default keyword arguments to be used that can be overridden in the call

__module__ = 'aiida.cmdline.params.options.config'
aiida.cmdline.params.options.config.yaml_config_file_provider(handle, cmd_name)[source]

Read yaml config file from file handle.

class aiida.cmdline.params.options.contextualdefault.ContextualDefaultOption(*args, contextual_default=None, **kwargs)[source]

Bases: click.core.Option

A class that extends click.Option allowing to define a default callable that also get the context ctx as a parameter.

__init__(*args, contextual_default=None, **kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'aiida.cmdline.params.options.contextualdefault'
get_default(ctx)[source]

If a contextual default is defined, use it, otherwise behave normally.

class aiida.cmdline.params.options.interactive.InteractiveOption(param_decls=None, switch=None, prompt_fn=None, contextual_default=None, **kwargs)[source]

Bases: 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.

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 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 = 'yellow'
__init__(param_decls=None, switch=None, prompt_fn=None, contextual_default=None, **kwargs)[source]
Parameters
  • param_decls – relayed to 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

__module__ = 'aiida.cmdline.params.options.interactive'
_get_default(ctx)[source]

provides the functionality of click.Option.get_default()

after_callback(ctx, param, value)[source]

If a callback was registered on init, call it and return it’s value.

ctrl_help()[source]

control behaviour when help is requested from the prompt

static custom_value_proc(value)[source]

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()[source]

format the message to be displayed for in-prompt help.

gives a list of possibilities for parameter types that support completion

full_process_value(ctx, value)[source]

catch errors raised by ConditionalOption in order to adress them in the callback

get_default(ctx)[source]

disable click from circumventing prompting when a default value exists

static is_non_interactive(ctx)[source]

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.

Returns

boolean, True if being run non-interactively, False otherwise

prompt_callback(ctx, param, value)[source]

decide wether to initiate the prompt_loop or not

prompt_func(ctx)[source]

prompt function with args set

safely_convert(value, param, ctx)[source]

convert without raising, instead print a message if fails

Returns

Tuple of ( success (bool), converted value )

simple_prompt_loop(ctx, param, value)[source]

Prompt until successful conversion. dispatch control sequences.

class aiida.cmdline.params.options.interactive.TemplateInteractiveOption(param_decls=None, **kwargs)[source]

Bases: 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.

__init__(param_decls=None, **kwargs)[source]

Define the configuration for the multiline template in the keyword arguments.

Parameters
  • template – name of the template to use from the aiida.cmdline.templates directory. Default is the ‘multiline.tpl’ template.

  • 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.

__module__ = 'aiida.cmdline.params.options.interactive'
prompt_func(ctx)[source]

Replace the basic prompt with a method that opens a template file in an editor.

aiida.cmdline.params.options.interactive.opt_prompter(ctx, cmd, givenkwargs, oldvalues=None)[source]

Prompt interactively for the value of an option of the command with context ctx.

Used to produce more complex behaviours than can be achieved with InteractiveOption alone.

Module to define multi value options for click.

class aiida.cmdline.params.options.multivalue.MultipleValueOption(*args, **kwargs)[source]

Bases: click.core.Option

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

__init__(*args, **kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'aiida.cmdline.params.options.multivalue'
add_to_parser(parser, ctx)[source]

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. –)

aiida.cmdline.params.options.multivalue.collect_usage_pieces(self, ctx)[source]

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

class aiida.cmdline.params.options.overridable.OverridableOption(*args, **kwargs)[source]

Bases: 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.

Example:

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))
__call__(**kwargs)[source]

Override the stored kwargs, (ignoring args as we do not allow option name changes) and return the option.

Parameters

kwargs – keyword arguments that will override those set in the construction

Returns

click option constructed with args and kwargs defined during construction and call of this instance

__dict__ = mappingproxy({'__module__': 'aiida.cmdline.params.options.overridable', '__doc__': "\n Wrapper around click option that increases reusability\n\n Click options are reusable already but sometimes it can improve the user interface to for example customize a\n help message for an option on a per-command basis. Sometimes the option should be prompted for if it is not given\n On some commands an option might take any folder path, while on another the path only has to exist.\n\n Overridable options store the arguments to click.option and only instantiate the click.Option on call,\n kwargs given to ``__call__`` override the stored ones.\n\n Example::\n\n FOLDER = OverridableOption('--folder', type=click.Path(file_okay=False), help='A folder')\n\n @click.command()\n @FOLDER(help='A folder, will be created if it does not exist')\n def ls_or_create(folder):\n click.echo(os.listdir(folder))\n\n @click.command()\n @FOLDER(help='An existing folder', type=click.Path(exists=True, file_okay=False, readable=True)\n def ls(folder)\n click.echo(os.listdir(folder))\n ", '__init__': <function OverridableOption.__init__>, '__call__': <function OverridableOption.__call__>, 'clone': <function OverridableOption.clone>, '__dict__': <attribute '__dict__' of 'OverridableOption' objects>, '__weakref__': <attribute '__weakref__' of 'OverridableOption' objects>, '__slotnames__': []})
__init__(*args, **kwargs)[source]

Store the default args and kwargs.

Parameters
  • args – default arguments to be used for the click option

  • kwargs – default keyword arguments to be used that can be overridden in the call

__module__ = 'aiida.cmdline.params.options.overridable'
__slotnames__ = []
__weakref__

list of weak references to the object (if defined)

clone(**kwargs)[source]

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.

Parameters

kwargs – keyword arguments to update

Returns

OverridableOption instance with stored keyword arguments updated