aiida.cmdline documentation

Baseclass

class aiida.cmdline.baseclass.VerdiCommand[source]

This command has no documentation yet.

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.VerdiCommandWithSubcommands[source]

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.

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.

Verdi lib

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]

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.

class aiida.cmdline.verdilib.CompletionCommand[source]

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.

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]

Describe a specific command

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

class aiida.cmdline.verdilib.Install[source]

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.

complete(subargs_idx, subargs)[source]

No completion after ‘verdi install’.

class aiida.cmdline.verdilib.ListParams[source]

List available commands

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

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

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

class aiida.cmdline.verdilib.Quicksetup[source]

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

class aiida.cmdline.verdilib.Run[source]

Execute an AiiDA script

class aiida.cmdline.verdilib.Setup[source]

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.

complete(subargs_idx, subargs)[source]

No completion after ‘verdi install’.

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

Daemon

class aiida.cmdline.commands.daemon.Daemon[source]

Manage the AiiDA daemon

This command allows to interact with the AiiDA daemon. Valid subcommands are:

  • start: start the daemon
  • stop: restart the daemon
  • restart: restart the aiida daemon, waiting for it to cleanly exit before restarting it.
  • status: inquire the status of the Daemon.
  • logshow: show the log in a continuous fashion, similar to the ‘tail -f’ command. Press CTRL+C to exit.
__init__()[source]

A dictionary with valid commands and functions to be called: start, stop, status and restart.

configure_user(*args)[source]

Configure the user that can run the daemon.

daemon_logshow(*args)[source]

Show the log of the daemon, press CTRL+C to quit.

daemon_restart(*args)[source]

Restart the daemon. Before restarting, wait for the daemon to really shut down.

daemon_start(*args)[source]

Start the daemon

daemon_status(*args)[source]

Print the status of the daemon

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

Stop the daemon.

Parameters:wait_for_death – If True, also verifies that the process was already killed. It attempts at most max_retries times, with sleep_between_retries seconds between one attempt and the following one (both variables are for the time being hardcoded in the function).
Returns:None if wait_for_death is False. True/False if the process was actually dead or after all the retries it was still alive.
get_daemon_pid()[source]

Return the daemon pid, as read from the celery.pid file. Return None if no pid is found (or the pid is not valid).

kill_daemon()[source]

This is the actual call that kills the daemon.

There are some print statements inside, but no sys.exit, so it is safe to be called from other parts of the code.

aiida.cmdline.commands.daemon.is_daemon_user()[source]

Return True if the user is the current daemon user, False otherwise.

Data

class aiida.cmdline.commands.data.Data[source]

Setup and manage data specific types

There is a list of subcommands for managing specific types of data. For instance, ‘data upf’ manages pseudopotentials in the UPF format.

__init__()[source]

A dictionary with valid commands and functions to be called.

class aiida.cmdline.commands.data.Depositable[source]

Provides shell completion for depositable data nodes.

Note

classes, inheriting Depositable, MUST NOT contain attributes, starting with _deposit_, which are not plugins for depositing.

deposit(*args)[source]

Deposit the data node to a given database.

Parameters:args – a namespace with parsed command line parameters.
get_deposit_plugins()[source]

Get the list of all implemented deposition methods for data class.

class aiida.cmdline.commands.data.Exportable[source]

Provides shell completion for exportable data nodes.

Note

classes, inheriting Exportable, MUST NOT contain attributes, starting with _export_, which are not plugins for exporting.

append_export_cmdline_arguments(parser)[source]

Function (to be overloaded in a subclass) to add custom export command line arguments.

Parameters:parser – a ArgParse parser object
Returns:change the parser in place
export(*args)[source]

Export the data node to a given format.

get_export_plugins()[source]

Get the list of all implemented exporters for data class.

print_or_store(node, output_fname, fileformat, other_args={}, overwrite=False)[source]

Depending on the parameters, either print the (single) output file on screen, or stores the file(s) on disk.

Parameters:
  • node – the Data node to print or store on disk
  • output_fname – The filename to store the main file. If empty or None, print instead
  • fileformat – a string to pass to the _exportstring method
  • other_args – a dictionary with additional kwargs to pass to _exportstring
  • overwrite – if False, stops if any file already exists (when output_fname is not empty
Note:

this function calls directly sys.exit(1) when an error occurs (or e.g. if check_overwrite is True and a file already exists).

class aiida.cmdline.commands.data.Importable[source]

Provides shell completion for importable data nodes.

Note

classes, inheriting Importable, MUST NOT contain attributes, starting with _import_, which are not plugins for importing.

get_import_plugins()[source]

Get the list of all implemented importers for data class.

class aiida.cmdline.commands.data.Listable[source]

Provides shell completion for listable data nodes.

Note

classes, inheriting Listable, MUST define value for property dataclass (preferably in __init__), which has to point to correct *Data class.

append_list_cmdline_arguments(parser)[source]

Append additional command line parameters, that are later parsed and used in the query construction.

Parameters:parser – instance of argparse.ArgumentParser
get_column_names()[source]

Return the list with column names.

Note

neither the number nor correspondence of column names and actual columns in the output from the query() are checked.

list(*args)[source]

List all instances of given data class.

Parameters:args – a list of command line arguments.
query(args)[source]

Perform the query and return information for the list.

Parameters:args – a namespace with parsed command line parameters.
Returns:table (list of lists) with information, describing nodes. Each row describes a single hit.
query_group(q_object, args)[source]

Subselect to filter data nodes by their group.

Parameters:
  • q_object – a query object
  • args – a namespace with parsed command line parameters.
query_group_qb(filters, args)[source]

Subselect to filter data nodes by their group.

Parameters:
  • q_object – a query object
  • args – a namespace with parsed command line parameters.
query_past_days(q_object, args)[source]

Subselect to filter data nodes by their age.

Parameters:
  • q_object – a query object
  • args – a namespace with parsed command line parameters.
query_past_days_qb(filters, args)[source]

Subselect to filter data nodes by their age.

Parameters:
  • filters – the filters to be enriched.
  • args – a namespace with parsed command line parameters.
class aiida.cmdline.commands.data.Visualizable[source]

Provides shell completion for visualizable data nodes.

Note

classes, inheriting Visualizable, MUST NOT contain attributes, starting with _show_, which are not plugins for visualization.

In order to specify a default visualization format, one has to override _default_show_format property (preferably in __init__), setting it to the name of default visualization tool.

get_show_plugins()[source]

Get the list of all implemented plugins for visualizing the structure.

show(*args)[source]

Show the data node with a visualization program.