aiida.cmdline package

aiida.cmdline._print_dictionary_json_date(dictionary)[source]

Print a dictionary using the json format (with indent=2), and converting dates to strings.

aiida.cmdline.delayed_load_node(*args, **kwargs)[source]

Call the aiida.orm.load_node, but import the module only at the first execution. This is needed in the command line, because an import would “freeze” the imported modules to the BACKEND currently set (and when ‘verdi’ starts to run, this has not been fixed yet).

Note:

either import load_node AFTER the load_dbenv call, inside each function, or if you want to import it only once for convenience reasons, import this function:

from aiida.cmdline import delayed_load_node as load_node
aiida.cmdline.delayed_load_workflow(*args, **kwargs)[source]

Same as aiida.cmdline.delayed_load_node. This method is needed in the command line in order not to “freeze” what is imported to a specific backend.

aiida.cmdline.pass_to_django_manage(argv, profile=None)[source]

Call the corresponding django manage.py command

aiida.cmdline.print_dictionary(dictionary, format)[source]
aiida.cmdline.wait_for_confirmation(valid_positive=('Y', 'y'), valid_negative=('N', 'n'), print_to_stderr=True, catch_ctrl_c=True)[source]

Wait for confirmation, until a valid confirmation is given. If the confirmation is not valid, keep asking.

Parameters:
  • valid_positive – a list of strings with all possible valid positive confirmations.
  • valid_negative – a list of strings with all possible valid negative confirmations.
  • print_to_stderr – If True, print messages to stderr, otherwise to stdout
  • catch_ctrl_c – If True, a CTRL+C command is catched and interpreted as a negative response. If False, CTRL+C is not catched.
Returns:

True if the reply was positive, False if it was negative.

Submodules

class aiida.cmdline.baseclass.VerdiCommand[source]

Bases: object

This command has no documentation yet.

__dict__ = dict_proxy({'_abstract': True, 'get_full_command_name': <function get_full_command_name>, '__module__': 'aiida.cmdline.baseclass', '__metaclass__': <class 'aiida.cmdline.baseclass.__metaclass__'>, 'complete': <function complete>, 'get_command_name': <classmethod object>, '_custom_command_name': None, '__dict__': <attribute '__dict__' of 'VerdiCommand' objects>, 'run': <function run>, '__weakref__': <attribute '__weakref__' of 'VerdiCommand' objects>, '__doc__': '\n This command has no documentation yet.\n '})
class __metaclass__[source]

Bases: type

Some python black magic to set correctly the logger also in subclasses.

__module__ = 'aiida.cmdline.baseclass'
static __new__(name, bases, attrs)[source]
__module__ = 'aiida.cmdline.baseclass'
__weakref__

list of weak references to the object (if defined)

_abstract = True
_custom_command_name = None
complete(subargs_idx, subargs)[source]

Method called when the user asks for the bash completion. Print a list of valid keywords. Returning without printing will use standard bash completion.

Parameters:
  • subargs_idx – the index of the subargs where the TAB key was pressed (0 is the first element of subargs)
  • subargs – a list of subarguments to this command
classmethod get_command_name()[source]

Return the name of the verdi command associated to this class. By default, the lower-case version of the class name.

get_full_command_name(with_exec_name=True)[source]

Return the current command name. Also tries to get the subcommand name.

Parameters:with_exec_name – if True, return the full string, including the executable name (‘verdi’). If False, omit it.
run(*args)[source]

Method executed when the command is called from the command line.

class aiida.cmdline.baseclass.VerdiCommandRouter[source]

Bases: aiida.cmdline.baseclass.VerdiCommand

__module__ = 'aiida.cmdline.baseclass'
_abstract = True
complete(subargs_idx, subargs)[source]

Relay tab-completion requests to subcommand complete functions.

Click-implemented commands (filtered by isinstance check) pose a special case. Here we use aiida.cmdline.commands.click_subcmd_complete to create a completion function on the fly, leveraging click functionality. Since VerdiCommands with click subcommands must actually rout to the root (aiida.cmdline.commands.verdi) for each subcommand, we have only access to the root as a python object through routed_subcommands, Not to the active subcommand. This means we must follow the chain up through cli parameters. Since this function is only passed subargs, we need to use sys.argv.

sys.argv in this case follows the signature of verdi completion:

verdi completion <num_subargs> verdi [<subgroup>, ...] <subcommand> ([<subcmd param>, ...] | '')

Therefore we can disregard the first four and the last element of argv and loop through sys.argv[4:len(sys.argv)-1], for each determine wether it’s a subcommand, if so, retrieve it’s python object until we find the last subcommand, for which we then build the completion function. We can safely disregard the last one, because it is never a (complete) subcommand and it will be passed to the completion function we build in any case (as part of subargs).

invalid_subcommand(*args)[source]
no_subcommand(*args)[source]
routed_subcommands = {}
run(*args)[source]

Method executed when the command is called from the command line.

class aiida.cmdline.baseclass.VerdiCommandWithSubcommands[source]

Bases: aiida.cmdline.baseclass.VerdiCommand

Used for commands with subcommands. Just define, in the __init__, the self.valid_subcommands dictionary, in the format:

self.valid_subcommands = {
    'uploadfamily': (self.uploadfamily, self.complete_auto),
    'listfamilies': (self.listfamilies, self.complete_none),
    }

where the key is the subcommand name to give on the command line, and the value is a tuple of length 2, the first is the function to call on execution, the second is the function to call on complete.

This class already defined the complete_auto and complete_none commands, that respectively call the default bash completion for filenames/folders, or do not give any completion suggestion. Other functions can of course be defined.

Todo

Improve the docstrings for commands with subcommands.

__module__ = 'aiida.cmdline.baseclass'
_abstract = True
complete(subargs_idx, subargs)[source]

Method called when the user asks for the bash completion. Print a list of valid keywords. Returning without printing will use standard bash completion.

Parameters:
  • subargs_idx – the index of the subargs where the TAB key was pressed (0 is the first element of subargs)
  • subargs – a list of subarguments to this command
complete_auto(subargs_idx, subargs)[source]
complete_none(subargs_idx, subargs)[source]
get_full_command_name(*args, **kwargs)[source]

Return the current command name. Also tries to get the subcommand name.

Also tries to see if the caller function was one specific submethod.

Parameters:with_exec_name – if True, return the full string, including the executable name (‘verdi’). If False, omit it.
invalid_subcommand(*args)[source]
no_subcommand(*args)[source]
run(*args)[source]

Method executed when the command is called from the command line.

valid_subcommands = {}
aiida.cmdline.common.print_node_info(node, print_summary=True)[source]
aiida.cmdline.common.print_node_summary(node)[source]

Load the dbenv lazily, especially useful in commandline commands

Always avoids trying to load the dbenv twice. When it has to be loaded, a spinner ASCII widget is displayed.

Provides:
  • with_dbenv, a decorator to frontload the dbenv for functions
  • dbenv, a contextmanager to load the dbenv only if a specific
    code branch gets visited and possibly avoiding the overhead if not
aiida.cmdline.dbenv_lazyloading.dbenv(*args, **kwds)[source]

Loads the dbenv for a specific region of code, does not unload afterwards

Only use when it makes it possible to avoid loading the dbenv for certain code paths

Good Example:

# do this
@click.command()
@click.option('--with-db', is_flag=True)
def profile_info(with_db):
    # read the config file
    click.echo(profile_config)

    # load the db only if necessary
    if with_db:
        with dbenv():
            # gather db statistics for the profile
            click.echo(db_statistics)

This will run very fast without the –with-db flag and slow only if database info is requested

Do not use if you will end up loading the dbenv anyway

Bad Example:

# don't do this
def my_function():
    with dbenv():
        # read from db

    # do db unrelated stuff
aiida.cmdline.dbenv_lazyloading.load_dbenv_if_not_loaded(**kwargs)[source]

load dbenv if necessary, run spinner meanwhile to show command hasn’t crashed

aiida.cmdline.dbenv_lazyloading.with_dbenv(function)[source]

Function decorator that loads the dbenv if necessary before running the function

Example:

@with_dbenv
def create_my_calculation():
    from aiida.orm import CalculationFactory  # note the local import
    my_calc = CalculationFactory('mycalc.mycalc')

Command line commands for the main executable ‘verdi’ of aiida

If you want to define a new command line parameter, just define a new class inheriting from VerdiCommand, and define a run(self,*args) method accepting a variable-length number of parameters args (the command-line parameters), which will be invoked when this executable is called as verdi NAME

Don’t forget to add the docstring to the class: the first line will be the short description, the following ones the long description.

class aiida.cmdline.verdilib.Completion[source]

Bases: aiida.cmdline.baseclass.VerdiCommand

Manage bash completion

Return a list of available commands, separated by spaces. Calls the correct function of the command if the TAB has been pressed after the first command.

Returning without printing will use the default bash completion.

__module__ = 'aiida.cmdline.verdilib'
_abstract = False
run(*args)[source]

Method executed when the command is called from the command line.

class aiida.cmdline.verdilib.CompletionCommand[source]

Bases: aiida.cmdline.baseclass.VerdiCommand

Return the bash completion function to put in ~/.bashrc

This command prints on screen the function to be inserted in your .bashrc command. You can copy and paste the output, or simply add eval “verdi completioncommand” to your .bashrc, AFTER having added the aiida/bin directory to the path.

__module__ = 'aiida.cmdline.verdilib'
_abstract = False
complete(subargs_idx, subargs)[source]

Method called when the user asks for the bash completion. Print a list of valid keywords. Returning without printing will use standard bash completion.

Parameters:
  • subargs_idx – the index of the subargs where the TAB key was pressed (0 is the first element of subargs)
  • subargs – a list of subarguments to this command
run(*args)[source]

I put the documentation here, and I don’t print it, so we don’t clutter too much the .bashrc.

  • “${THE_WORDS[@]}” (with the @) puts each element as a different parameter; note that the variable expansion etc. is performed
  • I add a ‘x’ at the end and then remove it; in this way, $( ) will not remove trailing spaces
  • If the completion command did not print anything, we use the default bash completion for filenames
  • If instead the code prints something empty, thanks to the workaround above $OUTPUT is not empty, so we do go the the ‘else’ case and then, no substitution is suggested.
class aiida.cmdline.verdilib.Help[source]

Bases: aiida.cmdline.baseclass.VerdiCommand

Describe a specific command

Pass a further argument to get a description of a given command.

__module__ = 'aiida.cmdline.verdilib'
_abstract = False
complete(subargs_idx, subargs)[source]

Method called when the user asks for the bash completion. Print a list of valid keywords. Returning without printing will use standard bash completion.

Parameters:
  • subargs_idx – the index of the subargs where the TAB key was pressed (0 is the first element of subargs)
  • subargs – a list of subarguments to this command
run(*args)[source]

Method executed when the command is called from the command line.

class aiida.cmdline.verdilib.Install[source]

Bases: aiida.cmdline.baseclass.VerdiCommand

Install/setup aiida for the current user

This command creates the ~/.aiida folder in the home directory of the user, interactively asks for the database settings and the repository location, does a setup of the daemon and runs a migrate command to create/setup the database.

__module__ = 'aiida.cmdline.verdilib'
_abstract = False
complete(subargs_idx, subargs)[source]

No completion after ‘verdi install’.

run(*args)[source]

Method executed when the command is called from the command line.

class aiida.cmdline.verdilib.ListParams[source]

Bases: aiida.cmdline.baseclass.VerdiCommand

List available commands

List available commands and their short description. For the long description, use the ‘help’ command.

__module__ = 'aiida.cmdline.verdilib'
_abstract = False
run(*args)[source]

Method executed when the command is called from the command line.

exception aiida.cmdline.verdilib.ProfileParsingException(*args, **kwargs)[source]

Bases: aiida.common.exceptions.AiidaException

Exception raised when parsing the profile command line option, if only -p is provided, and no profile is specified

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

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'aiida.cmdline.verdilib'
class aiida.cmdline.verdilib.Quicksetup[source]

Bases: aiida.cmdline.baseclass.VerdiCommand

Quick setup for the most common usecase (1 user, 1 machine).

Creates a database user ‘aiida_qs_<login-name>’ with random password (if it doesn’t exist). Creates a database ‘<profile>_<username>’ (if it exists, prompts user to use or change the name).

BACKEND_DJANGO = 'django'
BACKEND_SQLA = 'sqlalchemy'
__module__ = 'aiida.cmdline.verdilib'
_abstract = False
static _ctx(info_name='verdi quicksetup', **kwargs)[source]
run(*args)[source]

Method executed when the command is called from the command line.

class aiida.cmdline.verdilib.Run[source]

Bases: aiida.cmdline.baseclass.VerdiCommand

Execute an AiiDA script

__module__ = 'aiida.cmdline.verdilib'
_abstract = False
run(*args)[source]

Method executed when the command is called from the command line.

class aiida.cmdline.verdilib.Setup[source]

Bases: aiida.cmdline.baseclass.VerdiCommand

Setup aiida for the current user

This command creates the ~/.aiida folder in the home directory of the user, interactively asks for the database settings and the repository location, does a setup of the daemon and runs a migrate command to create/setup the database.

__module__ = 'aiida.cmdline.verdilib'
_abstract = False
static _ctx(info_name='verdi setup', **kwargs)[source]
complete(subargs_idx, subargs)[source]

No completion after ‘verdi install’.

run(*args)[source]

Method executed when the command is called from the command line.

aiida.cmdline.verdilib._check_db_name(dbname, postgres)[source]

looks up if a database with the name exists, prompts for using or creating a differently named one

aiida.cmdline.verdilib.exec_from_cmdline(argv)[source]

The main function to be called. Pass as parameter the sys.argv.

aiida.cmdline.verdilib.get_command_suggestion(command)[source]

A function that prints on stderr a list of similar commands

aiida.cmdline.verdilib.get_listparams()[source]

Return a string with the list of parameters, to be printed

The advantage of this function is that the calling routine can choose to print it on stdout or stderr, depending on the needs.

aiida.cmdline.verdilib.parse_profile(argv, merge_equal=False)[source]

Parse the argv to see if a profile has been specified, return it with the command position shift (index where the commands start)

Parameters:merge_equal – if True, merge things like (‘verdi’, ‘–profile’, ‘=’, ‘x’, ‘y’) to (‘verdi’, ‘–profile=x’, ‘y’) but then return the correct index for the original array.
Raises:ProfileParsingException – if there is only ‘verdi’ specified, or if only ‘verdi -p’ (in these cases, one has respectively exception.minus_p_provided equal to False or True)
aiida.cmdline.verdilib.print_usage(execname)[source]
aiida.cmdline.verdilib.run()[source]
aiida.cmdline.verdilib.setup(profile, only_config, non_interactive=False, **kwargs)[source]

setup an aiida profile and aiida user (and the aiida default user).

Parameters:
  • profile – Profile name
  • only_config – do not create a new user
  • non_interactive – do not prompt for configuration values, fail if not all values are given as kwargs.
  • backend – one of ‘django’, ‘sqlalchemy’
  • email – valid email address for the user
  • db_host – hostname for the database
  • db_port – port to connect to the database
  • db_user – name of the db user
  • db_pass – password of the db user
aiida.cmdline.verdilib.update_environment(*args, **kwds)[source]

Used as a context manager, changes sys.argv with the new_argv argument, and restores it upon exit.