aiida.cmdline.utils package

Commandline utility functions.

Subpackages

• aiida.cmdline.utils.query package
  • Submodules

Submodules

Utility functions to draw ASCII diagrams to the command line.

aiida.cmdline.utils.ascii_vis.build_call_graph(calc_node, max_depth: int | None = None, call_link_label: bool = False, info_fn=<function calc_info>) → str

Build the call graph of a given node.

Parameters:

• calc_node – The calculation node

• max_depth – Maximum depth of the call graph to build. Use None for unlimited.

• call_link_label – Include the call link label if other from the default CALL.

• info_fn – An optional function that takes the node and returns a string of information to be displayed for each node.

aiida.cmdline.utils.ascii_vis.calc_info(node, call_link_label: bool = False) → str

Return a string with the summary of the state of a CalculationNode.

Parameters:

• calc_node – The calculation node

• call_link_label – Include the call link label if other from the default CALL.

aiida.cmdline.utils.ascii_vis.format_call_graph(calc_node, max_depth: int | None = None, call_link_label: bool = False, info_fn=<function calc_info>)

Print a tree like the POSIX tree command for the calculation call graph.

Parameters:

• calc_node – The calculation node

• max_depth – Maximum depth of the call graph to print

• call_link_label – Include the call link label if other from the default CALL.

• info_fn – An optional function that takes the node and returns a string of information to be displayed for each node.

aiida.cmdline.utils.ascii_vis.format_tree_descending(tree, prefix='', pos=-1)

Format a descending tree.

Common utility functions for command line commands.

aiida.cmdline.utils.common.format_flat_links(links, headers)

Given a flat list of LinkTriples, return a flat string representation.

Parameters:

• links – a list of LinkTriples

• headers – headers to use

Returns:

formatted string

aiida.cmdline.utils.common.format_local_time(timestamp, format_str='%Y-%m-%d %H:%M:%S')

Format a datetime object or UNIX timestamp in a human readable format

Parameters:

• timestamp – a datetime object or a float representing a UNIX timestamp

• format_str – optional string format to pass to strftime

aiida.cmdline.utils.common.format_nested_links(links, headers)

Given a nested dictionary of nodes, return a nested string representation.

Parameters:

• links – a nested dictionary of nodes

• headers – headers to use

Returns:

nested formatted string

aiida.cmdline.utils.common.get_calcjob_report(calcjob)

Return a multi line string representation of the log messages and output of a given calcjob

Parameters:

calcjob – the calcjob node

Returns:

a string representation of the log messages and scheduler output

aiida.cmdline.utils.common.get_env_with_venv_bin()

Create a clone of the current running environment with the AIIDA_PATH variable set directory of the config.

aiida.cmdline.utils.common.get_node_info(node, include_summary=True)

Return a multi line string of information about the given node, such as the incoming and outcoming links.

Parameters:

include_summary – boolean, if True, also include a summary of node properties

Returns:

a string summary of the node including a description of all its links and log messages

aiida.cmdline.utils.common.get_node_summary(node)

Return a multi line string with a pretty formatted summary of a Node.

Parameters:

node – a Node instance

Returns:

a string summary of the node

aiida.cmdline.utils.common.get_process_function_report(node)

Return a multi line string representation of the log messages and output of a given process function node

Parameters:

node – the node

Returns:

a string representation of the log messages

aiida.cmdline.utils.common.get_workchain_report(node: WorkChainNode, levelname, indent_size=4, max_depth=None)

Return a multi line string representation of the log messages and output of a given workchain

Parameters:

node – the workchain node

Returns:

a nested string representation of the log messages

aiida.cmdline.utils.common.is_verbose()

Return whether the configured logging verbosity is considered verbose, i.e., equal or lower to INFO level.

Note

This checks the effective logging level that is set on the CMDLINE_LOGGER. This means that it will consider the logging level set on the parent AIIDA_LOGGER if not explicitly set on itself. The level of the main logger can be manipulated from the command line through the VERBOSITY option that is available for all commands.

aiida.cmdline.utils.common.print_last_process_state_change(process_type=None)

Print the last time that a process of the specified type has changed its state.

Parameters:

process_type – optional process type for which to get the latest state change timestamp. Valid process types are either ‘calculation’ or ‘work’.

aiida.cmdline.utils.common.print_process_info(process)

Print detailed information about a process class and its process specification.

Parameters:

process – a Process class

aiida.cmdline.utils.common.print_process_spec(process_spec)

Print the process spec in a human-readable formatted way.

Parameters:

process_spec – a ProcessSpec instance

aiida.cmdline.utils.common.tabulate(table, **kwargs)

A dummy wrapper to hide the import cost of tabulate

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.

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.utils.decorators.check_circus_zmq_version(wrapper=None, enabled=None, adapter=None, proxy=<class 'FunctionWrapper'>)

Function decorator to check for the right ZMQ version before trying to run circus.

Example:

@click.command()
@check_circus_zmq_version
def do_circus_stuff():
    pass

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

aiida.cmdline.utils.decorators.deprecated_command(message)

Function decorator that will mark a click command as deprecated when invoked.

Example:

@click.command()
@deprecated_command('This command has been deprecated in AiiDA v1.0, please use 'foo' instead.)
def mycommand():
    pass

aiida.cmdline.utils.decorators.load_backend_if_not_loaded()

Load the database backend environment for the currently loaded profile.

If no profile has been loaded yet, the default profile will be loaded first. A spinner will be shown during both actions to indicate that the function is working and has not crashed, since loading can take a second.

aiida.cmdline.utils.decorators.only_if_daemon_not_running(echo_function=<function echo_critical>, message=None)

Function decorator for CLI command to print critical error and exit automatically when daemon is 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_not_running(echo_function=echo.echo_warning, message='Cannot execute while daemon is running.')
def create_node():
    pass

Parameters:

• echo_function – echo function to issue the message, should be from aiida.cmdline.utils.echo

• message – optional message to override the default message

aiida.cmdline.utils.decorators.only_if_daemon_running(echo_function=<function echo_critical>, message=None)

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

Parameters:

• echo_function – echo function to issue the message, should be from aiida.cmdline.utils.echo

• message – optional message to override the default message

aiida.cmdline.utils.decorators.requires_broker(wrapper=None, enabled=None, adapter=None, proxy=<class 'FunctionWrapper'>)

Function decorator for CLI command that requires a profile that defines a broker.

Example:

@requires_broker
def start_daemon():
    pass

If the loaded profile does not define a broker, the command will exit with a critical error.

aiida.cmdline.utils.decorators.requires_loaded_profile()

Function decorator for CLI command that requires a profile to be loaded.

Example:

@requires_loaded_profile()
def create_node():
    pass

If no profile has been loaded, the command will exit with a critical error. Most verdi commands will automatically load the default profile. So if this error is hit, it is most likely that either no profile have been defined at all or the default is unspecified.

aiida.cmdline.utils.decorators.with_broker(wrapper=None, enabled=None, adapter=None, proxy=<class 'FunctionWrapper'>)

Decorate a function injecting a aiida.brokers.broker.Broker instance.

If the currently loaded profile does not define a broker, the command is aborted.

aiida.cmdline.utils.decorators.with_dbenv()

Function decorator that will load the database environment for the currently loaded profile.

Note

if no profile has been loaded yet, the default profile will be loaded first.

Example:

@with_dbenv()
def create_node():
    from aiida.orm import Int  # note the local import
    node = Int(1).store()

aiida.cmdline.utils.decorators.with_manager(wrapper=None, enabled=None, adapter=None, proxy=<class 'FunctionWrapper'>)

Decorate a function injecting a aiida.manage.manager.Manager instance.

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.

Raises:

click.UsageError – if the config could not be loaded or no default profile exists

Returns:

the default profile name or None if no default is defined in the configuration

Convenience functions for logging output from verdi commands.

class aiida.cmdline.utils.echo.ExitCode(value)

Bases: IntEnum

Exit codes for the verdi command line.

CRITICAL = 1

DEPRECATED = 80

SUCCESS = 0

UNKNOWN = 99

__module__ = 'aiida.cmdline.utils.echo'

__new__(value)

aiida.cmdline.utils.echo._format_dictionary_json_date(dictionary, sort_keys=True)

Return a dictionary formatted as a string using the json format and converting dates to strings.

aiida.cmdline.utils.echo._format_yaml(dictionary, sort_keys=True)

Return a dictionary formatted as a string using the YAML format.

aiida.cmdline.utils.echo._format_yaml_expanded(dictionary, sort_keys=True)

Return a dictionary formatted as a string using the expanded YAML format.

aiida.cmdline.utils.echo.echo(message: Any, fg: str | None = None, bold: bool = False, nl: bool = True, err: bool = False) → None

Log a message to the cmdline logger.

Note

The message will be logged at the REPORT level but always without the log level prefix.

Parameters:

• message – the message to log.

• fg – if provided this will become the foreground color.

• bold – whether to print the messaformat bold.

• nl – whether to print a newlineaddhe end of the message.

• err – whether to log to stderr.

aiida.cmdline.utils.echo.echo_critical(message: str, bold: bool = False, nl: bool = True, err: bool = True, prefix: bool = True) → None

Log a critical error message to the cmdline logger and exit with 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.

Parameters:

• message – the message to log.

• bold – whether to format the message in bold.

• nl – whether to add a newline at the end of the message.

• err – whether to log to stderr.

• prefix – whether the message should be prefixed with a colored version of the log level.

aiida.cmdline.utils.echo.echo_debug(message: str, bold: bool = False, nl: bool = True, err: bool = False, prefix: bool = True) → None

Log a debug message to the cmdline logger.

Parameters:

• message – the message to log.

• bold – whether to format the message in bold.

• nl – whether to add a newline at the end of the message.

• err – whether to log to stderr.

• prefix – whether the message should be prefixed with a colored version of the log level.

aiida.cmdline.utils.echo.echo_deprecated(message: str, bold: bool = False, nl: bool = True, err: bool = True, exit: bool = False) → None

Log an error message to the cmdline logger, prefixed with ‘Deprecated:’ exiting with the given exit_status.

This should be used to indicate deprecated commands.

Parameters:

• message – the message to log.

• bold – whether to format the message in bold.

• nl – whether to add a newline at the end of the message.

• err – whether to log to stderr.

• exit – whether to exit after printing the message

aiida.cmdline.utils.echo.echo_dictionary(dictionary, fmt='json+date', sort_keys=True)

Log the given dictionary to stdout in the given format

Parameters:

• dictionary – the dictionary

• fmt – the format to use for printing

• sort_keys – Whether to automatically sort keys

aiida.cmdline.utils.echo.echo_error(message: str, bold: bool = False, nl: bool = True, err: bool = True, prefix: bool = True) → None

Log an error message to the cmdline logger.

Parameters:

• message – the message to log.

• bold – whether to format the message in bold.

• nl – whether to add a newline at the end of the message.

• err – whether to log to stderr.

• prefix – whether the message should be prefixed with a colored version of the log level.

aiida.cmdline.utils.echo.echo_formatted_list(collection, attributes, sort=None, highlight=None, hide=None)

Log a collection of entries as a formatted list, one entry per line.

Parameters:

• collection – a list of objects

• attributes – a list of attributes to log for each entry in the collection

• sort – optional lambda to sort the collection

• highlight – optional lambda to highlight an entry in the collection if it returns True

• hide – optional lambda to skip an entry if it returns True

aiida.cmdline.utils.echo.echo_info(message: str, bold: bool = False, nl: bool = True, err: bool = False, prefix: bool = True) → None

Log an info message to the cmdline logger.

Parameters:

• message – the message to log.

• bold – whether to format the message in bold.

• nl – whether to add a newline at the end of the message.

• err – whether to log to stderr.

• prefix – whether the message should be prefixed with a colored version of the log level.

aiida.cmdline.utils.echo.echo_report(message: str, bold: bool = False, nl: bool = True, err: bool = False, prefix: bool = True) → None

Log an report message to the cmdline logger.

Parameters:

• message – the message to log.

• bold – whether to format the message in bold.

• nl – whether to add a newline at the end of the message.

• err – whether to log to stderr.

• prefix – whether the message should be prefixed with a colored version of the log level.

aiida.cmdline.utils.echo.echo_success(message: str, bold: bool = False, nl: bool = True, err: bool = False, prefix: bool = True) → None

Log a success message to the cmdline logger.

Note

The message will be logged at the REPORT level and always with the Success: prefix.

Parameters:

• message – the message to log.

• bold – whether to format the message in bold.

• nl – whether to add a newline at the end of the message.

• err – whether to log to stderr.

• prefix – whether the message should be prefixed with a colored version of the log level.

aiida.cmdline.utils.echo.echo_tabulate(table, **kwargs)

Echo the string generated by passing table to tabulate.tabulate.

This wrapper is added in order to lazily import the tabulate package only when invoked. This helps keeping the import time of the aiida.cmdline to a minimum, which is critical for keeping tab-completion snappy.

Parameters:

• table – The table of data to echo.

• kwargs – Additional arguments passed to tabulate.tabulate().

aiida.cmdline.utils.echo.echo_warning(message: str, bold: bool = False, nl: bool = True, err: bool = False, prefix: bool = True) → None

Log a warning message to the cmdline logger.

Parameters:

• message – the message to log.

• bold – whether to format the message in bold.

• nl – whether to add a newline at the end of the message.

• err – whether to log to stderr.

• prefix – whether the message should be prefixed with a colored version of the log level.

aiida.cmdline.utils.echo.highlight_string(string: str, color: str = 'highlight') → str

Highlight a string with a certain color.

Uses click.style to highlight the string.

Parameters:

• string – The string to highlight.

• color – The color to use.

Returns:

The highlighted string.

aiida.cmdline.utils.echo.is_stdout_redirected()

Determines if the standard output is redirected.

For cases where the standard output is redirected and you want to inform the user without messing up the output. Example:

echo.echo_info("Found {} results".format(qb.count()), err=echo.is_stdout_redirected)
echo.echo(tabulate.tabulate(qb.all()))

Utilities for logging in the command line interface context.

class aiida.cmdline.utils.log.CliFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Bases: Formatter

Formatter that automatically prefixes log messages with a colored version of the log level.

__module__ = 'aiida.cmdline.utils.log'

format(record)

Format the record using the style required for the command line interface.

class aiida.cmdline.utils.log.CliHandler(level=0)

Bases: Handler

Handler for writing to the console using click.

__module__ = 'aiida.cmdline.utils.log'

emit(record)

Emit log record via click.

Can make use of special attributes ‘nl’ (whether to add newline) and ‘err’ (whether to print to stderr), which can be set via the ‘extra’ dictionary parameter of the logging methods.

Utilities for getting multi line input from the commandline.

aiida.cmdline.utils.multi_line_input.edit_comment(old_cmt='')

Call up an editor to edit comments to nodes in the database

aiida.cmdline.utils.multi_line_input.edit_multiline_template(template_name, comment_marker='#=', extension=None, **kwargs)

Open a template file for editing in a text editor.

Parameters:

• template – name of the template to use from the aiida.cmdline.templates directory.

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

Returns:

the final string value entered in the editor with all comment lines stripped or an empty string if the click.edit returned None.

Plugin aware click command Group.

class aiida.cmdline.utils.pluginable.Pluginable(*args, **kwargs)

Bases: VerdiCommandGroup

A click command group that finds and loads plugin commands lazily.

__annotations__ = {}

__init__(*args, **kwargs)

Initialize with entry point group.

__module__ = 'aiida.cmdline.utils.pluginable'

get_command(ctx, name)

Try to load a subcommand from entry points, else defer to super.

list_commands(ctx)

Add entry point names of available plugins to the command list.

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

Parameters:

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(node, path, color)

Print the contents of the directory path in the repository of the given node to stdout.

Parameters:

• node – the node

• path – directory path

Raises:

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

aiida.cmdline.utils.shell._ipython_pre_011()

Start IPython pre-0.11

aiida.cmdline.utils.shell._ipython_pre_100()

Start IPython pre-1.0.0

aiida.cmdline.utils.shell.bpython()

Start a bpython shell.

aiida.cmdline.utils.shell.get_start_namespace()

Load all default and custom modules

aiida.cmdline.utils.shell.ipython()

Start any version of IPython

aiida.cmdline.utils.shell.run_shell(interface=None)

Start the chosen external shell.

Templates for input/output of verdi commands.