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.
-
-
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.
-
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).
Uses click for options. Creates a database user ‘aiida_qs_<username>’ with random password if it doesn’t exist. Creates a ‘aiidadb_qs_<username>’ database (prompts to use or change the name if already exists). Makes sure not to overwrite existing databases or profiles without prompting for confirmation.
-
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.
-
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
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.
-
daemon_restart
(*args)[source]¶ Restart the daemon. Before restarting, wait for the daemon to really shut down.
-
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, withsleep_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.
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.
-
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.
-
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
-
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.
-
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.
-
-
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.