Utility functions to draw ASCII diagrams to the command line.
aiida.cmdline.utils.ascii_vis.
draw_children
Print an ASCII tree of the parents of the given node.
Deprecated since version 1.1.0: Will be removed in v2.0.0.
node (aiida.orm.nodes.data.Data) – The node to draw for
aiida.orm.nodes.data.Data
node_label (str) – The label to use for the nodes
show_pk (bool) – Show the PK of nodes alongside the label
dist (int) – The number of steps away from this node to branch out
follow_links_of_type (str) – Follow links of this type when making steps, if None then it will follow CREATE and INPUT links
draw_parents
format_call_graph
Print a tree like the POSIX tree command for the calculation call graph
calc_node – The calculation node
info_fn – An optional function that takes the node and returns a string of information to be displayed for each node.
Common utility functions for command line commands.
aiida.cmdline.utils.common.
check_worker_load
Check if the percentage usage of the daemon worker slots exceeds a threshold. If it does, print a warning.
The purpose of this check is to warn the user if they are close to running out of worker slots which could lead to their processes becoming stuck indefinitely.
active_slots – the number of currently active worker slots
format_flat_links
Given a flat list of LinkTriples, return a flat string representation.
links – a list of LinkTriples
headers – headers to use
formatted string
format_local_time
Format a datetime object or UNIX timestamp in a human readable format
timestamp – a datetime object or a float representing a UNIX timestamp
format_str – optional string format to pass to strftime
format_nested_links
Given a nested dictionary of nodes, return a nested string representation.
links – a nested dictionary of nodes
nested formatted string
get_calcjob_report
Return a multi line string representation of the log messages and output of a given calcjob
calcjob – the calcjob node
a string representation of the log messages and scheduler output
get_env_with_venv_bin
Create a clone of the current running environment with the AIIDA_PATH variable set directory of the config.
get_node_info
Return a multi line string of information about the given node, such as the incoming and outcoming links.
include_summary – boolean, if True, also include a summary of node properties
a string summary of the node including a description of all its links and log messages
get_node_summary
Return a multi line string with a pretty formatted summary of a Node.
node – a Node instance
a string summary of the node
get_num_workers
Get the number of active daemon workers from the circus client
get_process_function_report
Return a multi line string representation of the log messages and output of a given process function node
node – the node
a string representation of the log messages
get_workchain_report
Return a multi line string representation of the log messages and output of a given workchain
node – the workchain node
a nested string representation of the log messages
print_last_process_state_change
Print the last time that a process of the specified type has changed its state. This function will also print a warning if the daemon is not running.
process_type – optional process type for which to get the latest state change timestamp. Valid process types are either ‘calculation’ or ‘work’.
print_process_info
Print detailed information about a process class and its process specification.
process – a Process class
Process
print_process_spec
Print the process spec in a human-readable formatted way.
process_spec – a ProcessSpec instance
Utility functions for command line commands related to the daemon.
aiida.cmdline.utils.daemon.
delete_stale_pid_file
Delete a potentially state daemon PID file.
Checks if the PID contatined in the circus PID file (circus-{PROFILE_NAME}.pid) matches a valid running verdi process. If it does not, the PID file is stale and will be removed.
This situation can arise if a system is shut down suddenly and so the process is killed but the PID file is not deleted in time. When the get_daemon_pid() method is called, an incorrect PID is returned. Alternatively, another process or the user may have meddled with the PID file in some way, corrupting it.
client – the DaemonClient
get_daemon_status
Print the status information of the daemon for a given profile through its DaemonClient
print_client_response_status
Print the response status of a call to the CircusClient through the DaemonClient
response – the response object
an integer error code; non-zero means there was an error (FAILED, TIMEOUT), zero means OK (OK, RUNNING)
Various decorators useful for creating verdi commands, for example loading the dbenv lazily.
Always avoids trying to load the dbenv twice. When it has to be loaded, a spinner ASCII widget is displayed.
with_dbenv, a decorator to frontload the dbenv for functions
code branch gets visited and possibly avoiding the overhead if not
aiida.cmdline.utils.decorators.
dbenv
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
only_if_daemon_running
Function decorator for CLI command to print critical error and exit automatically when daemon is not running.
The error printing and exit behavior can be controlled with the decorator keyword arguments. The default message that is printed can be overridden as well as the echo function that is to be used. By default it uses the aiida.cmdline.utils.echo.echo_critical function which automatically aborts the command. The function can be substituted by for example aiida.cmdline.utils.echo.echo_warning to instead print just a warning and continue.
Example:
@only_if_daemon_running(echo_function=echo.echo_warning, message='beware that the daemon is not running') def create_node(): pass
echo_function – echo function to issue the message, should be from aiida.cmdline.utils.echo
message – optional message to override the default message
with_dbenv
Function decorator that will load the database environment only when the function is called.
@with_dbenv() def create_node(): from aiida.orm import Int # note the local import node = Int(1).store()
Default values and lazy default get methods for command line options.
aiida.cmdline.utils.defaults.
get_default_profile
Try to get the name of the default profile.
This utility function should only be used for defaults or callbacks in command line interface parameters. Otherwise, the preference should go to calling get_config to load the actual config and using config.default_profile_name to get the default profile name.
click.UsageError – if the config could not be loaded or no default profile exists
the default profile name or None if no default is defined in the configuration
Convenience functions for printing output from verdi commands
aiida.cmdline.utils.echo.
echo
Print a normal message through click’s echo function to stdout
message – the string representing the message to print
bold – whether to print the message in bold
nl – whether to print a newline at the end of the message
err – whether to print to stderr
echo_critical
Print an error message through click’s echo function to stdout, prefixed with ‘Critical:’ and then calls sys.exit with the given exit_status.
This should be used to print messages for errors that cannot be recovered from and so the script should be directly terminated with a non-zero exit status to indicate that the command failed
echo_dictionary
Print the given dictionary to stdout in the given format
dictionary – the dictionary
fmt – the format to use for printing
sort_keys – Whether to automatically sort keys
echo_error
Print an error message through click’s echo function to stdout, prefixed with ‘Error:’
echo_highlight
Print a highlighted message to stdout
color – a color from COLORS
echo_info
Print an info message through click’s echo function to stdout, prefixed with ‘Info:’
echo_success
Print a success message through click’s echo function to stdout, prefixed with ‘Success:’
bold – whether to print the message in bold include a newline character
echo_warning
Print a warning message through click’s echo function to stdout, prefixed with ‘Warning:’
Utilities for getting multi line input from the commandline.
aiida.cmdline.utils.multi_line_input.
edit_comment
call up an editor to edit comments to nodes in the database
edit_multiline_template
Open a template file for editing in a text editor.
template – name of the template to use from the aiida.cmdline.templates directory.
aiida.cmdline.templates
comment_marker – the set of symbols that mark a comment line that should be stripped from the final value
extension – the file extension to give to the rendered template file.
kwargs – keywords that will be passed to the template rendering engine.
the final string value entered in the editor with all comment lines stripped or an empty string if the click.edit returned None.
click.edit
None
Plugin aware click command Group.
aiida.cmdline.utils.pluginable.
Pluginable
Bases: click.core.Group
click.core.Group
A click command group that finds and loads plugin commands lazily.
__init__
Initialize with entry point group.
__module__
get_command
Try to load a subcommand from entry points, else defer to super.
list_commands
Add entry point names of available plugins to the command list.
set_exclude_external_plugins
Set whether external plugins should be excluded.
If exclude_external_plugins is set to True, the plugins that belong to the entry_point_group defined for this click.Group will not be discoverable. This is useful to limit the available commands to only those provided by aiida-core (excluding those provided by plugins).
exclude_external_plugins – bool, when True, external plugins will not be discoverable
Utility functions for command line commands operating on the repository.
aiida.cmdline.utils.repository.
list_repository_contents
Print the contents of the directory path in the repository of the given node to stdout.
path – directory path
FileNotFoundError – if the path does not exist in the repository of the given node
Definition of modules that are to be automatically loaded for verdi shell.
aiida.cmdline.utils.shell.
_ipython
Start IPython >= 1.0
_ipython_pre_011
Start IPython pre-0.11
_ipython_pre_100
Start IPython pre-1.0.0
bpython
Start a bpython shell.
get_start_namespace
Load all default and custom modules
ipython
Start any version of IPython
run_shell
Start the chosen external shell.
Templates for input/output of verdi commands.